=================== IMP3SH README 0.2.3 =================== This is an introductory README covering some basic topics. After reading this file, you should read the 'README.playlists' file to learn how to build playlists and setup your resource file. After you get the hang of things, there are some useful tips in the 'README.advanced' file. ------ Author ------ Eric Kratzer ----------------- Table O' Contents ----------------- 1) Introduction 2) Features 3) Performance 4) Configuring 5) Running 6) Debugging 7) Bugs/Comments ------------ 1) Introduction ------------ imp3sh is an mp3/ogg/anything player with a shell-like interface and 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. ----------- 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: # angle brackets used to describe argument [] # arg(s) in square brackets denotes it is optional 'keys' # stuff in single quotes denotes literal ('*' | ) # 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.3: [32->mp3 -07:21 home]> help Print program info----> printinfo Print copyright-------> printgpl Print help------------> help [ | 'keys'] Exit------------------> exit Play------------------> play [] Stop------------------> stop Pause-----------------> pause Resume----------------> resume Play next entry-------> next Play last entry-------> last Seek------------------> seek ( ) | [+/-] Set volume/balance----> volume [+/-] [+/-] [+/-] Mute output-----------> mute Unmute output---------> unmute Print status----------> status [ []] Print time status-----> timestatus Add list--------------> addlist Delete list-----------> dellist ('all' | ) Reset list------------> resetlist ('all' | ) Rename list-----------> renamelist Set active list-------> uselist Next active list------> nextlist Previous active list--> prevlist Set edit list---------> editlist Print list------------> printlist ['-l'] [] Print list status-----> liststatus [] Copy list entry(s)----> copyentries ('all' | | ...Add file/stream-------> addfile ... Add directory---------> addir [] Add dir (recursive)---> addiR [] Toggle read-file-tags-> readtags Play list index-------> playindex Move list index-------> moveindex Delete list index-----> delindex ('all' | | ) Weight list index-----> weightindex ('all' | | sortlist Save list-------------> savelist Load list-------------> loadlist Save all lists--------> saveall Load all lists--------> loadall Print queue-----------> printq [] Queue list index------> addq ( | ) Queue files or dirs---> fileq ... Delete queue index----> delq ('all' | | ) Change queue size-----> sizeq Set mode Once---------> once Set mode Repeat-------> repeat Set mode TrueRandom---> random Set mode SmartRandom--> srandom Set mode Learn--------> learn Set learning weights--> setlearn Set view Tag, Fname---> viewTF Set view Tag, Pth+Fn--> viewTPF Set view Path+Fname---> viewPF Set view Filename-----> viewF Toggle auto report----> report Toggle DJ mode--------> djmode Set stamp Off---------> stampOff Set stamp Time Played-> stampTP Set stamp Time Left---> stampTL Print file tag--------> printtag ( | ) Add/modify tag info---> addtag ( | ) Print id3 tag styles--> printstyles [] Print players---------> printplayers Add player------------> addplayer ['-q' | '-b'] ['-k'] eqprint Set equalizer band(s)-> eqsetband ('all' | ) Enable equalizer------> eqenable Disable equalizer-----> eqdisable Print event list------> printevents Add event-------------> addevent ['-d'] ['-p'] Delete event----------> delevent ('all' | ) Print special keys----> printkeys Modify special key----> modkey ['-n'] ( | 'default') Exec cmnds in file----> source Print command history-> history [] Add alias-------------> alias [ ] Remove alias----------> unalias Print jobs------------> jobs Flush job buffer------> fjob Send job foreground---> fg [] Send job background---> bg [] Print environment-----> env [] Set environment-------> setenv Browse text file------> mess ['-s'] Change directory------> cd ['-' | ] Toggle driver mode----> audioprocs Toggle auto recover---> recover Start xaudio decoder--> decstart Set xaudio output-----> setoutput Print debug log-------> printlog Clear debug 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. Also check the CHANGES file, since that is the location of the most up-to-data info on features. 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 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!