======================= 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 : creates a new list dellist : deletes the specified list resetlist : reset the specified list (sets the weight of all entries to zero.) renamelist : renames a list uselist : Sets the Active list (see below) nextlist : Sets the Active list to the next list editlist : 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 >>> *mp3 Play mode : Learn List view : Tag, then Filename Entry(s) : 59 Position : 38 Status : 37% liked, 40% dis-liked 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 . See the Queue section for better examples on how to use and . --------- 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 " on the command line. A list of common commands used in the resource file: 'loadall ' -- load the playlist file 'addevent ['-q'] -- add events 'addplayer ['-q' | '-b'] -- add external players 'eqsetband ('*' | ) ' -- setup the equalizer 'uselist ' -- 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