
                              Ksmp3play 0.5.1
                              ---------------

                    Karl Sderstrm <ks@xanadunet.net>

                              19 August 2001


-------------------------------------------------------------------------------


Copyright Notice
----------------

     Copyright (C)2001 Karl Sderstrm

     This manual is free software; you may redistribute it and/or modify it
     under the terms of the GNU General Public License as published by the
     Free Software Foundation; either version 2, or (at your option) any
     later version.


-------------------------------------------------------------------------------


Contents
--------

     1.        Introduction
     1.1.      What's new in 0.5.1
     1.2.      What's new in 0.5

     2.        Installation
     2.1.      How to obtain Ksmp3play
     2.2.      Requirements
     2.3.      Compilation and installation

     3.        Usage
     3.1.      Command line options
     3.2.      Config file
     3.3.      In-program controls
     3.4.      Song ratings and volume

     4.        Q & A
     4.1.      How am I supposed to add files to a playlist?
     4.2.      I've found a bug or thought of a feature). What do I do?
     4.3.      What are those .ks3 files?
     4.4.      Why three different methods for random play?
     4.5.      Why the name ksmp3play?


-------------------------------------------------------------------------------


1. Introduction
---------------

     Ksmp3play is an curses-based MP3 player.  This allows you to control
     the player on another computer using telnet or ssh, which might be
     useful if you have an old computer dedicated for mp3 playing.  Other
     features include song rating and volume settings for each song.

     REMEMBER THAT KSMP3PLAY IS BETA SOFTWARE!  IT MAY WORK POORLY, NOT
     WORK AT ALL, SCREW UP YOUR MP3 COLLECTION, OR EVEN DAMAGE YOUR
     COMPUTER!  USE AT OWN RISK!


1.1. What's new in 0.5.1
------------------------

        * 3 different methods for random play

        * Delay between songs can be specified

        * Better command line options

        * Bugfixes, e.g.  the one related to deleting songs from playlist


1.2. What's new in 0.5
----------------------

        * Customizable keybindings

        * File browser for adding files

        * Http streaming support

        * Bugfixes


-------------------------------------------------------------------------------


2. Installation
---------------


2.1. How to obtain Ksmp3play
----------------------------

     Ksmp3play can be downloaded from http://www.xanadunet.net/ksmp3play.
     It is also part of Debian GNU/Linux (http://www.debian.org).


2.2. Requirements
-----------------

     Ksmp3play requires the following[1]:

        * SDL 1.1.5+

        * ncurses 5+

        * SMPEG 0.4+

[1]  Ksmp3play may compile with older versions, but this has not been
     tested. 


2.3. Compilation and installation
---------------------------------

     Ksmp3play uses the GNU autotools, which should make the installation
     easy.  For more detailed installation instructions read the `INSTALL'
     file included in the package.  However, for most people the following
     should work:

          % ./configure
          % make
          % make install

     If you encounter into problems please report them to the the author at
     <ks@xanadunet.net>.


-------------------------------------------------------------------------------


3. Usage
--------


3.1. Command line options
-------------------------

          Usage: ksmp3play [OPTION ...] FILE1 [FILE2 ...]
          Options:
            -h, --help                 display this help and exit
            -v, --version              output version information and exit
            -r, --random               start in random play mode
            -l, --loop                 start in loop play mode
            -t, --title                set xterm title (0/1, default=1)
            -d, --delay                delay between songs (in seconds)
            -m, --rmethod              method used for random play (1/2/3)
            -p, --playlist             default playlist to save to

     You may specify as many files as you wish at the command line.  These
     can be either mp3, m3u, or ks3 files, or even an URL for http
     streaming.  It's not necessary to use the --playlist option if only
     one ks3 file is specified, since this file will be considered the
     default playlist.


3.2. Config file
----------------

     Ksmp3play looks for a dot-file in the user's home dir called
     .ksmp3playrc.  The format of this file is <variable> = <value>, one
     variable on each line.  Empty lines and lines beginning with # are
     ignored.

3.2.1. General config variables
-------------------------------

     The general config variables you can set in the config file are:

        * Random (0/1) - Start in random play mode

        * Loop (0/1) - Start in loop play mode

        * Volume (0-100) - Default volume

        * Set_xterm_title (0/1) - Set xterm title to currently playing song

        * Delay_between_songs (0-5) - How many seconds to pause between
          songs

        * Random_method (1-3) - Method used for random play, See Section
          4.4, `Why three different methods for random play?'  for more
          details.

     Here's an example:

          #
          # Conf file for ksmp3play
          #
          
          # Start in random play mode (0/1)
          Random = 1
          
          # Start in loop play mode (0/1)
          Loop = 1
          
          # Set xterm title to currently playing song
          Set_xterm_title = 1
          
          # Default volume (0-100)
          Volume = 80

3.2.2. Keybindings
------------------

     Since version 0.5 you can bind most of the commands in ksmp3play to
     keys of your choice.  The format is very similar to the other config
     variables.  Here's an example:

          PAUSE = p
          JUMP_TO_CURRENT = P

     This will bind the key 'p' to the pause command and the 'shift + p' to
     jump to currently playing song.  You may however want to use keys that
     can't be typed as a single character.  This is done by entering '\'
     followed by the ASCII code.  Here's an example:

          PAUSE = \32
          JUMP_TO_CURRENT = \9

     This will bind ASCII code 32 (space) to the pause command, and ASCII
     code 9 (tab) to jump to currently playing song.

     Here's a list of the keybindings you can specify:

        * JUMP_TO_CURRENT - Jump to the currently playing song.

        * NEXT - Play the next song in playlist.

        * PAUSE - Pause/Unpause

        * VOLUME_UP - Increase volume for current song.

        * VOLUME_DOWN - Decrease volume for current song.

        * EDIT_ID3 - Edit ID3 tags for currently selected (not playing)
          song.

        * RANDOM_MODE - Enable/disable random play mode.

        * LOOP_MODE - Enable/disable loop play mode.

        * HELP - Show help screen.

        * QUIT - Quit program.

        * SORT_A - Sort playlist according to Artist.

        * SORT_S - Sort playlist according to Song name.

        * SORT_T - Sort playlist according to Time.

        * SORT_R - Sort playlist according to Rating.

        * DELETE - Delete song from playlist (not from disk).

        * SAVE - Save the playlist.

        * SEARCH - Search within the playlist.

        * ADD - Add files to the playlist.

        * MOVE_UP - Move currently selected file up one row in the
          playlist.

        * MOVE_DOWN - Move currently selected file down one row in the
          playlist.


3.3. In-program controls
------------------------

     These are the default controls.  The ones marked with an asterisk may
     be customised.  See Section 3.2.2, `Keybindings' for more info.

3.3.1. Controls
---------------

        * LEFT/RIGHT - Seek within song.

        * UP/DOWN - Move up/down in playlist.

        * PGUP/PGDN - Jump up/down in playlist.

        * ENTER - Select song.

        * C - Jump to the currently playing song.  *

        * SPACE - Pause/unpause.  *

3.3.2. Song options
-------------------

        * 1-9 - Set rating of selected song.

        * +/- - Change volume for currently playing song.  *

        * E - Edit ID3 tags for selected song.  *

3.3.3. Playlist options
-----------------------

        * SHIFT + A - Sort playlist according to Artist.  *

        * SHIFT + S - Sort playlist according to Song name.  *

        * SHIFT + T - Sort playlist according to Time.  *

        * SHIFT + R - Sort playlist according to Rating.  *

        * A - Add files to playlist.  *

        * D - Delete song from playlist.  *

        * S - Save playlist.  *

        * / - Search the playlist.  *

3.3.4. File browser
-------------------

        * UP/DOWN - Navigate up/down in the current dir.

        * PGUP/PGDN - Jump up/down in the current dir.

        * ENTER - Change to the highlighted directory.

        * LEFT - Same as hitting ENTER on '..'  (cd ..).

        * RIGHT - Same as hitting ENTER on a dir (cd dir).

        * SPACE - Select/unselect the highlighted file.

        * Q - Close the file browser and load the selected files into the
          playlist.

3.3.5. Playmodes
----------------

        * R - Enable/disable random play mode.  *

        * L - Enable/disable loop play mode.  *

3.3.6. Other
------------

        * H - Show help screen.  *

        * Q - Quit.  *


3.4. Song ratings and volume
----------------------------

     Ksmp3play allows you to rate the songs in a playlist with a value
     between 1 and 9.  This affects the chance of that particular song
     being played in random play mode.  See Section 4.4, `Why three
     different methods for random play?'  for more details.

     The volume is individual for each song, with a default of 80 or what's
     specified in the config file.  This, along with the song rating, is
     saved in the .ks3 playlist.


-------------------------------------------------------------------------------


4. Q & A
--------


4.1. How am I supposed to add files to a playlist?
--------------------------------------------------

     You can do this from the command-line.  The easiest way would be to
     run ksmp3play like this:

          ksmp3play playlist.ks3 newfile1.mp3 newfile2.mp3

     Since ksmp3play will not make duplicate entries in the playlist, you
     could even do this:

          ksmp3play playlist.ks3 *mp3

     UPDATE: Ksmp3play now includes a file browsing which gives you the
     ability to browse and add files within in program.


4.2. I've found a bug or thought of a feature). What do I do?
-------------------------------------------------------------

     Send a mail to ks@xanadunet.net with a detailed description of the
     problem and/or idea, or dig into the source yourself.


4.3. What are those .ks3 files?
-------------------------------

     Ksmp3play's own playlist files have the .ks3 extension.  You will
     probably not be able to load these playlists in another MP3 player.
     The .ks3 files are organized as follows:

<mp3 file 1> <song rating> <volume><mp3 file 2> <song rating> <volume>    ...

     Ksmp3play can (at the moment) only save playlists in .ks3 format.


4.4. Why three different methods for random play?
-------------------------------------------------

     The obvious answer is: "it gives you more control".  Here are
     explanations of the three different methods used for random play.

4.4.1. Method 1
---------------

     This is the simplest of the three methods.  It will make sure that a
     song with a rating of 5 will be played 5 times more often than a song
     with a rating of 1.  A song with a rating of 6 will be played 3 times
     more often than a song with a rating of 2, and so on.

4.4.2. Method 2
---------------

     This is the default method in ksmp3play.  The difference compared to
     method 1 is that the rating will be squared before use.  This means
     that if you have two songs, one with a rating of 6 (6^2 = 36) and one
     with a rating of 4 (4^2 = 16), the song with a rating of 6 will be
     played 2.25 (36 / 16 = 2.25) times more often than the one with a
     rating of 4.

4.4.3. Method 3
---------------

     Method 3 is the most advanced method.  It will not only do the same as
     method 2, but it will also divide the rating by the length (in
     minutes) of the song.  Let me give you an example:

     Let's say you have three songs in your playlist.  Two of them are 5
     minutes long, and one is 10 minutes.  They all have the same rating
     (5) , so if you used method 1 or 2 they would all get played just as
     often (at least in the long run).  Assume you listen to these three
     songs for one hour.  That means that you have heard each song three
     times.  However the song that's 10 minutes long would have been played
     for a total of 30 minutes, and the other two for 15 minutes each.
     That doesn't seem quite right since they all have the same rating.
     The answer to this is to compensate for the song length.

     If you use method 3 instead of method 2, the total, or final, rating
     of the song that's 10 minutes would be 2.5 (rating^2 / time = 5^2 / 10
     = 2.5) and the total rating of the 5-minute songs would be 5 (5^2 / 5
     = 5).  This means that if you listen to these songs for one hour, they
     would be played for a total of 20 minutes each.


4.5. Why the name ksmp3play?
----------------------------

     Well, KS are my initials, and mp3play I think is pretty obvious.


-------------------------------------------------------------------------------


     Ksmp3play 0.5.1

     Karl Sderstrm <ks@xanadunet.net>

     19 August 2001

