---

Home Downloads Forums Links

UPnP Internet Radio Station Server

Introduction
Radio Station Database
Server Browse Tree
Proxy Mode
Multi-Renderer Synchronization
Web Page Presentation
Command-Line Arguments and User Preference Files

Introduction

This UPnP media server application parses a directory tree of ASCII-based XML radio station metadata files and exports the radio station data to interested UPnP control points. A default radio station database of 60-plus popular (shoutcast-only at the moment) internet radio stations is supplied with the server. Users may stations by simply creating new station files, using existing files as a template. The exported server browse tree reflects the structure of the station database directory tree, allowing users to modify the server's browse tree if desired by simply adding to or modifying the database directory tree on disk.

Radio Station Database

The radio station database consists of a set of XML files, one per station, in a simple directory heirarchy. The default database is located in the $INSTALL_DIR/db/radiodb. By convention, one directory is named 'AllStations' and contains the master list of all the stations in the database. When adding stations to the database, one should always add it to the 'AllStations' directory. User's wishing to break the stations up into categories of their choosing may do so by creating category directories and subdirectories to any nesting depth, and filling the directories with copies of (or, if the OS supports it, symbolic links to) the XML files in the AllStations directory. The UPnP browse heirarchy exported by the server will reflect the directory structure on disk. For convenience, a 'Genres' category is automatically generated by the server when it is started up, using the genre metadata in the database.

A sample database file for www.radioparadise.com is shown below. As previously mentioned, the UPnP DIDL-Lite XML format is used since the UPnP packages implicitly provide support for it, and it nicely contains all the relevant metadata for a single radio station.

<?xml version="1.0" encoding="UTF-8" ?>
<DIDL-Lite xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp">
<item>
  <upnp:class>object.item.audioItem.audioBroadcast</upnp:class>
  <dc:creator>Bill &amp; Rebecca</dc:creator>
  <dc:title>Radio Paradise</dc:title>
  <upnp:genre>Rock</upnp:genre>
  <dc:description>Eclectic Mix of Adult Rock</dc:description>
  <upnp:region>US - Northern California</upnp:region>
  <dc:language>English</dc:language>
  <dc:relation>http://www.radioparadise.com</dc:relation>
  <upnp:radioCallSign></upnp:radioCallSign>
  <upnp:radioStationID></upnp:radioStationID>
  <upnp:radioBand>Internet</upnp:radioBand>
  <res protocolInfo="http-get:*:audio/mpegurl:*" bitrate="16384">http://www.radioparadise.com/musiclinks/rp_128.m3u</res>
  <res protocolInfo="http-get:*:audio/mpegurl:*" bitrate="8192">http://www.radioparadise.com/musiclinks/rp_64.m3u</res>
  <res protocolInfo="http-get:*:audio/mpegurl:*" bitrate="4096">http://www.radioparadise.com/musiclinks/rp_32.m3u</res>
</item>
</DIDL-Lite>



Database Field Notes

Radio stations commonly transmit multiple types of content. The convention used for the station database is to allow multiple genres to be specified in the genre field, separated by commas. The convention used for sub-genres (e.g. 'Rock/Metal') is to use a '/' to separate the genre/sub-genre. Lastly, for stations that do support multiple genres, the primary genre is always specified first in the comma-separated list. This is done so that for MediaRenderer clients that may be confused by multiple genres, the server can trim back the genre field to only the primary field when responding to UPnP browse requests.

The current list of genres in the default database is: Ambient, Alternative, Classical, College, Country, Dance, Folk, House, Indie, Jazz, Latin, New Age, News, Public Radio, Rock, Rock/Pop, Rock/Metal, Techno, Top Hits, Top Hits/80's, and Trance. Note that we make no claims regarding the proper choice of genre(s) for each station - users should feel free to adjust them as appropriate!

One piece of information that is sometimes of interest when listening to Internet radio is the station's primary geographical location. This is specified using the 'upnp:region' field. The UPnP specification leaves the exact format of the content of this field unspecified. The convention used here is to specify the country first, followed by a '-', followed by the 'region' within that country. For well known cities (New York, London), the city name is sufficient. For smaller cities, a more general term is specified (e.g. 'Northern California'). This convention is not cast in stone, and deviations from it certainly won't break anything.

Stations that actually transmit on the airwaves will have non-blank radio call sign and radioStationID (frequency) elements, and the radioBand element will be set to the band of the transmission (AM,FM, etc...) instead of 'Internet' (which in the context of the database really means 'Internet-Only')

The current default station database consists of approximately 60 stations. All of the URLs currently stored in the database refer to MP3 streams. Additional URLs for other formats can be added to existing stations if desired, since each station file supports an arbitrary number of resources for streaming audio access. There is no nice UI for modifying the database yet, so for the time-being changes to station files must be accomplished via hand-editing.

Server Browse Tree

The server generates a multi-level browse tree from the station database. For each station in the AllStations directory, the following tree of nodes is generated.

A screenshot of the default browse tree presented by the radio server is shown below. Note that the browse tree nodes at the individual station level and above simply reflect the heirarchy of the radio station database directory tree stored on disk. The user can easily customize the station heirarchy by simply modifying the disk directory structure

Proxy Mode

Ths server supports a proxy mode that can function as a 'repeater' to enable a single connection to an Internet radio station to serve multiple devices inside the home. The proxy mode simply converts radio station URLs of the form:

 http://stationHost:stationPort/station.pls

to the form:  http://proxyHost:proxyPort/stationHost:stationPort/station.pls

before sending them to the requesting device. Media renderers then request their content from the HTTP proxy server running within the radio server rather than from the external Web address of a radio station.

Multi-Renderer Synchronization

When the server is operation in proxy mode, it has the opportunity to try to ouput data in a synchronized fashion to multiple devices. In the absence of an accurate network-wide time reference and sync-aware media renderer devices, this is limited to simply feeding data to the multiple devices of the same type as synchronously as possible. The assumption that makes this possible is that the output streams to devices of the same type have the same end-to-end buffering capacity. As long as the streaming source takes care to balance the streams so the buffers are 'equally full' for all devices in a synchronized group, some degree of synchronization can typically be achieved.

This feature is still only partially implemented, and synchronization logic is only being executed at the start of a playback session. The only way to use this sync logic at the moment is to start the multiple renderers within the sync period of the server (default of 4 seconds, but can be increased). This is best accomplished via the media controller, not the remote controls of the devices themselves (otherwise a different form of 'shoutcast' between 2 people may be required to start devices in different rooms!). Using this method, synchronization is generally achieved at the start, inter-device timing drift can result in a gradual loss of sync over time (1-2 hours). The only way to currently deal with this is to restart the stream to re-sync it.

This feature obviously isn't quite ready from the perspective of user-friendly interaction - it's described here for purposes of experimentation only at this point!

Web Page Presentation

The UPnP device specification supports an optional (but recommended) 'presentation' URL which is typically used to allow Web-based access to status and/or configuration data for a given device. The radio server supports this by providing a simple status page containing the run-time settings and a dynamically generated Web page with a list of all the current stations. The simplest way to access the page is via the Media Controller's Options->DeviceInfo menu. No run-time configuration of the device is supported at this time via the Web interface.

Command-Line Arguments and User Preference Files

The radio server supports user preferences via Java property files, which use a simple text-based format. These property files are currently only hand-editable (no Web interface), but the need to actually edit the file is reduced by the support of the most commonly changed options via command-line arguments.

Supported command-line options

Usage: java RadioServer [-v] [-p] [-s syncWaitPeriod] [-w webPageDir]

Hand-editing the user-specific preference file

If modifying the preferences by hand, it is useful to understand a little bit about how the preferences mechanism is set up, especially with regard to how things are handled with regard to software updates. There are two copies of the preferences file used by the controller, one containing the 'factory default' settings ($INSTALL_DIR/properties/RadioServer.properties) and one containing the user-specific settings ($USER_HOME/.cidero/RadioServer/RadioServer.properties). At startup, the default settings are loaded first, followed by the user settings. The user-specific preferences override the defaults. If the user preferences file does not exist (first time application is run), it is created by making a copy of the default file. When the radio server software is updated, some preferences may have been added or removed. Addition of the new preferences, and removal of preferences that are no longer supported, is handled automatically at server startup. Note that if hand-editing the file corrupts the file somehow, the simplest fix is to remove the file and re-run the application to create a new one.