$Id: README,v 1.5 2002/05/19 11:17:57 wwwwolf Exp $

XMMS InfoPipe
=============

(c) Urpo Lankinen 2000, 2001, 2002
Distributed under GNU GPL (see COPYING for details).

This plugin consists of two parts:

   - The XMMS plugin, written in C, that opens a named pipe to
     /tmp/xmms-info. When read from there, it just returns plain text
     that has information about currently playing song.

   - Some random scripts that serve as an example of how to parse the
     data. The package includes mod_perl and PHP scripts for
     showing information on web pages, and a script to say out loud
     the name of the song being played.

This InfoPipe thing was my original idea, though I'm sure people have
thought of this before (I think this may be clever if you stretch the
term, but not *that* clever... =) I was surprised when I couldn't find
an XMMS plugin that would have provided this functionality.

For building information, see INSTALL.


Requirements
------------

 - Some sort of UNIX =)
 - XMMS 1.x and all build stuff on thereof (to use you just need the
   binaries, of course!)

In Debian GNU/Linux, you need the xmms-dev package (and everything
related to it) to build this.


Output description
------------------

"OK, enough hype. Time for the 'meat'." =)

The plugin creates a socket called /tmp/xmms-info_(username).(sessionid)
and, if possible, a symbolic link to it called /tmp/xmms-info.

   NOTE: The symbolic link is removed and re-created at start only
     if it's possible, and is NOT removed when the program exits.
     (this behavior can be changed by editing the options in your
     ~/.xmms/config, there's currently no configuration UI.)
     If you're using only one session of the program as the sole user
     on the computer, this will work. If you plan to use multiple XMMS
     sessions, or have multiple users who like to use XMMS, you are
     wholeheartedly recommended to *NOT* rely on the symlink and
     use some "algorithms" for finding the proper pipe.
     (I mean, really, kids. Perl's opendir() and like *really*
     aren't that hard to use.)

In case you didn't know, sockets can be read from, as if they would be
files. The output has just textual information.

Here is what it looks like:

nighthowl:~$ cat /tmp/xmms-info
XMMS protocol version: 2467
InfoPipe Plugin version: 1.3
Status: Playing
Tunes in playlist: 252
Currently playing: 116
uSecPosition: 109201
Position: 1:49
uSecTime: 238288
Time: 3:58
Current bitrate: 128000
Samping Frequency: 44100
Channels: 2
Title: The Laziest Men on Mars - Invasion of the Gabber Robots
File: /usr/local/lib/music/mp3s/sites/mp3.com/techno/Invasion_of_the_Gabber.mp3

Description of the fields:
   - Protocol version: What XMMS reports as its version. This is
     mostly "Internal Use Only"; I don't know if this information
     can be used to figure out the version of XMMS.
   - Plugin version: The version you're using...
   - Status: Can be "Playing", "Paused" or "Stopped".
   - Playlist information. Current tune and total number of tunes.
   - Position and Time: Current tune playing position and total length
     of tune in minutes:seconds format.
   - uSecPosition and uSecTime: ditto, in milliseconds.
   - Current bitrate: The bitrate of the song *at the moment*. There's
     no way (as far as I know) to get the CBR or average of VBR.
   - Sampling Frequency and Channel: those hertzes and number of channels
     (1 for mono, 2 for stereo, more than that if XMMS is using some
     weird format)
   - Title: The song title as reported by XMMS.
   - File: The filename of the song.

This format is hopefully easy enough to parse with even stupidest Web
development languages, and is pretty much trivial to parse with Perl
(then again, what *isn't* trivial to parse in Perl? =)


Configuration file
------------------

The configuration is kept in the same place as all configuration
details (~/.xmms/config). The configuration, if it doesn't exist, is
created when the plugin is used, and only read thereafter. It is not
*changed* by plugin at them moment, just read, so you need to change
it yourself.

The configuration is under [InfoPipe] section.

   Key			Type	Default	Description

   create_symlink	bool	TRUE	Create the symlink.
   delete_symlink	bool	FALSE	Delete the symlink.
   do_chown		bool	FALSE	Change the ownership of the pipe?
   chown_to_uid		int	curr.	UID of the new owner of the pipe?
   chown_to_gid		int	curr.	GID    - " -

(the uid and gid are taken from the system if they're not present...)
