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