Ksmp3play 0.5.1
Chapter 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 Why three different methods for random play?, Section 4.4 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 Keybindings, Section 3.2.2 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 Why three different methods for random play?, Section 4.4 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.