
				Beepfind
				========

This is a small plug-in for BMP (http://beepmp.sf.net) that is similar to
the built-in function "jump to file" although it has some more features.
This version requires BMP 0.9.7 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 Beepfind work, it must be enabled through the BMP preferences
dialog (preferences->Effects/General Plug-in), here you may also configure
Beepfind. (See below for details)
To start a search, simply launch the beepfind_remote program (installed in
/usr/local/bin by default) which will tell Beepfind to start a search

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

When Beepfind is told to launch (beepfind_remote) it gets the playlist from
BMP and stores it in memory. This is done only ONCE because it takes CPU on
slower machines, so if songs are added/removed while Beepfind search-box is 
open, the changes won't be visible unless Beepfind is refreshed. This can be 
done by re-launching beepfind_remote, clicking refresh, or pressing F5.
Also, the list IS updated every time Beepfind makes changes to the playlist.

In the search-box, simply type the words that you want to search for.
Beepfind 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 built
into BMP, 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
    BMP 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!
    
    Get titleinfo:      Tells Beepfind to query BMP 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.
    Do not close:       Don't close the Beepfind window after jumping to a song.
    Center Beepfind:    Forces the window to pop up in the middle of the
                        screen.  Disable to let the window manager place it.
			    
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 BMP?

Well, the problem with the built-in "jump to file" (or "jtf") is that you
have to have BMP 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 BMP 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 us:
<iso01001@student.mdh.se>
<marineam@engr.orst.edu>
