It's XML, of course

This page documents the file formats used by Radio UserLand.

There are two formats, outlineDocument and songList.

There's a simple XML-RPC interface that allows a user to register with an aggregator.

All formats are open and public and may be used for any purpose whatsoever.

outlineDocument

All playlists are outlineDocuments. This is the main file format for Radio UserLand. When you create a new file it's saved as an outlineDocument. Because users can save them into the www folder, they can be accessed over the Web, either from a script or a Web browser such as MSIE. (Of course they could be served by any HTTP server, not just the Radio UserLand server.)

The outlineDocument format is <a href="http://backend.userland.com/stories/storyReader$53">documented</a> on backend.userland.com. There will no doubt be changes and refinements to the format. One area that needs work is the format for the data attribute on a headline. Currently there are bugs in the way Radio UserLand uses this attribute. (Every headline gets a data attribute, whether or not it links to a song. We need to XMLize this and fit in data not as an attribute but as a legal sub-item. Shouldn't be hard to do, and with this caveat, breakage should be expected.)

Radio UserLand can be used to write any kind of document, not just a music playlist. Outlines are great for all kinds of structured documents, specifications, legal briefs, product plans, presentations and stories.

Several examples of outlineDocuments created with Radio UserLand: play list, specification, presentation.

songList

As you're listening to music, Radio UserLand keeps track of what you listen to. Here's a <a href="http://static.userland.com/images/radiodiscuss/userPlaylistSongs.gif">screen shot</a> of the table, user.playlist.songs, that keeps track of the stuff.

ctPlays is the number of times the song has been played. ctSeconds is the duration of the song, determined by a heuristic that's pretty accurate. f is the file that contains the MP3, on the local file system. whenFirstPlayed is the time/date the song was played for the first time, whenLastPlayed is the most recent time/date. whenLoaded is when Radio UserLand discovered the file in your MP3 folder.

Every hour on the hour Radio UserLand generates an XMLization of this table and places it in the userland folder of your www folder, making it available over the Web. (There's no way to turn this feature off, there should be.)

Here's an <a href="http://static.userland.com/gems/radiodiscuss/songs.xml">example</a> of the XML file. The mapping between the table and the XMLization should be fairly clear.

Rules of the road

Rules of the road will be determined later, since many of these files will be on users' machines, we want to provide guidelines for bots, aggregators and content systems; and whatever other kinds of applications people think of. Feel free to use the discussion group here to raise issues.