top

Summary

PCRCommander is an application that allows you to control the popular XM PCR product and compatible devices. PCRCommander supports timeshifting content (just like the popular TimeTrax application) so you can listen to it when you want, not when it's scheduled, and labels, names and tags tracks appropriately. It also has the ability to "quick search" all the available channels for an artist or song, stores favorites for easy access, supports scheduled recording events (on a daily, weekly or one-time basis), features the helpful and entirely configurable Related Searches sidebar, and has several codecs available for recording content in your choice of format.

IMPORTANT: We do not support copyright infringement in any way. Songs recorded by PCRCommander are tagged with your Radio ID and are thus traceable to you, so please do not distribute them to others. PCRCommander enables you to exercise your rights to personal use and timeshifting that are protected in most localities, including the US. If you want to continue enjoying these rights in the US, please support the EFF - a modest annual donation helps protect all of our rights. We strongly encourage you to purchase CDs (or online music tracks) of artists whose work you support, especially if those artists are not affiliated with the RIAA.

PCRCommander is not an official product of XM Satellite Radio or any related companies or organizations. It's not approved by them, and they probably wouldn't approve of it. If you are a subscriber of their service and you use PCRCommander's recording capabilities you are probably in violation of your subscriber agreement (we are not offering you any legal advice, of course).

top

Installing

You can download the latest version of PCRCommander at the download page. If you are using Windows, download the latest installer .exe and double-click on the PCRCommander icon on your desktop to run. Make sure your XMPCR or compatible device is connected to your computer via USB cable, and that you have installed the USB-serial drivers (these came with the hardware, and if you installed the included software, you should have no problems).

On Linux, PCRCommander should work fine if you build from source (see below for instructions), though it is not tested yet and there may be some unknown issues. Other *nix systems, including OS X, should theoretically work if you can get the PyMedia extension to compile and work on your platform, which may take a bit of work.

top

Compiling from Source

First, you need to grab the source ZIP or tarball from our download page. Or, better yet, get DARCS, the excellent cross-platform source control system we use instead of CVS, and type:

darcs get http://pcrcommander.sarovar.org/repos/PCRCommander

at the command prompt. Darcs has a great command line client with binaries available for Windows and Linux, and only takes a few minutes to learn.

There are several components you need to build and run PCRCommander. First, you'll need Python 2.3 or later, available from python.org, preferably 2.3.4 final. Next, you will need to download and install several Python libraries/modules. The GUI toolkit used is wxPython - PCRCommander is tested with the latest stable release 2.4.2.4, available here. You will also need PyID3 and PyMedia 1.2.2.1 or later (important: please use the version of PyMedia 1.2.2.1 in our files section for now, since it has several patches made to it that haven't yet been incorporated into the official PyMedia release). After you build each of these modules, you will have to run the installer which copies the modules to your Python site-packages directory, and then you should be set to run PCRCommander (type PCRCommander.py in the directory you unpackaged PCRCommander to, or keep reading to package an executable file as we do for distribution.

For packaging our Windows binaries, we use the hard-to-find and strangely named (but superior) alternative to py2exe, McMillan Installer (it's not an Installer at all, it takes python scripts and packages them into an executable file) and Inno Setup. If you run the build.bat file, it will create a single-file executable package of PCRCommander like the one we distribute in our Windows installer, and then package it up with other necessary files into a finished installer using Inno Setup.

For packaging and distribution on Linux or other UNIX-like platforms, we recommend trying cxFreeze, which is essentially a cross-platform version of py2exe. We haven't tried this yet, so your mileage may vary.

top

Using PCRCommander

Setup and Configuration

PCRCommander speaks to your PCR via a standard serial port - this means for most people with XMPCR devices, you will need the USB-serial port drivers (which are included with your device). If you are running Windows and installed the included software with your XMPCR, then these should already be installed. The first time you start up PCRCommander, it will scan your serial ports for a PCR device. It will save this setting, and look for the PCR device on the same port afterwards for faster startup. You can always change this in the settings.cfg file - in the Settings section, the 'portname' value can be set to the appropriate port name (i.e. 'COM3' on a Windows PC), or changed back to 'auto' to force a scan for a PCR device. You will usually only have to do this if you reconfigure your computer's hardware. By default, the Windows USB-serial drivers will use COM3 unless that port is already taken by another device. Recording settings can be configured by going to the File->Settings menu, where you can choose a codec, encoding bitrate, and audio sample rate. Not all bitrates and sample rates will necessarily work for all codecs - so some experimentation may be required if you want to play around with these settings at this point. These settings will not currently take effect until the next time PCRCommander is started to avoid interrupting any current recordings.

Normal Use

The channel list is on the bottom half of the PCRCommander app. Clicking once on a channel will tune to that channel. You can click on the column headers to sort the channel list by number, artist, title, channel name or genre. You can also use the Quick Search box on the upper panel to filter the channel list as desired - for example, if you want to see if Britney Spears is playing on any channels currently, type 'britney' and the list will be filtered down with each additional character you type. You may store the currently tuned channel as a favorite at any time by pressing and holding down one of the 9 favorites buttons for 2 seconds (you will see the button label display the channel number when the favorite is stored). Pressing that favorite button at any time in the future will return you to the favorite channel. Basic signal strength data is displayed in the lower left corner of the top panel at all times. Additionally, the Related Search toolbar is displayed by default on the right side of the top panel. You can hide this panel at any time by clicking on the hide window "slider" to the left of the Related Search bar (and re-expand it likewise). The links in this toolbar will open your default web browser with the appropriate search results relevant to the current song. See the Related Search section below for more information on configuring this panel - it's very easy to change the contents to return results from the search engine, lyrics search service or music retailers of your choice. As a word of warning, be careful of some of the lyrics sites out there if you use Internet Explorer as your default browser - some of them like to try to install sorts of nasty spyware. You have been warned.

Recording

At any time while listening to a song or program, you may hit the "Record Song" button if it is visible. This will save the entire current track to a file. That means you can tell PCRCommander to start recording a song mid-track if you decide you like it, and the whole song will be saved to disk. If the "Record Song" button is not visible, it means you just tuned to a channel while a song or program was midstream. The next release of PCRCommander will support recording partial tracks or programs. If you press the "Record All" button at any time, PCRCommander will begin monitoring the current channel and recording every song or program that comes on. In any case, if you change the channel while you are recording a track, it will interrupt your current recording.

Related Search

The contents of the Related Search bar can be modified at any time by editing the related.html document in your install directory. The tags '%artist%' and '%title%' will be replaced with the URL-escaped versions of the artist or title as appropriate. It should be quite easy to edit this file using the text editor or HTML editor of your choice.

top

License

PCRCommander is available under the GNU General Public License (GPL). Feel free to do what you will with the source code, but if you redistribute it or a compiled/binary version thereof, you must abide by the terms of the GPL. I'd be particularly appreciative if you contributed any patches or additions you make back to us - ideally by using DARCS to email us patchsets against our public DARCS repository. DARCS is very easy to use, and if you're able to hack on the code, you'll be able to figure out DARCS.

top

Credits

Thanks to dobbz (Christopher Carlson) and nsayer (Nicholas Sayer) for their excellent work on OpenXM and MacXM/JXM respectively. Their work deciphering (and documenting in their code) the serial protocol used by the XM PCR was extremely helpful. PCRCommander is Copyright 2004.