=================== 
IMP3SH README 0.2.1 
===================

This is an introductory README covering some very basic topics. After
reading this file, you should read the 'README.playlists' file to
learn how to build your playlists and setup your resource file.

After you get the hang of things, you can read the 'README.advanced'
file to learn how to use the more powerful features of imp3sh.

Read the 'INSTALL' file for information on requirements and building.

------
Author
------

Eric Kratzer <kman_can@yahoo.com>

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

1)   Introduction
2)   Features
3)   Performance
4)   Configuring
5)   Running
6)   Debugging 
7)   Bugs/Comments

   ------------
1) Introduction
   ------------

imp3sh is a true command-line mp3 player with over 90 built-in commands
and hotkeys. imp3sh has most of the mp3 and playlist control functions (minus
gfx, of course) of fully-featured mp3-players like xmms, plus a whole lot 
more...

If you have thousands (or tens of thousands) of songs in many different
formats, then imp3sh is for you. imp3sh allows you to store and search through
huge lists of songs with light-speed. imp3sh can also be configured to use 
other command-line players to support playback of any file format (MP3, and
Ogg/Vorbis are supported natively.) 

imp3sh is also a terminal shell. It has job/environment/alias controls,
command/file completion, command history, and more. imp3sh does not intend
or even attempt to be a shell replacement for POSIX compliant shells like
bash! I just implemented the shell functionality that I use most (an not even
all of that yet :) If you need full shell functionality, you can always run 
bash on top of imp3sh and still have your playlists and queue updating in the
background.

imp3sh uses the Xaudio Asynchronous Library for decoding MP3's, and the 
libogg and libvorbis libraries in conjunction with Xaudio to decode Ogg/Vorbis
files.

   --------
2) Features
   --------

This section attempts to give a summary of imp3sh's features. These lists are
not exhaustive.

   Playlists and song playback
   ---------------------------

	Play, pause, resume, stop, next, last, seek, and jump via commands or
        hotkeys.
   
	Play files and URLs (HTTP, FTP, or UDP.)

	Create/save/edit any number of user-defined lists.

	Volume and balance controls via commands or hotkeys.

	10 band equalizer.

	Status via command or hotkey showing song information, options, and
        memory usage.

	Can use any number of external players to play formats not natively
	supported (i.e., modules, midi, video, wavs, etc.) Able to suppress
	or buffer external players' console output.

	Reads song tag information (if available) and stores it in list. Can
        read id3, ogg-vorbis and tags from a variety of modules formats (i.e.,
        s3m, xm, it, 669, etc.) Any fixed-location, fixed-length tag can be
        easily supported.
 
	Add/Modify/View id3 tag information or module tags (ogg coming soon).

	Recursive searching of directories for MP3/Ogg files and all other
        file-types supported by external players.

	Learning, SmartRandom, TrueRandom, Repeat, and Once playmodes.

	Selective viewing/queuing of lists with powerful grep functionality. 
        Can grep via tag and path/filename with assignable priority.

	Move, delete, sort, save, and load lists and queues.

	Time-stamped prompt available showing 'active' list/queue position,
        and either time-left, or time-played of current song in real-time.

	Playlist status information by command or hotkey. 
   
	Xaudio auto-recover and error/debug logging.
      
	A 'fun' (or 'stupid', you pick) DJ mode

	Named-pipe input/output for using imp3sh as a back-end. Also included
	is an example pipe-client, and a socket-server and socket-client for
	remote access of imp3sh.

   Shell/Other features
   --------------------

	Able to execute multiple commands per line (separated by ';'.)

	Powerful aliasing.

	Command and file completion (including built-ins and aliases.)

	Command history.

	Bash style command shortcuts (i.e., "Ctrl-L", "Ctrl-E", "Ctrl-A", 
        "Ctrl-K", "Ctrl-N", "Ctrl-P", "Ctrl-Z", arrow-keys, etc.)

	Powerful event system: Can define any number of Timed, End-Of-List,
	End-Of-Queue, End-Of-Stream, or Start-Of-Stream events. Events can 
	be made persistent.

	Bash-style job control, plus job output-buffering.

	Console buffering and built-in-command output-buffering ('Mess'
        buffer.)

	Able to execute commands in any file ('sourcing'.)

	Environment variable setting/viewing/searching.
   
   
   ...and probably some more stuff that I forgot. Read the 'README.playlists' 
   file to learn more about using the lists and queue. Use the help command
   with a grep-string(s) to learn more about particular functionality. For
   example:

   >help event    # to see event commands

   >help queue    # to see queue commands

   >help list     # to see list manipulation commands

   >help player   # to see external player-list manipulation commands

   >help view     # to see how to change the list view

   >help stamp    # to see how to change the time-stamp mode
   
   >help eq       # to see the equalizer manipulation commands

   ...etc, etc.

   or just enter 'help' to look through all the help.
	
   To see a particular command's arguments, just type in the command without 
   any arguments.


   -----------
3) Performance
   -----------

imp3sh is able to handle _huge_ playlists with ease. I have produced some
benchmarks running on my system: Redhat 7.1, Duron 600, 256MB. The benchmarks
show how long it takes to do some common operations (viewing, searching, and 
sorting) with very large playlists. In order to achieve playlists of this size,
I had to use alot of duplicate entries. The existence of duplicate entries in
the playlists has no effect on the results of these tests.


Description of tests:

Test 1 = Display playlist (buffered)
         Command == 'printlist'

Test 2 = Search w/3 qualifiers and display (buffered)
         Command == 'printlist euphoria "Blue 1" !ibiza'

Test 3 = Playlist sort, listview set to: 'Tag, then Filename'
         Command == 'viewTF;sortlist' 


Results of tests:

# playlist entries        Test 1          Test 2         Test 3
------------------        ------          ------         ------
    10,000               <1 second       <1 second       1 second
    50,000               <1 second       <1 second       4 seconds
   100,000              1.5 seconds     1.5 seconds      8 seconds
   250,000                3 seconds       3 seconds     20 seconds
   500,000                5 seconds       5 seconds     65 seconds    


As the list size gets huge, so does the amount of RAM you need :) But it is not
too bad. With 500,000 entries and the output buffer full, imp3sh was consuming
around 60 MBytes of RAM. With 2,048 entries (the default list size), imp3sh
should never even come near to using 1 MByte of RAM. Compare this to XMMS, 
which requires around 20 or so MBytes of RAM with ZERO playlist entries (please
correct me if I am wrong here.)


   -----------
4) Configuring
   -----------

imp3sh reads a resource file (".imp3rc") from your home directory upon
startup. You can use any command imp3sh can execute in this file [i.e., load
playlists, search for MP3's, set the playmode, setup aliases and environment 
variables, spawn a few terminals or emacs or netscape or whatever.] 

Note: imp3sh does not require a resource file to run.

You can either create your own resource file, or copy, rename, and modify the
included example ("EXAMPLE.imp3rc"). Also read "README.playlists" for more
info on the resource file.

Note: a command-line option "-r" will let you specify the location of the 
      resource file, otherwise, imp3sh looks for "~/.imp3rc"

   -------
5) Running
   -------

imp3sh looks similar to other shells (except for time-stamp mode.) Most of the
shell functionality that does work works like bash or tcsh. 

The command definitions use the following notation:

  <arg_name>         # angle brackets used to describe argument

  [<arg_name>]       # arg(s) in square brackets denotes it is optional

  'keys'             # stuff in single quotes denotes literal

  ('*' | <arg_name>) # vertical bar denotes logical XOR


Here is the list of built-in commands and special keys that can be viewed by
using the built-in 'help' command in version 0.2.2:

[32->mp3 -07:21 home]> help
Print copyright-------> printgpl
Print help------------> help [<grep_strings> | 'keys']
Exit------------------> exit
 
Play------------------> play [<stream_name>]
Stop------------------> stop
Pause-----------------> pause
Resume----------------> resume
Play next entry-------> next
Play last entry-------> last
Seek------------------> seek (<offset> <scale>) | [+/-]<percent>
Set volume/balance----> volume [+/-]<master_vol> [+/-]<pcm_vol> [+/-]<balance>
Mute output-----------> mute
Unmute output---------> unmute
Print status----------> status
 
Add list--------------> addlist <list_name>
Delete list-----------> dellist ('*' | <list_name>)
Reset list------------> resetlist ('*' | <list_name>)
Rename list-----------> renamelist <list_name> <new_name>
Set active list-------> uselist <list_name>
Next active list------> nextlist
Set edit list---------> editlist <list_name>
 
Print list------------> printlist ['-l'] [<grep_strings>]
Print list status-----> liststatus [<list_name>]
 
Copy list entry(s)----> copylist <source_list> ('*' | <index_spec_list> | <gre...
Add file/stream-------> addfile <stream_name1> <stream_name2> ...
Add directory---------> addir [<path_name>]
Add dir (recursive)---> addiR [<path_name>]
Toggle read-file-tags-> readtags
 
Play list index-------> playindex <index>

Move list index-------> moveindex <targ_index> <dest_index>
Delete list index-----> delindex ('*' | <index_spec> | <grep_strings>)
Sort list-------------> sortlist
Save list-------------> savelist <file_name>
Load list-------------> loadlist <file_name>
 
Save all lists--------> saveall <file_name>
Load all lists--------> loadall <file_name>
 
Print queue-----------> printq [<grep_strings>]
Queue list index------> addq (<index_spec_list> | <grep_strings>)
Queue files or dirs---> fileq <stream_name1> <stream_name2> ...
Clear queue-----------> clearq
Change queue size-----> sizeq <maximum_size>
 
Set mode Once---------> once
Set mode Repeat-------> repeat
Set mode TrueRandom---> random
Set mode SmartRandom--> srandom
 
Set mode Learn--------> learn
Set learning weights--> setlearn <play_weight> <skip_weight>
 
Set listview 'TF'-----> viewTF
Set listview 'TPF'----> viewTPF
Set listview 'PF'-----> viewPF
Set listview 'F'------> viewF
 
Toggle auto report----> report
Toggle DJ mode--------> djmode
 
Set timestamp 'Off'---> stampOff
Set timestamp 'TP'----> stampTP
Set timestamp 'TL'----> stampTL
 
Print file tag--------> printtag (<list_index> | <file_name>)
Add/modify tag info---> addtag (<list_index> | <file_name>) <options...>
Print id3 tag styles--> printstyles [<grep_strings>]
 
Print players---------> printplayers
Add player------------> addplayer ['-q' | '-b'] ['-k'] <name> <command> <filet... 
Print equalizer bands-> eqprint
Set equalizer band(s)-> eqsetband ('*' | <band_number_list>) <band_value_list>
Enable equalizer------> eqenable
Disable equalizer-----> eqdisable
 
Print event list------> printevents
Add event-------------> addevent ['-q'] ['-p'] <type_options...> <command>
Delete event----------> delevent ('*' | <event_id>)
 
Exec cmnds in file----> source <file_name>
Print command history-> history [<grep_strings>]
Add alias-------------> alias [<alias_name> <command>]
Remove alias----------> unalias <alias_name>
 
Print jobs------------> jobs
Flush job buffer------> fjob <job_number>
Send job foreground---> fg [<job_number>]
Send job background---> bg [<job_number>]
 
Print environment-----> env [<grep_strings>]
Set environment-------> setenv <name> <value>
Change directory------> cd ['-' | <path_name>]
 
Toggle driver mode----> audioprocs
Toggle auto recover---> recover
Start xaudio decoder--> decstart
Set xaudio output-----> setoutput <full_path_name>
Print log-------------> printlog
Clear log-------------> clearlog
 
Next song-------------> Page-Up
Last song-------------> Page-Down
Fast-forward----------> Home
Rewind----------------> End
Play------------------> F1
Pause-----------------> F2
Resume----------------> F3
Stop------------------> F4
Increase master vol---> F5
Decrease master vol---> F6
Increase pcm vol------> F7
Decrease pcm vol------> F8
Pan balance left------> F9
Pan balance right-----> F10
Print status----------> F11
Print list status-----> F12


Most of these commands are pretty much self-explanatory. If you don't know 
what it does or how it works exactly, just futz with it a bit, or try entering
the command by itself to see if there is any extra built-in help.

The 'addtag' and 'addevent' commands have a lot of different options and will
display more detailed help when entered with no arguments.

   ---------
6) Debugging
   ---------

If you encounter problems with xaudio playback, check the decoder log for 
debug/error messages by typing "printlog". All messages from the Xaudio
decoder are stored in the log. [Input/output and HTTP/FTP debug/error
messages are the most common.]

If you encounter problems using external players, don't use the '-q' or '-b'
options to 'addplayer', this will let the external player's console output
to be seen on the console (instead of ignored, or buffered, respectively.) 
You can more easily see what the problem is if you can see the external
player's error messages.

   ---------------
7) Bugs / Comments
   ---------------

Please email all bugs or comments to <kman_can@yahoo.com> with "imp3sh"
somewhere in the subject field. I am continuosly adding functionality
and would be happy to fix any bugs or take functional suggestions.

Enjoy!
