
				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.

If you use multiple sessions, you can specify which xmms session to use
by giving xmmsfind_remote the argument --session or -n followed by the 
xmms session number.  If no argument is supplied xmmsfind_remote will
use the first session found (usually 0).

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 or refreshed
with the refresh button or F5.  The list is always refreshed if xmmsfind makes
a change to 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...:   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!
    Center Xmmsfind...  Forces the window to pop up in the middle of the
                        screen.  Disable to let the window manager place it.
    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 ctrl-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>
