=======================
IMP3SH playlists README
=======================

-----------------
Table O' Contents
-----------------

1)  Intro
2)  How imp3sh playlists work
3)  Playlist Files
4)  Modifying playlists
5)  The Queue
6)  Searching through your music
7)  The resource file

   -----
1) Intro
   -----

This document is an attempt to explain how to use imp3sh for first time users.
imp3sh has many commands, but don't let that scare you --you only need to know
a couple of them to get going.

   -------------------------
2) How imp3sh playlists work
   -------------------------

imp3sh can have any number of user defined lists. Only one list can be played
at any given time, although you can edit one list while playing another. The
following commands help your manage your lists:

	addlist    <list_name>   : creates a new list
	dellist    <list_name>   : deletes the specified list
	resetlist  <list_name>   : reset the specified list (sets the weight
				   of all entries to zero.)
	renamelist <old> <new>   : renames a list
	uselist    <list_name>   : Sets the Active list (see below)
	nextlist                 : Sets the Active list to the next list 
	editlist   <list_name>   : Sets the Edit list (see below)

There are two special lists in imp3sh: the Active list, and the Edit list. The
Active list is the list that imp3sh will pick songs from to play. The Active
list (essentially a pointer) can be changed at any time to any list by using
the 'uselist' command. The Active list is denoted by a '>>>' in front of the
list's name when you use the 'liststatus' command.

If you want to edit a list while listening to another, you can make a list
the current Edit list by using the 'editlist' command. The Edit list is 
denoted by a '*' directly in front of the list's name when you use the 
'liststatus' command. The following commands will perform their actions on
the current Edit list:

	printlist, copylist, addfile, addir, addiR, playindex, moveindex,
	delindex, sortlist, savelist, loadlist, once, repeat, random, srandom,
	learn, setlearn, viewTF, viewTPF, viewPF, viewF

NOTE: The 'uselist' command sets both the Active and Edit lists to the 
      specified list.  

Each list has its own playmode. The playmode defines how imp3sh
will choose the next song from the list, and how the 'next' command behaves.
Five different playmodes are available (default is 'once'):

	Once        : plays the current song and then stop
		      (command == 'once').
	Repeat      : plays the entire list in-order and wraps when the end 
		      is reached. (command == 'repeat')
	TrueRandom  : randomly chooses songs to play. (command == 'random')
	SmartRandom : randomly chooses songs, without repeating any until the
		      entire list is played. (command == 'srandom')
	Learn       : Uses a weighted algorithm to learn what songs you like
		      to hear the most. Each list has adjustable 'play' and
		      'skip' weights. (command == 'learn')

Each list also has its own listview. A listview defines how the list is 
displayed, and also defines what the list is sorted/searched by. There are 
four available listviews (default is 'viewTF'):

	Tag, then filename     : If a list entry has a tag, it is displayed.
				 if not, only the filename is displayed.
				 (command == 'viewTF')
	Tag, then path/filename: Same as above, except the full path is 
				 displayed with the filename.
				 (command == 'viewTPF')
	Path/Filename          : The full path and filename is displayed for
				 each entry. (command == 'viewPF')
	Filename               : Only the filename (without path) is displayed
				 for each entry. (command == 'viewF')

The 'liststatus' command will display information about all the lists in your
current imp3sh session:


[38->mp3 -01:29 ekratzer]> liststatus 
--> queue
	Entries   : 6/[1024]
	Position  : 5 <Delerium - Silence - Sanctuary remix.mp3>
>>> *mp3
	Play mode : Learn
	List view : Tag, then Filename
	Entry(s)  : 59
	Position  : 38 <Delerium - Silence - Sanctuary remix.mp3>
	Status    : 37% positive, 40% negative
	Weights   : play.1 skip.1 global.1
--> sfx
	Play mode : SmartRandom
	List view : Filename
	Entry(s)  : 112
	Position  : 0 <1.wav>
	Status    : 0% played, 0% skipped


In this example, there are two lists: 'mp3' and 'sfx', with 'mp3' being both
the Active and Edit lists. The 'queue' is not a list and has special
behaviors. Read the section below on the Queue for more information.

   --------------
3) Playlist Files
   --------------

There are two types of playlist files in imp3sh: those created with 
'savelist', and those created with 'saveall'.

Both commands save tag information and the current weight of each stream:

	#EXT_INFO -6 O'Fortuna - Apotheosis - 1999 - Kratzcom - Gothic Rock
	/home/ekratzer/personal/music/Apotheosis - O Fortuna (remix).mp3

The 'saveall' command also stores information about each list in the playlist
file:

	#LIST_INFO mp3 Random viewTF 45 1 1

Thats the list name, playmode, listview, current position, play weight, and 
skip weight. The entries that are stored in a particular list are listed after
that list's '#LIST_INFO' definition.

The 'savelist' command will save the current Edit list's entries to the
specified file. The generated file can be called as an argument to 'loadlist',
which will load the entries into the current Edit list.

The 'saveall' command saves ALL lists (including their options and settings) to
the specified file. The generated file can be called as an argument to
'loadall', which will create (if they do not already exists) all lists that 
were defined, and copy each list's saved entried back into the lists.

I find it useful to create an EXT (exit) event that will save the current state
of my lists:

	addevent -q -e saveall ~/.imp3sh_lists

This will allow any lists using the learning and smartrandom modes to remain
updated.


   -------------------
4) Modifying playlists
   -------------------

Playlists can be modified in a variety of ways. This section will present 
methods to add and copy list entries.

	Adding songs from a filesystem
	------------------------------

	There are two commands for adding songs from the filesysyem: 'addir' 
	and 'addiR'. The 'addir' command will search the specified directory
	for playable songs, while the 'addiR' command will recursively search
	that directory. 

	The 'readtags' command lets you toggle whether or not you want imp3sh
	to attempt to incorporate tag information into the playlist. This 
	option is on by default, and will cause the addiX commands to take
	more time to complete.

	Only files imp3sh knows how to play will be added to the playlist. MP3
	and OGG files are supported natively. Other filetypes can be supported
	by using external players (a filetype list is given to each addplayer
	command, see the 'EXTERNAL.players' file for examples.)

	An example:

	1) Create (if you haven't already) and choose a list:

		>addlist temp
		:-> "temp" list created successfully
		
		OR (if you already created a list)...

		>editlist temp
		:-> Edit list set to "temp"

	2) Use an addiX command on the list:

		>addiR /mnt/music/
		:-> Recursively adding playable files in "/mnt/music" ...
		:-> Added 1989 file(s) to "temp" list
		
	3) Optionally sort the list:
		
		>sortlist
		:-> Sorted 1989 entries in "temp" list

	Note: The addiX commands will automatically sort the entries they
	      find before adding them to the Edit list. The entries are sorted
	      according to the Edit list's listview.

	
	Copying songs between lists
	---------------------------

	imp3sh allows you to use grep-like matching to copy list entries 
	between lists. I usually add all of my songs to a 'temp' list, and
	then use 'copylist' commands to break down my songs into smaller
	more organized playlists.

	Continuing the example from above, say that we wanted to make two 
	more lists: one containing classical music and one containing songs
	by Nine Inch Nails:

	1) Create two more lists:

		>addlist instrumental
		:-> "instrumental" list created successfully
		>addlist nin
		:-> "nin" list created successfully
	
	2) Copy all list entries with "classical" mentioned in their tags 
	   from the 'temp" list to the 'instrumental' list:

		>editlist instrumental
		:-> Edit list set to "instrumental"
		>copylist temp classical
		:-> 215 entry(s) added to "instrumental" list

	3) Copy all Nine Inch Nails tracks to the 'nin' list:

		>editlist nin
		:-> Edit list set to "nin"
		>copylist temp nine inch nails
		OR
		>copylist temp "Nine Inch Nails"
		OR
		>copylist temp nine nails
		ETC..
		:-> 32 entry(s) added to "nin" list

	You can also give an index list and/or range to copy:

		>copylist temp 1,4,5-20,45,90-120

	Or you can include logical NOT operators by placing a '!' in front of
	a token:

		>copylist temp "Nine Inch Nails" !fragile

	See the section below on searching through your music for more and
	better examples on how to use <grep_strings>. See the Queue section
	for better examples on how to use <index_spec> and <index_spec_lists>.

   ---------
5) The Queue
   ---------

As of 0.2.0 imp3sh has a controllable song Queue. The Queue serves two
purposes:  to keep track of songs that have been played in the past, and to
allow you to queue songs to be played in the future.

Every time a new song is played, it is stored in the Queue. So, entering the
'last' command or using the 'Page Down' key will allow you to cycle back
through the songs you just played, in reverse order. 

You can also tell imp3sh to play specific songs in the future. Say you wanted
to listen to the Orbital album "Insides" track-by-track. You could:

	>addq orbital insides

to add those 8 tracks to the queue in-order (considering that your current
Edit playlist has that album in it.)

You can also queue an index or an index range from the current Active list:

	>addq 4     # queue Edit list index number 4

	>addq 7-23  # queue indices 7 through 23 (inclusive) from Edit List

	>addq 2,3,567,1106-1245 # add a buch of songs :)

You can also clear, print, search, and resize the queue at will (type
'help queue' to see the queue commands.)

If you give the 'play' command a directory instead of a filename, imp3sh
will recursively search, sort, and queue all playable songs beneath that
directory.

imp3sh's aliasing abilities can be used to accelerate manipulation of the
queue. Here is a command that creates an alias 'eub' that will clear the
queue, adds a particular Euphoria album (in-order), and starts playing:

        >alias eub editlist euph;stop;clearq;addq euph "blue 1" !ibiza;play


   ----------------------------
6) Searching through your music
   ----------------------------

Adding songs to your lists and queue would be kind of useless if you 
weren't able to search for your criteria first. imp3sh offers commands to 
search the lists and queue, so you will know what you are copy/add/queueing.

Two commands ('printlist', and 'printq') allow you to display and
search-through your music. These commands without any arguments will display
the entire contents of their respective list/queue. If you wish to
search the list for your criteria, you can add any number of grep strings:

For example, to search the contents of your master list for songs by
Tori Amos:

	>printlist tori

	or

	>printlist tori amos

	or

	>printlist "Tori Amos"

	etc...

Note: Using parenthesis will allow you to include white_space in your search.

Note: imp3sh uses the same rules as emacs' "I Search" when it comes to case-
      sensitive searches. imp3sh will only make the search case-sensitive if
      there are one or more capital letters in the search string.

You can also specify a logical "not" in your search criteria by placing a "!" 
in front of a grep string. For example, to search for all songs by Euphoria 
that were _not_ mixed by Alex Gold:

	>printlist Euphoria !alex

	or

	>printlist euph !alex !gold

	or

	>printlist euphoria "!Alex Gold"

	etc...
	

Notice that using the command 'printlist eUphoria' will yield no results
since the capital 'U' will force a case-sensitive search.

You can use an arbitrary number of grep strings to narrow down your search to
precisely what you want. 

Note: Any command that accepts a grep string (there are quite a few) will work
      in the same fashion as the 'printlist' and 'printq' commands.

When you print a list or the queue, each entry will be proceeded by '|||'
or '>>>'. The entry that is proceeded by '>>>' denotes the current position of
the list or queue.

   -----------------
7) The resource file
   -----------------

Every time imp3sh is run, it searches for a resource file named ".imp3rc" in
your home directory. imp3sh will execute any commands that are in this file.
You can use ANY command imp3sh can execute in the resource file. Some 
common things done in the resource file are: loading playlists, setting the
'Active' list and setting up other options. 

Since imp3sh is also a shell, you can use the resource file to launch
applications if you wish (i.e., emacs, xterm, netscape, etc.)

There is an example resource file included with the imp3sh source code. This 
file is called "EXAMPLE.imp3rc". Please take a look at the file for more
information.

You can specify a different file to be used as the resource file by giving
"-r <file_name>" on the command line.

A list of common commands used in the resource file:

   'loadall <file_name>'                    -- load the playlist file
                                                  <file_name>

   'addevent ['-q'] <seconds> <command>        -- add events

   'addplayer ['-q' | '-b'] <name> <command> <format_list>  -- add external
                                                               players

   'eqsetband ('*' | <band_number_list>) <band_value_list>' -- setup the 
                                                               equalizer

   'uselist <list_name>'                       -- set the Active list
	
   'stampXX'              -- setup the prompt mode

   'viewXX'               -- setup the listview

   'recover' -- turn the 'Auto Restart' feature on. This will automatically 
                restart imp3sh's decoder process if it dies. If you have a beta
   	        version of the libvorbis libraries installed, this is a good
 	        option to turn on.

   'report'  -- turn on the 'Auto Report' feature.

   'play'    -- use this towards the end of your resource file if you wish
                imp3sh to start playing upon startup.


Mail any questions/comments to kman_can@yahoo.com
