====================== IMP3SH advanced README ====================== This file attempts to cover some of the more advanced features of imp3sh. The CHANGES file also contains details about some of imp3sh's more advanced features, although it is not organized very well :) If you haven't read the 'README' or 'README.playlists' files, you should probably do so before reading this one. ----------------- Table O' Contents ----------------- These are in no particular order: 1) Job control 2) Buffering 3) Aliasing 4) External players 5) Event system 6) Tag editing 7) Equalizer 8) Audio drivers 9) Everything else ----------- 1) Job control ----------- imp3sh has bash-style job control. You can launch programs that use the console, and you can launch programs in the background (i.e., with an '&') You can stop programs that control the console with 'CTRL-Z', and the modify their job state with the 'fg' (foreground) and 'bg' (background) commands. imp3sh will buffer all output from a process if it is launched in the background or if it is launched by an event when the console is occupied by another process or imp3sh's own output buffer. The output from stdout and stderr is stored until the process terminates, in which the process's output is flushed to imp3sh's console buffer. Alternatively, the user can flush the process' buffer by using the 'fjob' command. 'fjob ' will dump the current contents of the process buffer for to the screen. Current jobs are displayed by using the 'jobs' command, which was also shows status info about the job buffers. The user can bring the buffered process back to the foreground by using the 'fg' command, however, the process will not be able to recieve input from stdin (break [Ctrl-C] and stop [Ctrl-Z] should still work, though.) If a process is started in the foreground (no '&') and then stopped (Ctrl-Z), it can still be sent to the background ('bg') or foreground ('fg') while properly transfering control of stdin. I added job-buffering because sometimes I am using an app on the console and I forget that I have events waiting to execute. This way, any event can run and all the output will be stored for me to look at later. The job buffers are circular with a maximum of 256 entries of (upto) 8192 bytes each. Each entry allocated as needed. --------- 2) Buffering --------- All of imp3sh's internal commands are buffered via the built-in 'Mess' buffer (The name 'Mess' was inspired from the standard unix commands 'more' and 'less'.) If you use a built-in command whose output would take more than one screenful, you will see the following prompt at the bottom of the screen: --Mess--(5%)-- The percentage refers to how much of the buffered output has been displayed. At this point, you have several options: 1) Press 'q' or 'Q' to exit out of the 'Mess' buffer. 2) Press '\n' (return) to scroll one line down 3) Press 'b' or 'B' to scroll one screen backwards 4) Press 'y' or 'Y' to scroll one line backwards 5) Press '\', enter a string, and press return to search for that string 6) Press 'n' or 'N' to search again with the last string entered, or 4) Press any other key to scroll one screen forward. To keeps things pretty, the output buffer will chop any entry that is longer than the current console width, adding the string "...". If you would like to see the entire line, you can always resize the terminal window. imp3sh also has a console-buffer. imp3sh output and messages will be buffered if the console is in use by another app or imp3sh's own output buffer. The buffered console messages are displayed at the next earliest convenience (simliar to bash.) Output from buffered jobs is also flushed to the console buffer (see the Job Control section above.) -------- 3) Aliasing -------- imp3sh can use aliases for commands or groups of commands. The 'alias' and 'unalias' commands allow you to manipulate the alias list. For example, to see colors with the 'ls' command: alias ls ls --color=tty Multiple commands can be aliased to a single command using semicolons. For example, here is an aliased command that will update your "classical" list: alias update editlist classical;delindex *;addiR ~/music/classical/ Notice that the 'alias' command is treated differently with respect to semicolons. Normally, the commands seperated by semicolons would all be executed immediately. In the above example, however, everything after "update" is treated as the alias. The 'addevent' command also behaves like this. Because of their special behavior, the 'alias' and 'addevent' commands cannot be aliased themselves. Shell variables and the '~' character will not be expanded until the alias is used. Use 'alias' without any arguments to see the current alias list. Use 'unalias' with the name of an alias to remove that alias. ---------------- 4) External players ---------------- imp3sh can use other, command-line players (like 'mikmod', or 'timidity') to play different file formats. Volume controls, the equalizer, muting, seeking, and time-stamped prompts are not available when using external players. Use 'addplayer' and 'printplayers' to add/view external players. A '-q' option to 'addplayer' will suppress any console output from the external player. A '-b' option (instead of '-q'), will buffer all of the output from the external player. The buffered output is viewable via the 'fjob' command. When using 'addir' or 'addiR', imp3sh will also add file-types that are supported by any external players. These filetypes are defined as an argument to the 'addplayer' command (see the 'EXTERNAL.players' file for examples.) ------------ 5) Event system ------------ imp3sh has an event system that will store commands to be executed at a specific time, interval of time, or when specific things happen. Here is the built-in help as of version 0.2.1a: :-| Add event-------------> addevent ['-q'] ['-p'] :-> Use '-p' to make event persistent (repeating) :-> Use '-q' to disable event alerts (quiet) :-> For , use one of the following: 1) -t : TMD (timed) event 2) -l ('*' | ) : EOL (end of list) event 3) -q : EOQ (end of queue) event 4) -s ('*' | ) : EOS (end of stream) event 5) -r ('*' | ) : SOS (start of stream) event 6) -e : EXT (exit) event :-> For , enter command(s) as you would by themselves Timed events have a one second resolution. EOL events can only occur in Once, Repeat, and SmartRandom playmodes. A can be given for EOS and SOS events. This string will be matched against the _end_ of a filename/URL. For example, addevent -p -s .MP3 echo "Hello" will create an event that prints "Hello" to the console every time a file whose last four bytes (length of ".MP3") match ".MP3". Please contact me @ kman_can@yahoo.com if you have questions regarding the event system. ----------- 6) Tag editing ----------- imp3sh can read/write id3 tags from MP3 files. imp3sh also has the ability to read/write fixed-location string identifiers from files. Any file type that has an identifier (i.e., song title) in a fixed location can be supported. Current supported formats are: .XM .ULT .STX .S3M .MTM .MOD .M15 .IT .IMF .GDM .FAR .DSM .AMF .669 The 'addiX' commands will attempt to read tag information from files if the file is determined to be one of the above types. The 'printtag' command takes a filename or a master-list index and tries to find any tag information for that file. imp3sh will display the tag info if it knows how to find it and if it exists in that file. The 'addtag' command can be used to add/modify the tag information of MP3s and any other supported fixed-location formats. 'addtag' takes a filename or a master-list index and file-type-dependant options. The id3 tag options are: :-| Add/Modify tag info---> addtag ( | ) ... ID3 options are: -n : Add/Modify song name -a : Add/Modify artist name -l : Add/Modify album name -y : Add/Modify year -o : Add/Modify note -s