This is a description of the Audio::Xmpcr module.

It provides access to control the XM Satellite Radio 'PCR' device. The PCR is a small, user-interface-less box that tunes into XM Satellite Radio. Control is performed via a USB port, and (on linux) the usb-serial module. Serial support in perl is provided by Device::SerialPort.

For technical reasons, and because the box is a shared hardware resource, a daemon is provided. Depending on your needs, it may be preferable to communicate with the PCR via the daemon. See the pod documentation for more information.

This package is a rewrite and extension of Chris Carlson's original work. Much appreciation goes to him for publishing the protocol (which he in turn discovered from someone else; thanks also to whoever that is!).

****** WARNING ********

Please note that a bug has been found in Audio::DSP 0.02, which causes extreme memory leaks and can halt your operating system when free memory is exhausted. The author has been notified, but a fixed package is not available of this writing. If you need to use 0.02, you'll need to fix the bug yourself. Replace line 594 of DSP.xs, by adding a call to sv_2mortal. Line 594 should now look like:

XPUSHs(sv_2mortal(newSVpvn(buf, status)));

There are other changes required, but they won't impact Audio::Xmpcr.

****** Note about Channel Lists ********

Any program that uses the serial API will cache the channel list to a disk file to reduce start-up time. If the channel list changes, you'll need to delete this file and restart the daemon: ~/.xmpcrd-cache
Building
To build it, make sure you have Device::SerialPort, Audio::Wav, and Audio::DSP loaded. Unpack the module, and type : 
        perl Makefile.PL
        make install

that's it.

Starting the daemon (if you elect to use it)
An optional daemon is provided. The API is called the same way whether or not you're using the daemon. So why would you want to use the daemon?

To start the daemon, just run the command 'xmpcrd'. If you pass the '-d' argument, debugging information will be generated. (in particular, it just prints the client commands as they are executed.) It takes a minute or so to come up when 'power on' is executed, since it has to scan all of the channels.

The daemon recognizes when the web-interface connects, and tries to start the darkice program (for audio brodcast to icecast). See http://www.icecast.org for more info. If all you want is web-based control (and no audio broadcasting), you can disable darkice by editing the daemon's source (there's a configuration section at the top).

Setting up the web interface (if you elect to use it)
Likewise, to use the web interface, copy the web/index.cgi file (and templates) to a convenient place in your web directory, and edit the configuration section at the top of the .cgi to point to the location of the templates.
Included applications:
* All command-line applications are placed into your perl's $SCRIPTDIR. * All applications have a preferences block at the top of the source;

edit it to set local parameters.

xmripper: Rip individual songs from a channel (into wavs) for making mp3's 

        index.cgi:A  web interface for controlling the pcr remotely. Offers
        icecast support, so you can broadcast the audio over the network. 
        Find this code in the web/ directory of the source Xmpcr package.

        xmfinder: A program that searches channels for songs you want, 
                                                and records only them.
Pod documentation
See the pod documentation in Xmpcr.pm for:

Thanks,

Paul Bournival
paulb@cajun.nu 13 Aug 03