M3F

From XiphWiki
Jump to navigation Jump to search


See other suggested metadata methods.

This document describes the proposed Multimedia Metadata Format (M3F) for the Ogg Container. The format is built on the Extensible Markup Language (XML). It is intended to describe any kind of multimedia (audio, video, text, images, …) that can reside in an Ogg container.

HELP IS NEEDED!! See the ogg-dev email list or contribute directly to the wiki.

Format description

Multimedia Metadata Format documents describe media resources in Ogg containers and stream. The format can link resources with one another for media players that support rendering multiple kinds of media. (Such as audio tracks and albumart; and video and commentary audio overlays.)

No element except ‘metadata’ is required. But some elements have required attributes.

All dates must be formatted as ISO 8601:2000 – International Date and Time Format.

XML declaration and name spaces

A metadata document must have a standard XML declaration on the very first line. The XML deceleration must contain the ‘version’ and ‘encoding’ attributes; as shown in the below example:

<?xml version="1.0" encoding="UTF-8" ?>

The ‘metadata’ element is required as the top level container. It must contain at least one XML name space defining the format via the ‘xmlns’ attribute. (The URL used in the example is not the final address as no name space have been created yet.)

<metadata xmlns="http://xmlns.xiph.org/metadata/0.1/">
	[…]</metadata>

The Multimedia Metadata Format can be extended by including multiple XML name spaces to the ‘metadata’ element. As with any other XML format: Software may not add, modify, or expect elements and attributes not defined by a XML name space.

Addressing the media resource

Media resources in the stream is described as ‘resource’ children of the ‘metadata’ element. Each resource element must have a ‘oggserial’ linking it to the correct chunk in the stream. It must also have a ‘type’ attribute with the native MIME type of the resource.

<resource oggserial="0×EXAMPLE" type="audio/vorbis">
	[…]</resource>

The ‘uri’ attribute may be used in stead of ‘oggserial’. For ogg serials the URI would be ‘urn:oggserial:#0×EXAMPLE’. (Other container and native file formats may specify any URI that works with that format.)

Resource elements can also have an optional unique ‘id’ attribute. The ‘id’ attribute is used as a label when the resource needs to be addressed by another resource element.

<resource id="unique-resource-id" […]>
	[…]</resource>

Describing the media resource

There are many children elements of the ‘resource’ element. All are optional and everyone can be used with any resource. Though media type spesific children are grouped together. These children does not make much sense with all media types

Describing audiences

The ‘audience’ element is a self-regulated filtering mechanism intended for parental control and self-regulated filtering. The optional ‘nudity’ attribute is a space separated list with one or more of the following values ‘breasts’, ‘buttocks’, and ‘genitals’. The optional ‘sexual’ attribute is a space separated list of with one or more for the following values ‘kissing’, ‘sexact’, ‘touching’, ‘sexlanguage’, ‘erections’ and ‘erotica’. The optional ‘violence’ attribute is a space separated list with one or more of the following values ‘rape’, ‘human-injury’, ‘animal-injury’, ‘anime-injury’, ‘human-blod’, ‘animal-blod’, ‘anime-blod’, ‘human-torture’, ‘animal-torture’, and ‘anime-torture’. The optional ‘language’ atribute is a space separated list with one or more of the following values ‘vulgar’, ’swear’, and ‘mild’. The optional ‘harmful’ attribute is a space separated list with one or more of the following values ‘tobacco’, ‘alcohol’, ‘drug’, ‘weapons’, ‘example-dangerous’, ‘horror’, and ‘discrimination’. The required ‘context’ attribute is a space separated list with one or more of the following values ‘artistic’, ‘educational’, ‘medical’, ’sports’ and ‘news context’.

<audience context="education" language="mild" nudity="sexact kissing" […] />

Note: The filters are based on Internet Content Ration Associations' (ICRA) work. See their label generator for full meaning of values.

Describing categories

The ‘category’ element describes the listing genre of the resource. The required ‘sort’ attribute describes the preferred genre for listing.

<category sort="metal">
	[…]</category>

The optional ‘genre’ child element describes more in-depth sorting for the resource.

<category sort="metal">
	<genre>symphonic metal</genre>
	<genre>goth metal</genre>
</category>
Describing collections

Media resources may appear in collections (DVD set boxes, CD albums, etc.). The ‘collection’ element describes the resources relation and order/place in collections. The optional ‘date’ attribute describes the date the collection was made publicly available (its ‘release date’). The optional ‘track’ attribute describes the resource's order/place in the collection. The optional ‘tracks’ attribute describes the total number of resources in the collection. The optional ‘uri’ attribute should uniquely identify the collection as a whole.

<collection date="2019-01-15" track="2" tracks="12" uri="urn:x-isrc:0123456789">
	[…]</collection>

The optional ‘artwork’ child element links the collection to a image resource. The required ‘uri’ attribute should either be a resource's ‘id’ attribute value with a ‘#’ prefix (as below) or a web URL resource. The optional ‘type’ attribute should be the MIME type of the image resource. The attribute should not be used when linking to other internal resources; but is encurraged when linking to external resources (such as web URLs).

<collection>
	<artwork uri="#embedded-image" />
</collection>

The optional ‘title’, ‘subtitle’, and ‘tagline’ child elements function as the ‘resource:title’ element.

<collection>
	<title>Great Audio VI</title>
	<tagline>Music that rocks you!</tagline>
</collection>

Note that CD singles are indeed collections too.

Describing encodings

The ‘encoding’ element describes the encoding or digitalization of the resource.

<encoding>
	[…]</encoding>

The optional ‘date’ child element describes when the last file encoding happen. When the file is re-encoded another date element should be added with the new date..

<encoding>
	<date>2019-01-21</date>
</encoding>

The optional ‘source’ child element describes the original media source for the encoding. The required ‘media’ attribute should be either ‘cd’, ‘dvd’, ‘tape’, ‘web-stream’, ‘tv-stream’, ‘radio-stream’, or ‘unknown’. The optional ‘uri’ attribute should uniquely identify the media.

<encoding>
	<source media="cd" uri="urn:x-isrc:0123456789" />
</encoding>

The optional ‘software’ child element describes the softwares used for the encoding. The optional ‘title’ attribute describes the software name. The optional ‘version’ attribute describes the software version. The required ‘uri’ attribute should uniquely identify the software (and version).

<encoding>
	<software title="flac" version="2.2" uri="http://xiph.org/flac/" />
</encoding>
Describing recordings

The ‘recording’ element describes recording conditions.

<recording>
	[…]</recording>

The optional ‘date’ child element describes when the recording was made.

<recording>
	<date>2018-10-17</date>
</recording>

The optional ‘duration’ child element describes how long the recording lasts. This value must be specified as a colon separated value containing days:hours:minutes:seconds:milliseconds. When the value is low enough to not use a field it should be left blank or have the value zero (‘0’). The below examples says zero days, zero hours, seven minutes, four seconds, and 54 milliseconds.

<recording>
	<duration>::07:04:54</duration>
</recording>

The optional ‘location’ child element describes when the recording was made in a human readable-way. The optional ‘lat’ and ‘long’ attributes are the machine-readable latitude and longitude position of the recording.

<recording>
	<location lat="22.20N" long="114.11E">Hong Kong, China, Earth</location>
</recording>
Describing rights

The ‘rights’ element describes the Copyright and license status of the resource.

<rights>
	[…]</rights>

The optional ‘date’ child element describes when the Copyright were put in place. This is especially useful when determining when a work's Copyright expires.

<rights>
	<date>2018-10-20</date>
</rights>

The optional ‘license’ child element is a short and human-readable version of the full license.

<rights>
	<license>© 2018 Recording Company. All distribution rights reserved.</license>
</rights>

The optional ‘link’ child element can point to any URI via it's ‘uri’ attribute where a full version of the license is available. This means it can be pointed to a ‘resource’ element via it's ‘id’ attribute as well!

<rights>
	<link type="text/html" uri="http://licenses.record-company.com/artist.html" />
</rights>
Describing titles, subtitles, and taglines

The ‘title’ element describes the resource's title.

<title>Awesome Audio Track</title>

The ‘subtitle’ element describes secondary title.

<subtitle>The Sound of Music</subtitle>

The ‘tagline’ element describes promotional taglines and slogans.

<tagline>Get to the real sound!</tagline>

Below are media type specific children of the ‘resource’ element. The elements are grouped by the media type they describe.

History

  • 2007-11-25 – Began work with simplifying the format.
  • 2007-09-08 – Wiki page created based on original format and suggestsion from the email list.
  • 2007-09-06 – Format suggested on Xiph's ogg-dev email list by Daniel Aleksandersen.