playmp3list V 0.9
=================

1. OVERVIEW
2. INSTALLATION
3. USAGE
4. DEFAULT CONTROL KEYS
5. RC FILE EDITING
6. CONTACT

1. OVERVIEW
-----------

playmp3list is an ncurses mp3 player for Linux.
Main features:

o Displays a large scrollable playlist
o Browse playlists, directories and 'virtual playlists', even while playing
o Fully configurable key mappings and color schemes in a playmp3listrc file
o Real-time toggling of shuffle / repeat modes
o Next, Previous, Play, Pause, Stop, Fast-forward and Rewind functions
o PCM Volume changing
o Time elapsed and song format displays
o Optional ID3v1 tag extraction in the playlist
o Full / short (beautified) filename display in playlist
o Command-line options to quickly override rc file settings
o Uses mpg123 for decoding

2. INSTALLATION
---------------

First of all, make sure that you have mpg123 installed correctly. Version 0.59r
or higher is required. Get it working before proceeding. Take note of any
unusual command-line parameters you need on your system, and add them to your
rc file (chances are you will not need to) - see below.

Extract the source files with a command like:

tar zxvf playmp3list-0.9.tar.gz

Then,  cd playmp3list-0.9

Take a look at the settings in the 'playmp3list.h' file and check that 
they correspond to your system. Especially, if you have a mono screen!
(Note: You may also need to select the 'mono' theme in the rc file - see below)
Alright, now you need to configure the Makefiles for your system and then
compile it:

./configure
make

If that is succesful, you'll probably want to run:

make install
make clean

Don't forget to copy the included playmp3listrc file as either
~/.playmp3listrc or /etc/playmp3listrc, and customize it before running!

If you get stuck, please e-mail me! I have no idea whether this program is
actually WORKING on peoples machines out there unless you tell me!
Remember, after making any changes to the source code, re-compile it.

If you have some programming know-how, try hacking the code,
it's really simple :-). Please send me any changes or bug-fixes!

3. USAGE
--------

Okay, usage is really simple, just use one of the following:

playmp3list [options] <playlist>
playmp3list [options] <directory>
playmp3list [options] <song> [<song>...]

Type playmp3list without parameters to get a list of command-line options.
You can press '?' or 'H' in the program to get a quick list of the default
control keys!

If you just want to start browsing (and playing) the current directory, try
something like this:

playmp3list -ap .

To extract and display ID3v1 tag info in the playlist, use the -i option.

(Note: This may take a while, especially with a large playlist or directory,
 but the program will run at full speed thereafter.)

You don't know how to make a playlist file?!?!?!
Okay, either get a program to edit playlists (there are lots around), or
make a shell script, similar to this, which will generate a playlist for you:

ls /mp3/Songs/*.mp3 > ~/playlist.m3u
ls /mp3/Humour/*.mp3 >> ~/playlist.m3u

This will create the playlist ~/playlist.m3u with the full path to all those
mp3 files in it. Now, whenever you add/delete files, just run the script and
your playlist will be up-to-date, or even automate the process with cron.

Once you run the program, it will (hopefully) pop up with a nice window
containing a standard scrollable list of files (your playlist) and a bar at
the bottom with the song name, playback state, and more info.

(Note: If you edited the rc file, and the screen is completely black, you
 have probably corrupted the theme section, so restore it from the original
 distfile - see below.)

The program is controlled with the following default keys:

4. DEFAULT CONTROL KEYS
-----------------------

Z / Y		Previous
X		Play
C		Pause
V		Stop
B / SPACE	Next
LEFT / N	Rewind
RIGHT / M	Fast-forward
ENTER		Play highlighted song / browse hilighted directory or playlist
UP, DN		Move up/down playlist
PGUP, PGDN	Page up/down playlist
HOME, END	Go to top/bottom of playlist
S		Toggle shuffle mode
R		Toggle repeat mode
F		Toggle full/short filename display in playlist
T		Toggle time elapsed/remaining display
A		Alphabetise by filename (ignores path)
< / -		Decrease volume by 1%
> / +		Increase volume by 1%
? / H		Display the default control keys
/, ~		Jump to root or home directory
BKSP		Jump to parent directory
^L / ^R		Redraw window
Q		Quit

If you want to customize the control keys, edit your ~/.playmp3listrc file:

5. RC FILE EDITING
------------------

The ~/.playmplistrc file can be edited to configure the program's key mappings,
startup settings and color schemes (themes). Use the supplied file as a
starting point, as it contains all the function, setting and element names!

Each keyboard mapping is defined in the format <function> <key> [<key>...],
or in other words, the function name followed by a list of keys to be mapped
to that function.

Each setting is defined in the format <setting> <value>. You can supply
additional command-line parameters to pass to mpg123, for example to set your
sound device (-a <device>), force-to-mono (-m) etc. Edit the 'mpg123_params'
setting and add them there. The 'theme' setting must be the name of the theme
to use, as defined below.

Each theme is a separate section, with the heading '.theme <theme_name>'.
Each theme element is defined in the format <element> <fg> <bg> <attr>, where
'fg' is the text color, 'bg' is the background color and attr is a text
attribute.

Needless to say, themes can easily be shared with other people, so if you make
a particularily good one, mail it to me and I'll include it in future releases!

6. CONTACT
----------

Well, that's about it for now.
Send comments/suggestions/patches/money/flames to me via e-mail, 
  urban@rucus.ru.ac.za
Check my homepage for new versions: 
  http://rucus.ru.ac.za/~urban/playmp3list.html
