
				Xmmsfind
				========

This is a small plug-in for xmms (http://www.xmms.org/) that is similar to
the built-in function "jump to file" although it has some more features.
This version requires xmms 1.2.8 or greater.

It currently features case-insensitive-regular-expression-search and plays any song
selected from the search list!
Also options for queuing files and what the search string should
match (mp3 title and/or path+filename) is available.
The entire list can also be enqueued


HOW DOES IT WORK?
-----------------
To make Xmmsfind work, it must be enabled through the xmms preferences
dialog (preferences->Effects/General Plug-in), here you may also configure
Xmmsfind. (See below for details)
To start a search, simply launch the xmmsfind_remote program (installed in
/usr/local/bin by default) which will tell xmmsfind to start a search

When xmmsfind is told to launch (xmmsfind_remote) it gets the playlist from
xmms and stores it in memory. This is done only ONCE because it takes CPU on
slower machines, so if songs are added/removed while xmmsfind search-box is 
open, the changes won't be visible unless xmmsfind is restarted! This can be 
done by re-launching the xmms_remote program (no need to close xmmsfind search 
window) This behavior can be changed by the re-get options in the config 
window. Reloading the list when launched (as described above) can be disabled. 
Also, if performance isn't an issue, the list can be updated every time 
xmmsfind changes the playlist.


In the search-box, simply type the words that you want to search for.
Xmmsfind will then match _ALL_ words with the playlist (title and/or filename)
Press enter to play the selected song and it will be played or enqueued.
Regular expression characters are in in the search box.
For example:
	^The		Search for every entry starting with the word The
	Queen|Beatles	Match every instance of Queen or Beatles
Note: any word that contains special characters like ^ | ( and ) but is not
a valid regular expression, i.e. a ( with no ), will be ignored.
See grep(1) for more details regarding regular expressions.

There are two methods of enqueing songs. One uses the enqueue feature introduced
in xmms 1.2.8, the other reorders the playlist (requires random to be off).
If you want to enqueue the song, simply press ctrl-enter and it will be
played after the current song. You can also select "enqueue by default" from the
config-window, which will force an enqueue every time.

If you want to enqueue, simply hit "shift-enter". 

The configuration window:
    Match search by:
    Title/Filename:     this will match the search-string with the id3
                        title and artist or mp3 filename
	Directory path:     this will match against the full directory path of
                        the mp3 file.

    Enqueue songs by default:	Pressing enter enqueues songs
    XMMS enqueue:       Uses built in encueueing (does not edit the playlist)
    Playlist enqueue:   Will move the selected file to the position
    	    		    after the current song.
    Force random off:   Will turn shuffle mode off. (Otherwise the
    	  	 	        playlist enqueue option wont work as it should)
    Use smart enquing:  Will remember the position of the last enqueued
    	      		    song so that when you enqueue next, it will be moved
                        to _after_ the last enqueued.
                        Note that if the song changes, then the "smart"
                        offset will be reseted!
    Re-get playlist     Tells xmmsfind to re-get the playlist every time
	at launch:          it is launched. You can safely uncheck this if
                        your playlist never changes.
    Re-get playlist     re-get the playlist if xmmsfind edits the playlist
	on update:          (avoids errors if using Playlist enqueue)
    Get titleinfo...    Tells xmmsfind to query xmms for the titlestring
                        (the shown on the playlist). Unchecking this will
                        speed up the getting of the playlist, but Title/File
                        matching will only do the filename.
			    
Keyboard keys:
   Enter:               Plays the song selected in the search-list
   Control-enter:       Forces an enqueue of the song selected
   Shift-enter:	        Enqueues all songs in the search-list
                        (Both cntr-enter and shift-enter forces random off
                        if selected in the options)

WHY??
-----
Why create a plug in when there already exist a similar function in xmms?

Well, the problem with the built-in "jump to file" (or "jtf") is that you
have to have xmms in focus for it to work. This program is called externally
from the prompt, or even better, by a key-board shortcut, and there is
therefor no need for xmms to be in focus. Se INSTALL for details regarding
keyboard shortcuts.

This plug-in does also have some more features like regexps ;-)

----
If you have any suggestions or bug-reports, feel free to email me:
<iso01001@student.mdh.se>
