|
Last revision: 2003-02-06 by Mayhem &
Chaos
Table of Contents
Introduction
The MusicBrainz Metadata Initiative is designed to create a portable
and flexible means of storing and exchanging metadata related to digital
audio and video tracks. The MusicBrainz Metadata Initiative is a content
description model for audio and video tracks on the Internet.
The MM Initiative uses
RDF/XML to facilitate the exchange
of audio/video related metadata. This document describes an RDF namespace
that should be used in conjunction with the
Dublin Core metadata recommendation.
This specification will be used by the MusicBrainz.org metadata server
to communicate metadata queries. All the data returned from the server will
be in the MM/Dublin Core RDF format.
This initiative defines the following namespaces:
| Namespace |
Namespace URI |
|---|
| mm |
http://musicbrainz.org/mm/mm-2.1# |
| mq |
http://musicbrainz.org/mm/mq-1.1# |
| mem |
http://musicbrainz.org/mm/mem-1.0# |
The namespace abbreviations (mm, mq, mem) will be used throughout
the remainder of this document, to refer to the namespaces defined above.
[ MusicBrainz RDF Example |
RDF Information |
Dublin Core Home Page]
General Protocol Definition
The metadata queries defined here are carried over the HTTP/1.1
protocol. By using the HTTP/1.1 protocol, the metadata query system
can take advantage of existing HTTP implementations and pass
through firewalls without any special considerations.
A MM enabled server must implement HTTP/1.1 fully, unless otherwise
noted in this document. Furthermore, an MM server should listen for
requests on port 80, following the standard HTTP convention to allow the
metadata requests to flow across firewalls unhindered.
Character Encodings
In order to achieve the most versatile international support in this
protocol, the recommended encoding for use with this protocol is UTF-8. However, the
XML/RDF that is POSTed to the server by a client can be in any XML
compliant character encoding. The server will convert any incoming
data to UTF-8 and process it in UTF-8 and respond to the client
using the UTF-8 encoding.
Client Requests
Client requests may either use the HTTP GET or POST commands. All of
the functions provided by the server are accessible via POSTing
query/submission data in RDF format to the MM capable server.
Other methods (OPTIONS, HEAD, PUT, DELETE, TRACE, CONNECT) will
receive an error response.
Some functions may have GET command shortcuts to ease the implementation
on the client side. However, any functions that must pass data to the server
that may not be encodable into a compliant URL, do not have GET functions
defined, and the POST functions should be used instead.
For example, the searching functions require that a search string be
passed to the server. However, using a GET function requires the
search string to be encoded into a valid URL, which must be encoded
in the ISO-8859-1 character encoding. Thus, search functions using the
GET command cannot correctly search all of the data available on the
server.
The specific details for accessing the server features with GET and POST
commands are described in the following namespace definitions. For
each RDF examples given in the sections below, the client can POST
that RDF document to the server.
Server Responses
Server responses are compliant with the HTTP/1.1 protocol, and
the data returned in the body of the response is in XML/RDF format
described in the following sections.
Only the following status codes and reason phrases are valid:
- 200 OK - Successful query and normal response.
- 202 Accepted - Submission accepted and batched for review or merge.
- 204 No Content - Query was understood but there is no content. As
in HTTP/1.1, there must not be a message body following this status code.
- 400 Bad Request - There was an error processing the request. This
may also be used for 405 Method Not Allowed since only one method is
allowed.
- 403 Forbidden - The server refuses to process the request. Used
for refusal to accept metadata submissions.
- 500 Internal Server Error - Random catch-all for server errors.
This indicates a bug in the server software, otherwise pass a status 503.
- 503 Service Unavailable - The server is temporarily unable to service
this request, although it may have been valid. Clients are advised to
try another MM server if this message is received.
Required headers:
- Server: - Server name and version number.
- Date: - Server date, as per HTTP/1.1.
- Content-type: - "text/xml" is the only valid return content type.
Optional headers:
- Connection: - The "close" value is required here for implementations
not supporting persistent connections, as in HTTP/1.1.
mm: MusicBrainz Metadata Namespace
The mm namespace defines RDF classes and properties for expressing basic
music related metadata. This namespace intentionally focuses on the primitives
for metadata; more detailed metadata will be supported in the
MusicBrainz Extended Metadata Namespace.
Classes
Artist
[Example]
|
This class is used to describe an Artist. Inside of Artist, use dc:title,
mm:sortName, and mm:albumList to describe the name and sortname of the artist
as well as a list of albums available by that artist.
|
Album
[Example]
|
Use this to describe an Album. The dc:title, dc:creator and mm:trackList
properties should be used to describe the album.
|
Track
[Example]
|
Use Track to describe one audio track. Use the dc:title, mm:trackNum,
dc:creator, mm:trmId properties to descibe a track.
|
Properties
|
sortName
|
Use this to indicate the name of an artist for use in an alphabetically
sorted list. If the dc:title field for an Artist contains "The Beatles",
this field should contain "Beatles, The".
|
|
trackNum
|
This indicates the sequence number for a track in a given album. trackNum will only
be used if a track number must be specified outside of the context of an album. When
tracks are described inside of an album context, then the track list order defines
the track number implicitly. Track numbers start with 1.
|
|
trmid
|
This property is used to indicate a Relatable TRM ID for an audio track.
|
|
cdindexid
|
Used to describe a Disc ID for a CD-ROM.
|
|
duration
|
Used to indicate the duration of a track in milliseconds.
|
|
releaseType
|
Indicates the type of a release. The possible values are: TypeAlbum, TypeSingle, TypeEP, TypeCompilation, TypeSoundtrack, TypeSpokenword, TypeInterview, TypeAudiobook, TypeLive, TypeRemix, TypeOther.
|
|
releaseStatus
|
Indicates the status of a release. The possible values are: StatusOfficial, StatusPromotion, StatusBootleg.
|
|
artistList
[Example]
|
This property is used to convey a list of artists.
|
albumList
[Example]
|
This property is used to describe a list of albums.
|
trackList
[Example]
|
This property is used to convey a list of tracks.
|
cdindexidList
[Example]
|
This property is used to describe a list of Disc IDs in an album.
|
trmidList
[Example]
|
This property is used to describe a list of TRM IDs in a track.
|
mq: MusicBrainz Query Namespace
The mq namespace defines RDF classes and properties that facilitate
metadata lookups between an RDF enabled client and a MusicBrainz
metadata server.
Classes
Result
[Example]
|
The Result class is used to encapsulate all of the server responses. It
will contain a mq:status property which contains a query status code from
the server. Currently only OK is defined as a valid value. The Result
class will also contain one artistList, albumList or trackList, depending
on what type of query was executed by the server.
|
SubmitTrack
[Example]
|
This class is used to submit metadata for one track. Not currently supported
on the main server.
|
LookupMetadata
[Example]
|
This class is used to lookup metadata for one track. This query returns
the same data that ExchangeMetadata returns, but no metadata is sent to
the server. Please consider using ExchangeMetadata whenever possible in
order to contribute metadata back to the server.
|
FindDisctinctTrmId
[Example]
|
Use the FindDistinctTrmId class to query the server about a trmid. Given
mq:artistName and mq:trackName the server will find a track that matches
the two criteria and return one track in a trmidList.
|
FindArtist
[Example]
|
The FindArtist class can be used to query the server for artists that
match a given search string. Use mq:artistName to specify the search
string.
|
FindAlbum
[Example]
|
The FindAlbum class can be used to query the server for albums that
match a given artist and album search strings. Use mq:artistName and
mq:albumName to specify the search strings.
|
FindTrack
[Example]
|
The FindTrack class can be used to query the server for tracks that
match a given artist, album and track search strings. Use mq:artistName,
mq:albumName, and mq:trackName to specify the search strings.
|
GetCDInfo
[Example]
|
Use the GetCDInfo to retrieve metadata for a given CD. Use the mm:cdindexId
property to specify the Disc ID.
|
SubmitTRMList
[Example]
|
Use this query to submit a list of TRM ID and track id pairs. The pairs
must be submitted in a mq:trmTrackPair inside of a mm:trmidList Sequence.
|
Properties
|
status
|
This property specifies the result status of the query. Currently the
only valid value is OK.
|
|
depth
|
The depth property allows the client to set the level of information
that is returned by the server. Using a depth of 1 will only return
the topmost list of resources. Using a depth of 2 will return all of the
resources referenced by the topmost list of resources. Each subsequently
higher value of depth will return more information.
|
|
artistName
|
|
|
albumName
|
|
|
trackName
|
|
mem: MusicBrainz Extended Metadata Namespace
The mem namespace is reserved for future use in expressing extended
music related metadata that is not covered by the MusicBrainz
Metadata Namespace. This namespace will focus on the more detailed
metadata such as contributors, roles, lyrics, release dates, remix/cover
information, etc.
|
Contact details
