"par.pl" - A Personal Audio Recorder in a Perl Script

Overview

par.pl is a script to download streams in Real Audio format and transcode them to a format of the users' choice. The output audio file is also appropriately tagged.

This script, whilst it is in Perl, really assumes it's running on Linux. It might be possible to adapt it to run on Windows, but I have no real inclination to do that as that's not the platform I need to run it on. The main use of this script (and its original purpose) was to implement a "poor man's personal audio recorder" by coupling this script to cron. In particular, this is very useful for the BBC's "listen again" content since that allows you to record each programme as they come out (if you schedule your cron job correctly). Each recorded programme is given a filename that includes the date of the recorded programme, hence if you use this correctly you'll end up with folder that contains all the recorded episodes of the programme you were interested in.

Options

  • --stream. The URL of the Real Audio stream to record. This can end in either .ra or .ram - both will be correctly handled.
  • --outputdir. The directory used for the output files - this script will place each recorded programme into this folder with a filename that includes the date that the recording was made.
  • --format. The required output format. This can be any format that is recognised as a 'convertto' type by the Perl Audio Converter script (pacpl), but the most common types to use here would be "ogg" or "mp3". This parameter is optional; if it is not present then MP3 format is the default.
  • --artist. The artist name to tag the output file with. For radio stations, this is often going to be the station name the programme has been recorded from (eg "BBC Radio 4").
  • --title. The title that will be written into the track tag of the recording (with the date of the recording as a prefix). For radio stations, this is often going to be the name of the programme itself (eg "The Archers Omnibus").
  • --minlength. Specifies the minimum length, in minutes, that the programme is expected to be. This is useful since a remote steam can be prematurely closed and would otherwise result in a part-recorded programme. If the recording is less than this number of minutes then the script will try to download the programme again, up until the number of tries in the next option.
  • --maxtries. This specifies the maximum number of tries that will be used to download the programme. This value is optional; if not specified then the maximum number of tries will be 5.
  • --retrypause. If the download has to be retried, this value specifies the amount of time, in seconds, that the script will pause before retrying the download. This value is optional; if not specified then the pause will be 300s (five minutes).
  • --bitrate. Specifies the required bitrate (in kbps) of the resulting file. This value is optional and if not supplied the default of 128kbps will be used instead.
  • --help. Displays usage information for the script.

Getting Further Help

As the online help is embedded in the script you can get a man page style guide with the perldoc par.pl command.

Example

A simple example is probably all you'll need to actually use this script effectively. The following command will download a programme that is published weekly and transcode it to Ogg format:

par.pl
--stream "rtsp://rmv8.bbc.net.uk/radio4/archers/archers_omnibus.ra"
--outputdir "/mnt/media/Radio/archers"
--artist "BBC Radio 4"
--title "The Archers Omnibus"
--minlength 73
--format ogg

Over time (eg if this command were scheduled weekly with cron), this will populate the folder /mnt/media/Radio/archers as follows:

2006-08-27 The Archers Omnibus.ogg
2006-09-03 The Archers Omnibus.ogg
2006-09-10 The Archers Omnibus.ogg

An example cron entry that scheduled this command to be run weekly would be as follows (note that this would be all on one line in the crontab):

0 17 * * sun par.pl
--stream "rtsp://rmv8.bbc.net.uk/radio4/archers/archers_omnibus.ra"
--outputdir "/mnt/media/Radio/archers"
--artist "BBC Radio 4"
--title "The Archers Omnibus"
--minlength 73
--format ogg >/dev/null 2>&1

This will download and transcode the programme at 5pm every Sunday evening. Remember that you can add and amend crontab entries with the crontab -e command. Note the redirection at the end of the entry to prevent cron mailing you the verbose output of the script every time it runs. Note: the script relies on finding both 'mplayer' and 'pacpl' in the path, so you need to ensure that the PATH used for cron jobs is correct for the location of these commands on your system. On mine, for example, I have to add the following line to the top of my crontab:

PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin

Installation

First download the script below. Installation is straightforward - simply copy the script somewhere and ensure it's executable. A good choice would be your /usr/local/bin directory.

Dependencies

As well as the main dependencies of this script (which should be detected and a meaningful error produced if they are not present), there are a number of other dependencies that must be installed for this script to work:

  • mplayer. This does the main work of downloading and dumping the radio stream. It must be configured with the appropriate codecs to allow the decoding of Real Audio streams. The Gentoo ebuilds media-video/mplayer and media-libs/win32codecs can be used to install this.
  • Perl Audio Converter. This can be obtained from here (there is no Gentoo ebuild available). Follow the installation instructions with the package (note, though, that only a "base" installation is necessary for this script's purposes).
  • Ogg::Vorbis::Header. This is required by the Perl Audio Converter and must be installed. The Gentoo ebuild dev-perl/ogg-vorbis-header can be used to install this.
  • MP3::Tag. Only necessary if you intend to produce MP3 files with --format mp3 (or leave the default format, which is MP3). The Gentoo ebuild dev-perl/MP3-Tag can be used to install this.
  • Plus, any other dependencies of the Perl Audio Converter for your chosen output format - determine those by running pacpl-install -c in the installation package (the required Perl modules are listed at the end).

Monitoring

It's easy to forget this script is running and, if there are any problems, not realise you've missed a recording. As I've been bitten by this myself (I'll never be able to get that week of The Archers back!), I wrote a simple checker script that you can find below. It's a bit rough and ready, but there are some configuration constants near the top that you can change to suite your machine. Again, I expect you'll schedule this through your crontab with an entry such as the following:

00 06 * * * /usr/local/bin/parcheck.pl --mailto someperson@somehost.co.uk

The script looks to see if there are any currently-scheduled recordings in your crontab where there hasn't been a recording for more than a week, and if it finds such a directory it sends an email to the nominated recipient.

History

  • 16/12/2006. Corrected a few typos and added clarifications reported by Philip Lyons - thanks very much for the feedback Philip, and thanks for PAC!
  • 11/12/2006. Added a monitoring script to detect if recordings have been missed.
  • 6/9/2006. Initial version.
AttachmentSize
par.pl12.64 KB
parcheck.pl2.5 KB

Comments

Thanks for the points,

Thanks for the points, Philip, I've incorporated those now. Thanks for the Perl Audio Converter - it's an excellent tool.

Nice script. I noticed the

Nice script. I noticed the following though, and thought that you might want to change it.

1) "Ogg::Vorbis::Header. Only necessary if you intend to produce Ogg files with --format ogg. The Gentoo ebuild dev-perl/ogg-vorbis-header can be used to install this."

Ogg::Vorbis::Header is required by PAC, therefore it is absolutely necessary to have it installed.

2) "# Perl Audio Converter. This can be obtained from - there is no Gentoo ebuild available. Follow the installation instructions with the package (note, though, that only a “base” installation is necessary for this script’s purposes)."

There's no URL that points to PAC. Probably because the URL is surrounded by < >

3) "Note: the script relies on finding both ‘mplayer’ and ‘parpl’ in the path"

Typo parpl = pacpl

Keep up the good work.