$Id: README 138 2003-04-17 00:00:41Z aqua $

This is xf86audio-xmms, a plugin for XMMS to enable control over XMMS playback
via the XF86Audio* keysyms, as produced by some keyboards with media-control
keys.

This plugin was written in response to demand from the users of Acme, GNOME2's
multimedia key manager.  While Acme manages the association of appropriate
keyboard scancodes with the media-control scancodes, it does not know how to
individually control the various media players.  Instead, it arranges the
mapping and expects those media players to listen for the XF86Audio keysyms.
I produced a patch against XMMS to do just that, but I'm also providing this
plugin to do the same job, since it's easier for end users than patching the
XMMS sources (indeed, this plugin's source is nearly identical to the patch).


Build procedure:

You'll need the development packages for XMMS and GTK 1.2.  On Debian systems,
these are in the xmms-dev and libgtk1.2-dev packages respectively.

That done, just run make, then make install.  By default, the build will
attempt to install to the XMMS general plugins dir as reported by xmms-config.
You can override this by specifying PLUGIN_DIR to make install, as in:

	make PLUGIN_DIR=~/.xmms/Plugins/General install


Usage:

You first must arrange to have the media control keys on your keyboard mapped
to the XF86Audio keysyms, if they aren't already.  Unlike the usual
printable-character scancodes, which have been standardized on PC keyboards
since half of forever (for which read 1980), the various "special" keys added
by aftermarket keyboards are much less uniform.  As of this writing (April
2003), this seems to be improving -- most of the new keyboards I've seen with
these keys use the same set of scancodes, and XFree86 recognizes them.

The simplest way to check whether you need to do any keysym adjustment is
simply to load and enable the plugin, then try the keys and see if they work.
If they don't, you'll need to arrange to have the keys mapped to the desired
keysyms.  If you run GNOME 2 or later, I suggest using Acme
(http://hadess.net/misc-code.php3), which can map the keys for you -- look for
Applications|Desktop Preferences|Multimedia Keys in the GNOME Foot menu.


If you don't want to use GNOME, you can find the keycodes manually with
xev(1), then have xmodmap(1) adjust the mappings for you whenever X starts.
xev is a little X app that dumps out the details of every event it sees.  When
run, it pops up a window with a little square in it.  Position your mouse
cursor over the window's close button (so you can get rid of it again without
scrolling anything important off the screen), then press and release one of
the media keys.  You should see something like this:

KeyPress event, serial 27, synthetic NO, window 0x2a00001,
    root 0x36, subw 0x0, time 484830179, (8,-16), root:(378,582),
    state 0x10, keycode 162 (keysym 0x1008ff31, NoSymbol), same_screen YES,
    XLookupString gives 0 characters:  ""
 
KeyRelease event, serial 27, synthetic NO, window 0x2a00001,
    root 0x36, subw 0x0, time 484830277, (8,-16), root:(378,582),
    state 0x10, keycode 162 (keysym 0x1008ff31, NoSymbol), same_screen YES,
    XLookupString gives 0 characters:  ""

This output was from pressing the pause/play key on an IBM QuickConnect
keyboard.  To map it to XF86AudioPause, you'd have xmodmap associate the
keycode on the third line of the xev dump with the keysym 'XF86AudioPause':

	xmodmap -e 'keycode 162 = XF86AudioPause'

... repeat this for the other audio control keys. A typical set of settings
would be:

	xmodmap -e 'keycode 161 = XF86AudioLowerVolume'
	xmodmap -e 'keycode 163 = XF86AudioRaiseVolume'
	xmodmap -e 'keycode 176 = XF86AudioMute'
	xmodmap -e 'keycode 162 = XF86AudioPause'
	xmodmap -e 'keycode 146 = XF86AudioNext'
	xmodmap -e 'keycode 164 = XF86AudioPrev'
	xmodmap -e 'keycode 160 = XF86AudioStop'

There's no "play" key listed here because I don't have a keyboard with a pure
"play" key -- this is often combined as a "play/pause" key.  The plugin will
interpret XF86AudioPause as a playback toggle -- if xmms is playing, it will
pause.  If paused, it will resume.  If stopped, it will play.


