Media-Detect by Damon Kaswell
License: GPL.  See http://www.gnu.org/copyleft/gpl.html
Version: 0.55

**********

Contents
--------
1) Introduction to Media-Detect (Or, "The Manifesto")
2) Requirements
3) Installation
4) Usage
	4.1) Basic Command Syntax
	4.2) The Menu System
	4.3) The Configuration Editor
	4.4) Extended Mode
	4.5) Alternate Entries
	4.6) Setting application priority
5) Sample LinEAK configuration
--------


1 - Introduction to Media-Detect
Media-Detect is a script designed to make your multimedia shortcuts
more powerful and easier to configure.  It is intended for use with
LinEAK, but can be called by any shortcuts or applications you
like - such as khotkeys - or executed from the command line.

LinEAK is a program that enables the multimedia keys on specialty
keyboards, such as the Logitech iTouch (my particular model). I use
LinEAK, but have been frustrated by its lack of flexibility.  Each
button can only be configured to do one thing.  If you configure
the fast-forward button to skip to the next song in XMMS, that's
all it will do.  It won't skip to the next DVD chapter in xine if
you happen to have that program open instead.

I wanted my keys to do more.  I decided to scratch this itch and
write myself a handy script that decides what each key does based
on which app is currently open.  Specifically, it takes parameters
that have been passed to it and converts them into commands that
your multimedia applications can use.

Now, instead of calling the app directly, LinEAK calls the script.
Media-Detect then decides which multimedia application is open and
provides the correct command.  XMMS fast-forwards and rewinds, as
does xine, KsCD, and any other application that can accept DCOP or
command line calls.  My buttons work the way I want them to, no
matter what I happen to be doing.  Life is good again.

2 - Requirements
2.1 - User Interface
Media-Detect uses kdialog (version 3.2 or higher) to generate a GUI
front-end for the script's menu systems and editors.  It also uses
kwrite for manual editing of the configuration file.

If you do not have KDE installed, don't worry.  If your $DESKTOP
variable doesn't say "kde" then Media-Detect will generate a CLI
menu instead.  This menu is functionally identical to the regular
menu.

If you use KDE, but for some reason the $DESKTOP variable doesn't
reflect this (or if you want to use kdialog outside of KDE), then
Media-Detect can be hard-set to use kdialog from the Global Settings
menu.

2.2 - Sound control
Media-Detect can be used to control volume for each configured
application.  To use this feature, you must have aumix installed.

See your distribution's documentation if you don't have aumix
installed.  It is standard on most distributions.

3 - Installation
Since Media-Detect's primary component is a pair of scripts, they
can be "installed" however you prefer.  You can place them somewhere
on your path, execute them with /bin/bash, or whatever you like.

For your convenience, I've included a simple installer that will let
you place the scripts (and the man page) wherever you like.  I've
chosen the default locations (/usr/bin and /usr/share/man/man1
respectively) based on typical Linux configurations, but you can
choose any locations you like for them if you decide to use the
installer.

To use the installer:
At a console, type

		./install
		
You will get a wizard-like series of kdialog screens if you're using
KDE.  If not, a CLI installer will appear.  Everything should be
pretty self-explanatory from there.

The first time a Media-Detect script is run, it will generate a
default configuration file of ~/.media-detect.conf containing
configurations for Xmms, xine, JuK, and KsCD. (The default configuration
for xine now includes an Alternate that gives it play-pause
functionality).

You can change the location of the configuration file by editting
the scripts manually.

4 - Usage
4.1 - Basic Command Syntax
Media-Detect uses BASH scripts ("media-detect" and "media-menu") which
accept one command line parameter.  They processes that parameter into
a command for whichever configured multimedia application is open, or
open a menu.  The commands are meant to be self-explanatory, but they
are also arbitrary. Just because I have chosen to only associate
rewinding commands with "media-detect previous" doesn't mean you have
to.  I would recommend it for simplicity's sake, however.

The multimedia commands Media-Detect can process:
Rewinding:		media-detect previous
Fast-forwarding:	media-detect next
Stopping:		media-detect stop
Playing/Pausing:	media-detect play-pause
Volume Up:		media-detect volup
Volume Down:		media-detect voldown
Mute channel:		media-detect mute

If no configured multimedia apps are open, any of the above
commands will open the main menu, with the exception of volume
control commands. These will adjust the default mixer and channel
whether there are any configured applications open or not.

4.2 - The Menu System
Media-Detect comes with a menu system based on kdialog.  From the
menu you can:
* Launch configured applications
* Edit application configurations
* Make adjustments to Media-Detect

To access the menus, use the following commands:
Main menu:              media-menu menu (or just media-menu by itself)
Editor menu:		media-menu edit

Note: For the sake of backwards compatibility, the "menu" and "edit"
parameters can also be given to the "media-detect" script.

4.3 - The Configuration Editor
Media-Detect comes with a configuration editor, media-menu.  It
supports the following functions:
* Adding, deleting, and editing application configurations
* Opening the config file in a text editor
* Turning on/off Extended Mode (which supports 5 additional buttons)
* Setting the Interface Mode (Choices are GUI, command line, or allow
  Media-Detect to automatically detect your environment)
* Reverting the config file to the default one (useful if it becomes
  damaged somehow)
* Importing configurations from other files.

Configurations are stored by default in ~/.media-detect.conf.  This
can be changed by editing the media-detect and media-menu scripts.

To access this editor:	media-menu edit
(The editor can also be opened from the main menu.)

4.4 - Extended Mode
Some multimedia applications have several additional commands it
may be desirable to use with Media-Detect beyond the basics.  If
your keyboard has more keys you would like to use with specific
applications, Extended Mode will allow you to define and configure
up to five additional commands.

To enable Extended Mode:
a. Open the editor menu ("media-menu edit" or choose "Configure
   Media-Detect" from the main menu)
b. Select "Turn on/off Extended Mode"

Once Extended Mode is enabled, the following additional commands
will be supported:
Extended function 1:    media-detect extbtn1
Extended function 2:    media-detect extbtn2
Extended function 3:    media-detect extbtn3
Extended function 4:    media-detect extbtn4
Extended function 5:    media-detect extbtn5

4.5 - Volume Control
New in version 0.55, Media-Detect now supports volume control.
This feature is meant to replace the built-in volume control of
LinEAK or the built-in KDE volume controller, both of which only
allow control of the master volume on the first mixer.

With Media-Detect, you can specify the mixer and channel to
control with each application.  There is also a default mixer and
channel configuration that Media-Detect will revert to if no
configured applications are open.  Differentiating the channel and
mixer to control with each application is optional: each one can
also be configured to just use the global default.

The first time you start the Media-Detect 0.55 menu, it will set
the default mixer and channel (/dev/mixer and the master volume).
These can be changed in the Global Options menu.

To use Media-Detect to control the volume, use the following:

Volume Up:		media-detect volup
Volume Down:		media-detect voldown
Mute Volume:		media-detect mute

4.6 - Alternate Entries
Alternate Entries let you configure one of the basic commands
Media-Detect accepts (previous, next, stop, play-pause) to
"alternate" between two different functions.  For instance,
if you have a xine configuration that looks like:

	xine -S pause

then you might create an Alternate that looks like:

	xine -S play

After you've done this, the button you've configured will switch
back and forth between these two commands, giving you a "play-pause"
functionality that Xine itself doesn't have!

Alternates can be added when a new application configuration is
installed, or added to existing configurations.

To add an Alternate Command:
a. Open the editor menu ("media-menu edit" or choose "Configure
   Media-Detect" from the main menu)
b. Choose "Use Application Editor"
c. Select the application to edit
d. Choose "Edit Alternate Commands"
e. Select the command that you want to create an alternate for from
   the list, and enter your alternate command.

4.7 - Setting application priority
Media-Detect lets you set a priority for each of your configured
applications.  Now, instead of getting an error message when you try
to use Media-Detect with two applications open, Media-Detect will
simply route all commands to whichever application has the highest
priority.

Application priority is determined by the order in which the
applications appear in your configuration file.

To change application priority:
a. Open the editor menu
b. Go to the Application Editor
b. Choose "Adjust Application Priority"
c. Select two applications to reverse position. (Sorry, kdialog is
   limited, and this was the only easy solution).

4.8 - DCOP Applications
Media-Detect allows you to specify whether an application is a standard
application or a DCOP application. If it is a DCOP application,
Media-Detect will search DCOP for it. The main benefit to this approach
is that applications that register random names with DCOP, like kmplayer,
can now be used with Media-Detect. This wasn't possible before.

Since this is a new feature, all previously configured DCOP
applications will be treated as normal applications.  See the files in
the ./configs directory for sample DCOP configurations.

5 - Sample LinEAK configuration

A typical lineakd.conf file might contain an entry that looks
something like this:

	next = "xmms --fwd"

The limitation of this is that whichever key lineakd associates with
"next" will always produce the command "xmms --fwd" no matter what
application is running.

In this example, you might instead configure lineakd as follows:

	next = "media-detect next"

Media-Detect will generate the appropriate action based on which
application is running.  If xmms is running, then it will run
"xmms --fwd" but if Xine is running, then it might instead run
"xine -S pl=next".  The exact command it runs is up to you.

The following is a partial excerpt from my lineakd.conf:

	Media = "media-menu"
	Mute = "media-detect mute"
	Next = "media-detect next"
	Play = "media-detect play-pause"
	Previous = "media-detect previous"
	Stop = "media-detect stop"
	VolumeDown = "media-detect voldown"
	VolumeUp = "media-detect volup"

Each multimedia key association is optional.  For instance, if you
don't want to use the volume controls in Media-Detect, feel free to
use the LinEAK built-in volume controls.
