The K-Zone: pmaplay -- a rudimentary MP3 stream player for PMA430

What is this?

pmaplay is a rudimentary MP3 stream player for the Archos PMA430. By rudimentary I mean that it has an impoverished user interface, no proxy or authentication support, and limited error reporting, among other things.
pmaplay is designed to play ShoutCast and IceCast streams. These streaming formats are widely used by Internet radio operators. It may play other streams that are MP3-based as well, but I can't make any promises. pmaplay has elementary support for ShoutCast playlist files (.pls files), and can be integrated with the Opera Web browser to play these files through the browser. This means, for example, that you can click on any `Tune in' link on the ShoutCast home page (www.shoutcast.com), and get playing immediately (with a bit of luck).
This implementation should be regarded as alpha quality, if even that. If you get poor-quality playback, please see the discussion of the `Downsample' option below before reporting a bug. Please read the section `Bugs and Limitations' before installing anything.

Installation

If you have Archos version 1.3-2 or later on your PMA, download the installer for pmaplay v0.02. If you have earlier firmware, you will need to use the earlier version v0.01. Install the software on the Archos in the usual way (e.g., copy the installer to the Documents directory and run the package manager). You should find an icon for the program on the Application tab of the Launcher. Needless to say, you'll need to make sure you have a working Internet connection from the PMA before trying to play a stream.

Graphical user interface usage

The user interface is very simple -- it can either display a list of bookmarks (if you've stored any) or the status of the current playback. To start playing a stream, select `Open URL' from the `File' menu, and enter the URL of the stream. If you're lucky, it will start to play. If you're not, you might at least be lucky enough to get an error message. In general, the user interface is not sophisticated enough to interpret the detailed error messages from the server or the MP3 decoder, so don't expect to see much in the way of diagnostic information if it doesn't play.
If there are particular streams that won't play, you might get more diagnostic information by running the program at the command line (see below).
Once a stream is playing, you can save it as a bookmark by selecting `Add' from the `Bookmark' menu. Thereafter you'll be able to select the stream from the Bookmarks page rather than entering the URL. Note that you need to double-click on an entry in the bookmarks page to select it (or you can press the centre button on the navigation pad). The bookmark list doesn't respond to a single-click operation, because there may come a time when pmaplay supports other bookmark operations (but don't hold your breath...). At present, the user interface provides no mechanism to delete or organize bookmarks.

Integration with Opera

pmaplay can play streams defined in ShoutCast playlist (.pls) files. Most websites that provide access to ShoutCast streams do so by linking to one or more .pls files. These files can, in principle, reference multiple streams but, in practice, few do. Consequently, pmaplay will only play the first stream referenced in the file.
To play .pls files from a browser, you will need to enable Opera to invoke pmaplay when you select a .pls file. From the Opera `Preferences' menu, select `File types'. Click the button `Add new MIME type'. For the type, enter `audio/x-scpls'. Then choose `Use external program', and enter the program name pmaplayui. The click `OK'. That should do the trick.

Command-line usage

This program can be run from the console command line. If you have problems with particular streams, this is the best way to get some kind of diagnostic information which can be used to improve the program.
The simplest way to run from the command line, if you know the URL of the stream you want to play, is to open the console application, then enter at the command line:

# pmaplay_feeder [url]

For example:

# pmaplay_feeder http://64.236.34.196:80/stream/2008

Implementation notes

pmaplay has four major parts:

A stream feeder (pmaplay_feeder) which slurps up data from the server by HTTP, and feeds the decoder. This component communicates stream data (title, etc) with the graphical user interface. Communication is through a file /tmp/pmaplay.log, which is cleared whenever a new stream is selected, and then written as IceCast headers are retrieved from the server. The format of this file is understood by the user interface. The feeder invokes the decoder internally, and feeds the stream data into its standard input channel through an anonymous pipe.
An MP3 decoder (pmaplay_madplay). This is based on madplay, which in turn is based on the MAD decoder library. To reduce CPU load, MAD is compiled for speed rather than accuracy. I have therefore linked the MAD library directly into the decoder so it doesn't interfere with any other version of MAD you may have installed. The madplay version used in this project is pared to the bone to reduce memory size and CPU load, and most of its usual features are absent. In particular, I have removed all the audio output and file handling features. The audio output doesn't work on the PMA430 anyway, and no file handling is needed since the stream feeder pipes the data into the decoder directly.
A sample player (pmaplay_bplay). This takes decoded audio samples from the decoder, buffers them, and feeds the the PMA's audio driver. In fact, the sample player consists of two processes, a reader and a writer, communicating through shared memory blocks.
A graphical user interface (pmaplayui) to tie all the other parts together

All the components of pmaplay have either been written specifically for the application, or are heavily modified versions of open-source projects. Because there is considerable scope for these modified versions to clash with unmodified versions that may already have been installed on the PMA, everything is statically linked. There should therefore be no dependencies on other packages. As every file installed by the installer has a name that begins with `pmaplay', there should be little scope for bits of this program to clash with other things.

Bugs and limitations

PLEASE READ THIS BEFORE DOING ANYTHING :)

This program will not play any kind of RealMedia stream
This program will not play any kind of Microsoft media stream
The program should not be used to play local files (but why should you want to? The PMA has a perfectly good MP3 file player built in). In fact it will play local files, after a fashion; but it won't play them very well, as the buffering parameters are optimized for network operation
This program cannot be used to write streams to disk. Please don't ask for this feature to be added. If you've got a C cross-compiler, you can add it yourself :)
There is no support for HTTP proxies. None at all. If you normally need a proxy to get to the Internet, forget it (for now -- it's on the to-do list)
The stream feeder will not follow HTTP redirects. In plain English, this means that if the server at the URL you enter suggests a different URL to go to, you'll get an error message (usually error 302). To be fair, most PC-based players don't follow redirects either. If you really want to play the stream, you'll have to find the real URL, perhaps by hitting the original URL with a web browser and seeing where it takes you
Don't expect to be able to do anything else with the PMA while using this program. Some limited multitasking is possible while playing low-bitrate streams, but with high-bitrate streams, playback will be badly affected -- even with all the code optimised to reduce CPU load, this program generally consumes at least 50% of the available CPU throughput.
Changing streams is not a fast operation. pmaplay uses a relatively complex system of inter-process communication to improve throughput. When you change streams, all these processes have to be torn down and new ones established. Then the new stream has to be pre-buffered to allow for intermitted transmission. This will usually take a second or two. If you click on a bookmark and nothing happens, please wait a second or two before clicking again. If you see ``(busy...)'' in the title bar, the program is thinking. Note that stream information (title, etc) may not appear for a few seconds after playback starts. This is normal -- the user interface only checks for new information from the stream feeder every three seconds.
Not all MP3 streams will play, even those that really should. High-bitrate streams (more than 192 kBits/sec) will probably not play at all. Some 128 kbits/sec streams won't play very well, although some do. See below for a discussion of this issue.
After a certain number of uses, the program may refuse to run at all. At the command line, the error message is:
```
pmaplay_bplay: semget: No space left on device
```
This error message is caused by the sample player not tidying up semaphores correctly. At present, I'm not sure whether the limitation is in the software or in the PMA's Linux implementation. I don't see the same problem when running this sofware on a workstation, so I'm inclined to suspect the latter. I'm not even sure what circumstances cause the problem. In any event, the PMA doesn't have the software built in to tidy up semaphores, so the only solution is to reboot. If you experience this problem, please let me know.
The Opera browser does not invoke helper application through Qtopia -- it does it by invoking the Linux shell directly. This is a bad thing for pmaplay, because like all Qtopia applications it doesn't get a taskbar icon when it is launched this way. This means that if you switch to a different application while pmaplay is running, you won't be able to get back. I should stress that this is a consequence of the way Opera works, and not something that can be corrected in pmaplay. If you use this software to play a .pls file through Opera, make sure you close pmaplay before switching back to Opera or another application. If you forget, there is a last desparate measure you can take, which is to shutdown pmaplay from the console. Get a console prompt, and type:
```
# pmaplay_kill
```

Downsampling and sound quality

One possible reason (and I must stress that it's only one of a number of possible reasons) for erratic, `clicky' playback is that the PMA430 has a small audio buffer, and limited CPU power. I have not been able to find a way to increase the buffer size beyond two chunks of 4096 bytes. I don't know if this is a limitation of the PMA's hardware, or if there is some secret, undocumented method for increasing the buffer size that Archos are keeping to themselves. 4096 bytes corresponds to 40 msec at a sample rate of 44,100 Hz (which most high-biterate streams require). What this means is that anything that interrupts the process that feeds the audio buffer for more than about 40 msec will cause the buffer to under-run -- to run out of samples to play. This effect manifests itself as a `click' or `pop' in the playback, rather like a stratch on a record (remember records?).
      It's important to realize that the limiting factor here is not the overall bitrate of the stream, but the sample rate of the data that the decoded stream delivers. Most streams with bitrates of 128 kbits/sec or higher use 44,100 Hz sampling, but I've streams with much lower bitrates use this sampling rate. Similarly, some high-bitrate streams use lower sampling rates, for various reasons.
      pmaplay will play most 128 kbits/sec, 44,100 Hz streams without too much clicking provided you're not doing anything else. This only applies if the stream itself is stable, that is, capable of delivering data at a more-or-less constant rate. If you want to play streams with higher sample rates or bitrates, or you want to multitask, you should consider downsampling. To enable downsampling, select the `Downsample' option from the `Settings' menu. The effect is to reduce the sample rate of all streams to 22,050 Hz. Because the sample buffer stays the same size, this means that it takes twice as long for the audio output buffer to run out of data, so it can tolerate somewhat longer pauses in sample delivery. With downsampling, you should general get click-free operation (provided that the source is not generating its own artefacts), even with limited multitasking. However, the trade-off is that the overall sound quality will be degraded.
      My experience is that it isn't necessary to enable downsampling on good-quality, 44,100 Hz streams, unless I'm trying to multitask. 48 kHz streams (if you can find any) invariable require downsampling. If you don't get good quality playback, please at least consider the possibility that the problem lies outside this software before reporting a bug.

Power management issues

When the PMA430 is on battery power, normally it would be configured to go into suspend (`sleep') mode after a certain period of time of inactivity. The problem is that network activity is not considered `activity' by Qtopia. The fact that you're playing a network stream won't prevent the PMA going to sleep, which is irritating. Of course, you can use the power management applet to prevent it sleeping when the network connection is active, but the problem with this is that it will never shut down if you forget to shut it down. If you leave the unit unattended and forget about it, you'll come back to a flat battery.
There is no perfect solution to this problem. The built-in media players disable suspension while they are playing -- but they only play files of known duration. When you're playing a stream, the duration is unknown and, in most cases, unlimited.
So, lacking the possibility of a more elegant solution, pmaplay can be configured to prevent the PMA430 going to sleep. To do this, select `Delay suspend' from the `Settings' menu. In order to prevent the battery being drained, this mode is self-cancelling after one hour, upon which the PMA will suspend if there is no user activity.

Reporting bugs

If this program does not work for you, and you think it should, please report a bug, and I will try to fix it. However, before reporting a bug, please bear in mind the following factors.

Please be aware that, if there is a problem with audio playback, it isn't necessarily this software that is to blame. It might be, but it ain't necessarily so. It goes without saying that the source must be able to supply data at least as fast as it gets played, at least on average. With the current settings, pmaplay buffers about 10 kB of data from the source, which is enough to accomodate a pause in transmission of a few seconds, depending on the bitrate. If the playback breaks up completely, most likely the bottleneck is in the source or the network infrastructure, rather than this software.
Please also bear in mind that most Internet radio stations experience outages and odd behaviour from time to time. If you get `404 not found' errors, most likely the URL is simply wrong, or the server is down. It's unlikely to be a bug in pmaplay.
Even well-established and stable broadcasters rarely broadcast 24 hours a day. If pmaplay gets as far as displaying a stream name and bitrate on the `Info' page, but no sound is playing, most likely the server is active, but transmitting silence. This is not a bug :)

If you believe that there is a bug in pmaplay, please include the following information in your report.

The version of the program (use the `About' command from the `Help' menu)
The URL of the stream, so I can try it myself
Any error message that appear when you try to play the stream at the command line. It will be very difficult to diagnose the problem without this information

Revisions

0.01h -- March 2005:
  * Added a `delete bookmark' menu option
  * Added facility to defer going into suspend mode
  * Reluctantly modified the program to use the standard Qtopia 
    method of saving settings. The PMA overwrites the files in
    /media/pda/Settings on a shutdown, so reading and writing this
    area directly is fruitless
0.01g -- March 2005:
  * Set pre-buffering size to 32kB for all bitrates
  * Converted mono streams to stero by duplication, to avoid problem
    with PMA430 audio hardware (selecting mono operation on the 
    audio driver causes the hardware to product no output at all)
0.01f -- March 2005 -- first public release

Legal stuff

There is no warranty! I can't promise that this software will work for you. Like most software developers, I instinctively test my programs in ways which I know won't reveal any faults. I can't even promise that this software won't break your PMA. It hasn't broken mine, but I might just be lucky.

pmaplay is distributed according to the GNU Public Licence. In short, you may do whatever you wish with this code, provided that the original authors continue to be acknowledged, and source code is made available. If you would like the source code for this software, please ask me. Please send bug reports, suggestions for new features, etc., to me.
©1994-2006 Kevin Boone, all rights reserved