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? * A full channel listing can be obtained instantly with the daemon, but will take ~10-20 seconds without. * The daemon will, if you elect, alert you to song changing events. Methods in the API are provided to provide you with a list of just those channels (and the new song names) that changed. 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: * A more detailed description of the api * A copyright notice. Thanks, Paul Bournival paulb@cajun.nu 13 Aug 03