gnomoradio.org

Gnomoradio Metafile Specification

by Jim Garrison
May 28, 2004
Updated October 30, 2004

This document describes the specification for RDF files that describe songs, artists, and albums on Gnomoradio. This specification is a superset of Creative Commons' specification for RDF metadata. Knowledge of XML is helpful to those reading this document.

Introduction

Gnomoradio is a peer to peer music playing system that allows independent bands and musicians to promote themselves. It is an opt-in service for musicians who wish to allow peer to peer file sharing.

As such, it requires technology that allows bands to publish their music along with details about file sharing permissions. Creative Commons has already designed licenses that fit this description. These licenses all fall under the same umbrella, and they are supported and maintained in the same way. In addition, Creative Commons has designed an RDF specification for describing these licenses.

Gnomoradio RDF Overview

Unfortunately, CC's current metadata specification is incomplete when it comes to describing files to be shared. Therefore, we have created our own superset of CC metadata that derives from their RDF classes. In particular, we have only modified and expanded the section of RDF that applies to CC resources; we have not modified the RDF sections that describe the licenses themselves. There are a number of modifications we made.

First of all, Gnomoradio separates the notion of a resource (a song/recording) from its representation (a file). In this way, it understands when multiple files represent the same recording in different formats (mp3, ogg, even different bitrates). This is crucial to an abstract user interface. A user should not need to care about file formats. It is the song that matters, and the program should take care of finding and obtaining the appropriate file to represent that song.

Secondly, Gnomoradio verifies each file that it downloads against a sha1 checksum, which is described in a the RDF metadata describing the file. This is useful to combat viruses and hoax files on the network.

Finally, there are many other pieces of metadata that Gnomoradio supports that are not specifically mentioned in CC's RDF spec. These include a location for the band's web site, a place to purchase an album online, cover art for albums, song lyrics, and other useful features.

Another problem with current CC metadata lies in how people implement it. Often, authors will use rdf:about="", which makes it difficult to determine exactly what the license applies to. There is usually a written notice to describe what the CC license applies to, but the machine is often left in the dark. This act makes it easy to embrace and promote CC licenses, but it is not good enough for Gnomoradio to function properly.

Rainbow Builder

Understanding of this document is in no way necessary for an artist to be distributed using Gnomoradio. The easiest way to prepare an RDF document is to use the Rainbow Builder, a web application that will produce this metafile in a user-friendly way.

Hopefully, online music sites will find it beneficial to produce RDF files for the artists that they host in the near future. This will further lessen the difficulty of creating RDF files for the artist. In addition, Gnomoradio itself will drive further traffic to these sites and relieve them of bandwidth for distributing audio files.

Publishing the metafile

The metafile as described below, or as produced by Rainbow Builder or a similar system, must be published on the world wide web for Gnomoradio to recognize it.

One way to publish a file is to upload it in its entirety to a web server. The specific mime type is not essential, but it should be something such as text/plain, or ideally application/rdf+xml.

A second way of publishing the metafile that Gnomoradio supports is the embedding of an RDF document within a comment block of an html file. If this method is chosen, it is important to consider that only one RDF file should be embedded in a given HTML file for Gnomoradio to find it. Thus, if an HTML document already contains a different type of RDF, it is best to put the Gnomoradio metadata in a separate file.

RDF Essentials

People who are unfamiliar with RDF may find it helpful to read an introduction, such as the RDF Primer.

Summary of namespaces

"rdf" is the namespace that describes rdf itself. "dc" and "dcterms" are built on top of rdf to describe general features of an object. The "cc" namespace further builds upon this work, describing details of licenses for resources.

Gnomoradio's RDF adds two more namespaces onto this. The first is rainbow ("rbow"), which is used to describe file resources in a reliable way for file transfers. The second namespace is gnomoradio, which describes songs, artists, albums, and how they relate to files described by rainbow resources.

Before publishing or describing a song through RDF, it is necessary to describe an actual file that represents that song. Rainbow resources represent files of any type--audio, images, etc, that can be transferred via peer to peer. They are most often licensed under a Creative Commons license, so that file sharing can take place legally.

Songs and albums are then described in the gnomoradio namespace with links to the rainbow resources that represent them. This may seem more straightforward after looking at an example.

Here is a sample RDF file, which in its totality represents four songs off the album Science in the Hand of an Angry God by Tommy Magik and the Wonderfulls (the author's band). Only part of the file is shown below, describing the album itself and one of the four songs. The full file is available at http://www.tommymagik.com/discography/science.rdf.

<?xml version="1.0"?>	The standard XML 1.0 header
<rdf:RDF xmlns="http://gnomoradio.org/gnomoradio/1.0.rdf#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:cc="http://web.resource.org/cc/" xmlns:rbow="http://gnomoradio.org/rainbow/1.0.rdf#"	This begins the RDF block, and declares the XML namespaces that will be used. From the ground up, this includes rdf, dc, dcterms, cc, rbow, and gnomoradio. Notice that the default (implicit) namespace is gnomoradio for the rest of the file.
xml:base="http://www.tommymagik.com/discography/science.rdf">	This tag is optional. If it exists, it is very important that this point to the actual URL where the file (itself) can be retrieved. Every `#something` URL will be fetched relative to what this URL is set to (which should be the current file)
<Album rdf:ID="science">	This begins the description of an album, which is not necessary for a song to be on Gnomoradio. Given this ID, the album can now be referred to with the URL `http://www.tommymagik.com/discography/science.rdf#science`.
<dc:title>Science in the Hands of an Angry God</dc:title>	The title of the album
<dc:creator rdf:resource="http://www.tommymagik.com/tmatw.rdf#tmatw"/> <dc:rights rdf:resource="http://www.tommymagik.com/tmatw.rdf#tmatw"/>	Links to the creator and holder of the rights to the album. This should link to the RDF description of an artist, which is described later in this document.
<dc:date>2002-6-27</dc:date>	Date the album was/will be released (optional)
<retail rdf:resource="http://www.tommymagik.com/discography/"/>	a link to a site with information about purchasing the album (optional)
<img src="http://www.tommymagik.com/images/dinosaur-opening.jpg"/>	An image that can be used to described the album (optional)
<tracks> <rdf:Seq> <rdf:li>We Can Turn to Ronnie James Dio</rdf:li> <rdf:li rdf:resource="#glassheart"/> <rdf:li>Hide and Seek</rdf:li> <rdf:li rdf:resource="#grundel"/> <rdf:li>Darwinian Love Song</rdf:li> <rdf:li>Raging Asexual Disaster</rdf:li> <rdf:li>Malachi Alladbay</rdf:li> <rdf:li rdf:resource="#firefly"/> <rdf:li>Sweet Ginger</rdf:li> <rdf:li rdf:resource="#robot"/> <rdf:li>David Bowie was an Open Door</rdf:li> </rdf:Seq> </tracks>	This describes the tracks on an albums, in order. Songs that are available to Gnomoradio are referenced by the URL of the Recording that describes them (Recording syntax is below). Songs that are not available to Gnomoradio are referenced by their title only. (Note that the RDF of only one song is displayed below. In the actual file, all four are described.)
<</Album>	End of album block
<Recording rdf:ID="glassheart">	This begins the description of a recording which is featured on Gnomoradio under a CC license. The URL for this recording is now `http://www.tommymagik.com/discography/science.rdf#glassheart`.
<dc:title>Glass Heart, Stars, Moons and Clovers in the Midst of Eternity</dc:title>	Song title
<dc:creator rdf:resource="http://www.tommymagik.com/tmatw.rdf#tmatw"/>	Link to the RDF of artist that recorded the song (as described below)
<dcterms:isPartOf rdf:resource="#science"/>	Link to the RDF describing an album that the recording is featured on. There can be zero, one, or more albums in this section of the RDF (with a separate tag for each).
<cc:license rdf:resource="http://creativecommons.org/licenses/by-nd-nc/1.0"/>	Link to the RDF that describes what license the song can be distributed under
<audiofile rdf:resource="#glassheart_mp3"/>	This is a link to an rbow:Resource block, which in turn describes a file. There can be multiple files that represent a given recording (different formats like mp3/ogg, different bitrates, etc), and each representation of the file is given its own rbow:Resource block and refernenced here. In this case, there is only one available representation of the recording online.
<lyrics> Trapped in your eyes.<br/> Break this medusa gaze.<br/> Another fabricated smile<br/> wasted on me.<br/> </lyrics>	Lyrics to the song, with line breaks in xhtml as shown (optional)
</Recording>	End of recording block
<rbow:Resource rdf:ID="glassheart_mp3">	This begins the description of the resource/file which represents the Recording `#glassheart`. The URL for this resource is now `http://www.tommymagik.com/discography/science.rdf#glassheart_mp3`.
<rbow:available rdf:resource="http://www.tommymagik.com/~garrison/tmatw/Glass%20Heart.mp3"/>	This is a standard URL where the file can be downloaded. Once the file is widely available on the file sharing system, this is no longer necessary to have, but it is still useful.
<representationOf rdf:resource="#glassheart"/>	Link back to the Recording that this Resource represents, as described above
<cc:license rdf:resource="http://creativecommons.org/licenses/by-nd-nc/1.0"/>	License that the resource can be distributed under. This should be consistent with the license given for the Recording above.
<dc:format>audio/mpeg</dc:format>	Mime type of the audio file, which is usually audio/mpeg or audio/ogg
<rbow:checksum>a53260f2624d9d15a6b7c6e3cfd1f86b87f32229</rbow:checksum>	sha1 checksum of the resource
</rbow:Resource>	End of resource block
<cc:Agent rdf:about="http://www.tommymagik.com/tmatw.rdf#tmatw">	This block describes the artist. In this case, the RDF that describes the band is actually located in another file, so that many different RDF files can reference it easily. Still, we have included a summary of its contents in this file, and that is why `rdf:about` has been used. Otherwise, we could have used rdf:ID as before.
<dc:title>Tommy Magik and the Wonderfulls</dc:title>	Artist or band name
<website rdf:resource="http://www.tommymagik.com/"/>	Link to the web site of the artist (optional)
<img src="http://www.tommymagik.com/images/tmatw.png"/>	An image that can be used to describe the artist (optional, and not yet implemented or used in Gnomoradio)
</cc:Agent>	End of artist block
<cc:License rdf:about="http://creativecommons.org/licenses/by-nd-nc/1.0"> <cc:requires rdf:resource="http://web.resource.org/cc/Attribution"/> <cc:permits rdf:resource="http://web.resource.org/cc/Reproduction"/> <cc:permits rdf:resource="http://web.resource.org/cc/Distribution"/> <cc:prohibits rdf:resource="http://web.resource.org/cc/CommercialUse"/> <cc:requires rdf:resource="http://web.resource.org/cc/Notice"/> </cc:License>	It is very useful, but not necessary, to describe any licenses that were referenced in the file. This way, Gnomoradio does not have to fetch the licenses separately to determine the exact terms of them.
</rdf:RDF>	Ends the RDF document block

Please feel free to contact me if you still have any questions.

Jim Garrison <garrison@gnomoradio.org>