W3C

API for Media Resource 1.0

W3C Working Draft @@ April 2009

This version:
http://www.w3.org/TR/2009/WD-mediaont-api-1.0-200904@@
Latest version:
http://www.w3.org/TR/mediaont-api-1.0
Editors:
WonSuk Lee, Electronics and Telecommunications Research Institute (ETRI)
Florian Stegmaier, University of Passau
Chris Poppe, Ghent University

Copyright  © 2009  W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use rules apply.

Abstract

This specification defines a client-side API to access metadata information related to media resources on the Web. The overall purpose of the API is to provide developers an with a convenient access to metadata information stored in different metadata formats. The API will be introduced in an abstract manner using the interface definition language Web IDL. Thereby, the Media Ontology Core Properties will be used as a pivot vocabulary in the API.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the First Public Working Draft of the API for Media Resource 1.0 specification. It has been produced by the Media Annotations Working Group , which is part of the W3C Video on the Web Activity .

Please send comments about this document to public-media-annotation@w3.org mailing list ( public archive ).

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .

Table of Contents

1 Introduction
    1.1 Formats in scope
    1.2 Formats out of scope
    1.3 Terminology
2 API Description
    2.1 Design consideration
    2.2 API for Descriptive Properties
        2.1.1         2.2.1 Identification Properties
            2.1.1.1             2.2.1.1 Identifier
            2.1.1.2             2.2.1.2 Title
            2.1.1.3             2.2.1.3 Language
            2.1.1.4             2.2.1.4 Locator
        2.1.2         2.2.2 Creation Properties
            2.1.2.1 Contributor             2.2.2.1 Contributors
            2.1.2.2 Creator             2.2.2.2 Creators
            2.1.2.3             2.2.2.3 CreateDate
            2.1.2.4             2.2.2.4 Location
        2.1.3         2.2.3 Content description Properties
            2.1.3.1             2.2.3.1 Description
            2.1.3.2             2.2.3.2 Keyword
            2.1.3.3             2.2.3.3 Genre
            2.1.3.4             2.2.3.4 Rating
        2.1.4         2.2.4 Relational Properties
            2.1.4.1             2.2.4.1 Relation
            2.1.4.2             2.2.4.2 Collection
        2.1.5         2.2.5 Rights Properties
            2.1.5.1             2.2.5.1 Copyright
            2.1.5.2             2.2.5.2 License
        2.1.6         2.2.6 Distribution Properties
            2.1.6.1             2.2.6.1 Publisher
            2.1.6.2             2.2.6.2 TargetAudience
        2.1.7         2.2.7 Fragments Properties
            2.1.7.1             2.2.7.1 Fragments
            2.1.7.2             2.2.7.2 NamedFragments
    2.2     2.3 API for Technical Properties
        2.2.1         2.3.1 FrameSize
        2.2.2         2.3.2 Compression
        2.2.3         2.3.3 Duration
        2.2.4         2.3.4 Format
        2.2.5         2.3.5 Samplingrate
        2.2.6         2.3.6 Framerate
        2.2.7         2.3.7 Bitrate
        2.2.8         2.3.8 NumTracks
    2.3     2.4 API for Iterating operation
3 Examples of how to use the API

Appendices

A References(Normative)
B References(Non-Normative)
C Acknowledgements (Non-Normative)

1 Introduction

This section is informative.

Editorial note  
This part will be elaborated in the perspectives of reason why we want to provide an API and an explanation on who should use/implement it.

This specification defines a client-side API to access metadata information related to media resources on the Web. The overall purpose of the API is to provide developers an with a convenient access to metadata information stored in different metadata formats. Thereby, the Media Ontology Core Properties will be used as a pivot vocabulary in the API. The description of relations between these core properties and the metadata formats in scope ( 1.1 Formats in scope ) are stored in the Media Ontology in order to provide cross-community data integration. The API will be introduced in an abstract manner using the interface definition language WebIDL . The decision to use Web IDL, which offers bindings for ECMAScript and Java, can be based on the Use Cases and Requirements for Ontology and API for Media Object 1.0 . This document clearly states that the focus for this API lies on multimedia services on the web. Web.

The API serves as a mediator between a developer and the underlying Ontology for Media Resource 1.0 with the goal to support interoperability between metadata formats. It offers GET and SET operations to retrieve and to store particular metadata informations represented in a certain metadata format related to media ressources on the Web.

The initial version of this document is not contains only a final version. limited description of API. In addtion, there are many open issues including definitions of return types. Nevertheless it is being published with the aspiration to gather wide feedback on the yet available API design.

1.1 Formats in scope

The following table lists the formats that were selected by the working group as in-scope, along with the identifiers which are used as prefixes Refers to identify them in this specification. Note: the This specification is based on a review of existing formats and the properties they provide. This review does not aim to be complete, and this specification does not aim to cover all properties defined in these formats. The choice of properties is motivated by the level of usage. scope of Ontology for Media Resource 1.0 .

Identifier Format Example property Reference cl11 CableLabs 1.1 cl11:Writer_Display Cablelabs 1.1 cl20 CableLabs 2.0 cl20:Producer Cablelabs 2.0 dig35 DIG35 dig35:ipr_name/ipr_person@description='Image Creator' DIG35 dc Dublin Core dc:creator Dublin Core ebucore EBUCore ebuc:creator EBUCore pmeta EBU P-Meta pmeta:Contribution EBU P-META exif EXIF 2.2 exif:Artist EXIF frbr FRBR frbr:Person FRBR id3 ID3 id3:TCOM ID3 iptc IPTC iptc:Creator IPTC it iTunes it:©ART

iTunes 1.2 Formats out of scope lom21 LOM 2.1 lom21:LifeCycle/Contribute/Entity

LOM Refers to the ma Core properties Formats out of MA WG ma:creator media Media RDF media:Recording Media RDF scope mrss Media RSS mrss:credit@role='author' of Ontology for Media RSS mets METS mets:agency METS mpeg7 MPEG-7 mpeg7:CreationInformation/Creation/Creator/Agent MPEG-7 nmix NISO MIX nmix:ImageCreation/ImageProducer Resource 1.0 .

MIX 1.3 Terminology qt Quicktime qt:©dir

QuickTime In this document the terms "Media Resource", "Property", "Mapping" and "Property value type" are to be interpreted as defined in media SearchMonkey Section 2 of Ontology for Media media:type MediaMonkey dms DMS-1 dms:Participant/Person Resource 1.0 .

DMS-1

2 API Description

Editorial note 
This part will be elaborated with a precise description of the actual methods in the API, (so these are the methods that can be found in the Strawman API design and note), described using Web IDL. This section needs to define and explain all aspects of those methods (parameters and return values).
Editorial note 
There are many open issues about SET interfaces, so these issues will be covered later.
module mawg {
	exception WrongMethod{
		const DOMString errorMessage = ”Property undefined for this media type.”
	};

	exception NoValue{
		const DOMString errorMessage = ”No value available for this property.”
	};

tva
TV-Anytime
tva:CredistsList/CredistItem

	interface MediaResource {

		// Identification
		readonly attribute DOMString identifier getraises (NoValue);
		readonly attribute DOMString title getraises (NoValue);
		readonly attribute DOMString language getraises (NoValue);
		readonly attribute DOMString locator getraises (NoValue);

TV-Anytime

		// Creation
		readonly attribute object[] contributors getraises (NoValue);
		readonly attribute DOMString[] creators getraises (NoValue);
		readonly attribute object createDate getraises (NoValue);
		readonly attribute object location getraises (NoValue);

		//Content Description
		readonly attribute DOMString description getraises (NoValue);
		readonly attribute DOMString[] keyword getraises (NoValue);
		readonly attribute DOMString genre getraises (NoValue);
		readonly attribute object rating getraises (NoValue);

		// Relational 
		readonly attribute object[] relation getraises (NoValue);
		readonly attribute DOMString collection getraises (NoValue);

txf
TXFeed
txf:author

		// Rights
		readonly attribute object[] copyright getraises (NoValue);
		readonly attribute object license getraises (NoValue);

		 // Distribution
		readonly attribute DOMString publisher getraises (NoValue);
		readonly attribute object targetAudience getraises (NoValue);

TXFeed

		// Fragments
		readonly attribute object[] fragments getraises (NoValue);
		readonly attribute object[] namedFragments getraises (NoValue);

		// Technical Properties
		readonly attribute object frameSize getraises (NoValue);
		readonly attribute DOMString compression getraises (NoValue);
		readonly attribute unsigned long duration getraises (NoValue);
		readonly attribute DOMString format getraises (NoValue);
		readonly attribute unsigned long samplingrate getraises (NoValue);
		readonly attribute float framerate getraises (NoValue);
		readonly attribute float bitrate getraises (NoValue);
		readonly attribute unsigned short numTracks getraises (NoValue);
	};

	
	module returnValues {
		interface Unstructured {
			attribute DOMString unstructuredValue;
		};

vra40
VRA
Core
4.0
vra40:agent

		interface Contributors: Unstructured {
			attribute DOMString id;
			attribute DOMString role;
		};

		interface Date: Unstructured {
			// to be defined … 
		};
		interface Location: Unstructured {
			// to be defined what the Location is … 
		};

VRA

		interface Rating: Unstructured {
	                attribute DOMString issuer;
			attribute short value;
			attribute short minimum;
			attribute short maximum;
			attribute DOMString context;
		};

		interface Relation: Unstructured {
			attribute DOMString id;
			attribute DOMString relationship;
		};
		
		interface Copyright: Unstructured {
			attribute DOMString statement;
			attribute DOMString[] holder;
		};

		interface License: Unstructured {
			attribute DOMString statement;
			attribute DOMString organization;
		};

xmp
XMP
xmpDM:composer

		interface TargetAudience: Unstructured {
			attribute DOMString issuer;
			attribute DOMString classification;
		};

		interface Fragment: Unstructured {
			  attribute DOMString role;
			  attribute DOMString identifier;
		};
		
		interface NamedFragment: Unstructured {
			  attribute DOMString name;	
			  attribute DOMString identifier;
		};
		
		interface FrameSize: Unstructured {
			  attribute unsigned long width;
			  attribute unsigned long height;
		};
	};
};

XMP


yt
YouTube
Data
API
Protocol
yt:author
YouTube
Data
API
Protocol

1.2 Formats out of scope 2.1 Design consideration

The following formats have been decided to be out of scope for this specification. MPEG-21 2 API Description Editorial note   This part will be elaborated with a precise description of the actual methods in the API, (so these are the methods that can be found in the Strawman API design and note), described using web IDL. This section needs to define and explain all aspects of those methods (parameters and return values). This part defines the interface for accessing the metadata. The API has been described using WebIDL . All properties are treated as attributes and have been grouped in the MediaResource interface within the mawg module. Currently, only read access is defined (all attributes are defined as readonly ). Exceptions have been defined using Web IDL's exception constructs. Certain properties have complex structures so the return type consists of one or more object types. For these objects, different interfaces have been defined which are part of the returnValues module. Note that, all of these interfaces inherit from the unStructured Unstructured interface. This interface has an attribute unstructeredValue using DOMString . If it is not clear how a certain value for a property should be structured, this attribute allows to describe the value in plain text. The following fragment shows the entire API described in Web IDL. The different properties have been grouped in categories and the semantics of each property and return type will be discussed in the next sections. module mawg { exception WrongMethod{ const DOMString errorMessage = ”Property undefined for this media type.” }; exception NoValue{ const DOMString errorMessage = ”No value available for this property.” }; interface MediaResource { // Identification readonly attribute DOMString identifier getraises (NoValue); readonly attribute DOMString title getraises (NoValue); readonly attribute DOMString language getraises (NoValue); readonly attribute DOMString locator getraises (NoValue); // Creation readonly attribute object[] contributor getraises (NoValue); readonly attribute DOMString[] creator getraises (NoValue); readonly attribute object createDate getraises (NoValue); readonly attribute object location getraises (NoValue); //Content Description readonly attribute DOMString description getraises (NoValue); readonly attribute DOMString[] keyword getraises (NoValue); readonly attribute DOMString genre getraises (NoValue); readonly attribute object rating getraises (NoValue); // Relational readonly attribute object[] relation getraises (NoValue); readonly attribute DOMString collection getraises (NoValue); // Rights readonly attribute object[] copyright getraises (NoValue); readonly attribute object license getraises (NoValue); // Distribution readonly attribute DOMString publisher getraises (NoValue); readonly attribute object targetAudience getraises (NoValue); // Fragments readonly attribute object[] fragments getraises (NoValue); readonly attribute object[] namedFragments getraises (NoValue); // Technical Properties readonly attribute object frameSize getraises (NoValue); readonly attribute DOMString compression getraises (NoValue); readonly attribute unsigned long duration getraises (NoValue); readonly attribute DOMString format getraises (NoValue); readonly attribute unsigned long samplingrate getraises (NoValue); readonly attribute float framerate getraises (NoValue); readonly attribute float bitrate getraises (NoValue); readonly attribute unsigned short numTracks getraises (NoValue); }; module returnValues { interface Unstructured { attribute DOMString unstructuredValue; }; interface Contributor: Unstructured { attribute DOMString id; attribute DOMString role; }; interface Date: Unstructured { // to be defined … }; interface Location: Unstructured { // to be defined what the Location is … }; interface Rating: Unstructured { attribute DOMString issuer; attribute short value; attribute short minimum; attribute short maximum; attribute DOMString context; }; interface Relation: Unstructured { attribute DOMString id; attribute DOMString relationship; }; interface Copyright: Unstructured { attribute DOMString statement; attribute DOMString[] holder; }; interface License: Unstructured { attribute DOMString statement; attribute DOMString organization; }; interface TargetAudience: Unstructured { attribute DOMString issuer; attribute DOMString classification; }; interface Fragment: Unstructured { attribute DOMString role; attribute DOMString identifier; }; interface NamedFragment: Unstructured { attribute DOMString name; attribute DOMString identifier; }; interface FrameSize: Unstructured { attribute unsigned long width; attribute unsigned long height; }; }; };

2.1 2.2 API for Descriptive Properties

This part defines part of the interface for accessing the descriptive metadata that describes a work for purposes of discovery and identification, such as creator, creators, title, language and extra. The properties have been grouped in different categories.

2.1.1 2.2.1 Identification Properties

2.1.1.1 2.2.1.1 Identifier
Web IDL syntax: 

readonly
attribute
DOMString
identifier
getraises
(NoValue);
Description:

The identifier property identifies a resource; which can be either a "Resource" (abstract concept) or a "Representation" (instance/file). resource.

Return type:

A DOMString which should represent a URI identifying the resource.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG"

2.1.1.2 2.2.1.2 Title
Web IDL syntax: 

readonly
attribute
DOMString
title
getraises
(NoValue);
Description:

The title property defines the title of the document, or the name given to the resource.

Return type:

A DOMString that holds the title as a plain string.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"MAWG-Stockholm-20090626" "MAWG Stockholm 20090626"

2.1.1.3 2.2.1.3 Language
Web IDL syntax: 

readonly
attribute
DOMString
language
getraises
(NoValue);
Description:

The language property specifies a language used in the entity, Recommended best practice is to use a controlled vocabulary such as RFC 4646 [RFC4646]. BCP 47 [ BCP 47 ].

Return type:

A DOMString that represents the language as a plain string.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

N/A

2.1.1.4 2.2.1.4 Locator
Web IDL syntax: 

readonly
attribute
DOMString
locator
getraises
(NoValue);
Description:

The locator property holds a URI at which the entity can be accessed (e.g. a URL, or a DVB URI).

Return type:

A DOMString that holds the URI.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG"

2.1.2 2.2.2 Creation Properties

2.1.2.1 Contributor 2.2.2.1 Contributors
Web IDL syntax: 

readonly
attribute
object[]
contributor

contributors

getraises
(NoValue);
Description:

The contributor contributors property holds a pair identifying the contributor contributors and the nature of the contribution. E.g.actor, cameraman, dirctor,singer, author, artist (Note: subject see addition of contributor contributors type) identifies a resource; which can be either a "Resource" (abstract concept) or a "Representation" (instance/file). resource.

Return type:

An array of object elements implementing the Contributor Contributors interface. This object has an attribute id which identifies the contributor. contributors. Additionally, the role attribute defines the role. For the latter a number of suggested terms are defined. 

interface
Contributor:

Contributors:

Unstructured
{
attribute
DOMString
id;
attribute
DOMString
role;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

[http://www.individuals.com/Author1, "author"], [http://www.individuals.com/Author2, "author"]

2.1.2.2 Creator 2.2.2.2 Creators
Web IDL syntax: 

readonly
attribute
DOMString[]
creator

creators

getraises
(NoValue);
Description:

The creator creators property holds the authors of the resource (listed in order of precedence, if significant).

Return type:

An Array array of DOMString element, each identifying an author of the resource.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

["http://www.individuals.com/Author1", "http://www.individuals.com/Author2"]

2.1.2.3 2.2.2.3 CreateDate
Web IDL syntax: 

readonly
attribute
object
createDate
getraises
(NoValue);
Description:

The createDate property holds the date and time the entity was originally created. (for commercial purpose there might be an annotation of publication date).

Return type:

An object implementing the Date interface. This object is currently undefined. 


interface
Date:
Unstructured
{
//
to
be
defined
…
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

2009-06-26T15:30:00

2.1.2.4 2.2.2.4 Location
Web IDL syntax: 

readonly
attribute
object
location
getraises
(NoValue);
Description:

The location property holds the location where the resource has been shot/recorded.

Return type:

A object implementing the Location interface. This object is currently undefined. 


interface
Location:
Unstructured
{
//
to
be
defined
…
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"Sweden", " Stockholm, Kistavägen 25, KISTA, KMUM Building", "Ericsson", ...

2.1.3 2.2.3 Content description Properties

2.1.3.1 2.2.3.1 Description
Web IDL syntax: 

readonly
attribute
DOMString
description
getraises
(NoValue);
Description:

The description property holds a textual description of the content of the resource.

Return type:

An DOMString holds the description of the content of the resource.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"Group picture of the W3C Media Annotations WG at the face-to-face meeting in Stockholm."

2.1.3.2 2.2.3.2 Keyword
Web IDL syntax: 

readonly
attribute
DOMString[]
keyword
getraises
(NoValue);
Description:

The keyword property represents an unordered array of descriptive phrases or keywords that specify the topic of the content of the resource.

Return type:

An Array of DOMString element, each corresponding to one descriptive phrase or keyword.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

["W3C Media Annotations WG", "meeting", "group picture"]

2.1.3.3 2.2.3.3 Genre
Web IDL syntax: 

readonly
attribute
DOMString
genre
getraises
(NoValue);
Description:

The genre property describes the genre of the entity.

Return type:

An DOMString representing the genre of the entitiy.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"Work"

2.1.3.4 2.2.3.4 Rating
Editorial note  
It should be clarified about what the 'context' of a rating is
Web IDL syntax: 

readonly
attribute
object
rating
getraises
(NoValue);
Description:

The rating property holds information to identify the rating person or organization and the rating (real value). Additionally, a minimum and maximum value can be given. Lastly, information on the context of the rating is also included.

Return type:

A object implementing the Rating interface. This object holds an attribute issuer to identify the rating person or organization. Next, the rating value can be represented, together with the minimum and maximum rating values. These allow to interpret the rating value. Lastly, a textual description of the context can be given. 


interface
Rating:
Unstructured
{
attribute
DOMString
issuer;
attribute
short
value;
attribute
short
minimum;
attribute
short
maximum;
attribute
DOMString
context;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

[http://www.individuals.com/ChrisPoppe, 10.0, 0, 10.0, "quality"]

2.1.4 2.2.4 Relational Properties

2.1.4.1 2.2.4.1 Relation
Web IDL syntax: 

readonly
attribute
object[]
relation
getraises
(NoValue);
Description:

The relation property holds pairs identifying the entities and the nature of the realtionships. E.g. transcript, original_work.

Return type:

An array of object elements implementing the Relation interface. This object holds an attribute id to identify the entitiy. A textual description of the relationship is represented using the relationship attribute. For the latter a number of suggested terms are defined. 

interface
Relation:
Unstructured
{
attribute
DOMString
id;
attribute
DOMString
relationship;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

[http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626_thumb.JPG, "re-edit"]

2.1.4.2 2.2.4.2 Collection
Web IDL syntax: 

readonly
attribute
DOMString
collection
getraises
(NoValue);
Description:

The collection property holds a name of the collection from wich the entities originates.

Return type:

A DOMString representing the name of the collection from wich the entities originates.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"My Work Pictures"

2.1.5 2.2.5 Rights Properties

2.1.5.1 2.2.5.1 Copyright
Web IDL syntax: 

readonly
attribute
object[]
copyright
getraises
(NoValue);
Description:

The copyright property holds the copyright statement and an identification of the copyrights holder (DRM is out of scope for MAWG).

Return type:

An array of object elements implementing the Copyright interface. This object holds an attribute statement that holds the copyright statement. An array of DOMString elements is used to denote the copyright holders and stored in attribute holder . 


interface
Copyright:
Unstructured
{
attribute
DOMString
statement;
attribute
DOMString[]
holder;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

["All images in the collection are copyrighted by John Doe", http://www.individuals.com/JohnDoe]

2.1.5.2 2.2.5.2 License
Editorial note  
license/statement attribute: is this really free text?
Web IDL syntax: 

readonly
attribute
object
license
getraises
(NoValue);
Description:

The license property holds a description of the license of the media resource or reference.

Return type:

A object implementing the License interface. This object holds an attribute statement that holds the description of the license. Attribute organization identifies the organization that issued the license. 


interface
License:
Unstructured
{
attribute
DOMString
statement;
attribute
DOMString
organization;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

["Attribution 2.5 ", http://www.organizations.com/CreativeCommons] http://creativecommons.org/licenses/by/2.5]

2.1.6 2.2.6 Distribution Properties

2.1.6.1 2.2.6.1 Publisher
Web IDL syntax: 

readonly
attribute
DOMString
publisher
getraises
(NoValue);
Description:

The publisher property holds identification of the publisher of the entitiy. Examples of a Publisher include a person, an organization, or a service. Typically, the name of a Publisher should be used to indicate the entity.

Return type:

A DOMString representing the name of the publisher.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"http://www.individuals.com/JohnDoe"

2.1.6.2 2.2.6.2 TargetAudience
Web IDL syntax: 

readonly
attribute
object
targetAudience
getraises
(NoValue);
Description:

The targetAudience property holds a pair identifying the issuer of the classification (agency) and the classification. E.g. parental guide, targeted geographical region.

Return type:

An object implementing the TargetAudience interface. This object has an attribute issuer which identifies the issuer of the classification. Additionally, the classification attribute defines the actual classification. 


interface
TargetAudience:
Unstructured
{
attribute
DOMString
issuer;
attribute
DOMString
classification;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

[http://www.fosi.org/icra,"no nudity"]

2.1.7 2.2.7 Fragments Properties

2.1.7.1 2.2.7.1 Fragments
Web IDL syntax: 

readonly
attribute
object[]
fragments
getraises
(NoValue);
Description:

The fragments property holds a list of pairs of fragment role and fragment identifier (e.g. chapters, favourite scenes).

Return type:

An array of object elements implementing the Fragment interface. This object holds an attribute role that holds the role of the fragment. The attribute identifier is used to identify the fragment. 


interface
Fragment:
Unstructured
{
attribute
DOMString
role;
attribute
DOMString
identifier;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

[["Person", http://www.example.com/movie.mov#xywh=320,320,40,100],

["Person", http://www.example.com/movie.mov#xywh=300,350,40, 40]]

2.1.7.2 2.2.7.2 NamedFragments
Web IDL syntax: 

readonly
attribute
object[]
namedFragments
getraises
(NoValue);
Description:

The namedFragments property holds the list of named fragments annotated for this resource (pairs of label and fragment identifier).

Return type:

An array of object elements implementing the NamedFragment interface. This object holds an attribute name with the name given to the fragment. The attribute identifier is used to identify the fragment. 


interface
NamedFragment:
Unstructured
{
attribute
DOMString
name;
attribute
DOMString
identifier;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

[["Joakim Söderberg", http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG#xywh=1600,550,80,150],

["Chris Poppe", http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG#xywh=1400,600,80, 80]]

2.2 2.3 API for Technical Properties

This part defines the interfaces for accessing the technical metadata that describe information for dealing with the creation or storage encoding processes or formats of the resource.

2.2.1 2.3.1 FrameSize

Web IDL syntax: 

readonly
attribute
object
frameSize
getraises
(NoValue);
Description:

The frameSize property determines the frame size.

Return type:

An object implementing the FrameSize interface. This object has an attribute width and height to represent the width and height of the frame, respectively. 


interface
FrameSize:
Unstructured
{
attribute
unsigned
long
width;
attribute
unsigned
long
height;
};
Exceptions:

The NoValue exception is thrown if no value is available.

Example:

[3.072, 2.304]

2.2.2 2.3.2 Compression

Web IDL syntax: 

readonly
attribute
DOMString
compression
getraises
(NoValue);
Description:

The compression property holds the compression type used. Note: it might be possible to use extended mime type, see RFC 4281.

Return type:

A DOMString representing the compression type. interface FrameSize: Unstructured { attribute unsigned long width; attribute unsigned long height; };

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"H.264/AVC"

2.2.3 2.3.3 Duration

Editorial note  
Further consideration is required for the unit of Duration. (e.g. Is it fixed to 'second'?)
Web IDL syntax: 

readonly
attribute
unsigned
long
duration
getraises
(NoValue);
Description:

The duration property represents the duration of the entitiy.

Return type:

An unsigned long representing the duration (in secs).

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

3600

2.2.4 2.3.4 Format

Web IDL syntax: 

readonly
attribute
DOMString
format
getraises
(NoValue);
Description:

The format property holds the MIME type of the entity (wrapper, bucket media types).

Return type:

A DOMString representing the MIME type.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

"image/jpeg"

2.2.5 2.3.5 Samplingrate

Web IDL syntax: 

readonly
attribute
unsigned
long
samplingrate
getraises
(NoValue);
Description:

The samplingrate property holds the samplingrate of an audio file. Only applicable for audio.

Return type:

An unsigned long representing the samplingrate (in Hz).

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

100

2.2.6 2.3.6 Framerate

Web IDL syntax: 

readonly
attribute
float
framerate
getraises
(NoValue);
Description:

The framerate property holds the frame rate of the video. Only applicable for video.

Return type:

An float representing the framerate (in fps).

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

30

2.2.7 2.3.7 Bitrate

Editorial note  
Should bitrate be a number? What about Variable Bit Rate? Or would we raise NoValue in that case?
Web IDL syntax: 

readonly
attribute
float
bitrate
getraises
(NoValue);
Description:

The bitrate property holds the average bitrate. Only applicable for audio and video.

Return type:

An float representing the bitrate (in kbps).

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

100

2.2.8 2.3.8 NumTracks

Web IDL syntax: 

readonly
attribute
unsigned
short
numTracks
getraises
(NoValue);
Description:

The numTracks property holds the number of tracks.

Return type:

An unsigned short representing the number of tracks.

Exceptions:

The NoValue exception is thrown if no value is available.

Example:

2

2.3 2.4 API for Iterating operation

Editorial note  
This part will be covered later in the perspectives of what kind API for iterating operation is helpful to application developers .

3 Examples of how to use the API

Editorial note  
This part will illustrate how to use the API in the actual (working) implementations

A References(Normative)

[Ontology for Media Resource 1.0]
WonSuk Lee, Tobias Bürger, Felix Sasaki, Véronique Malaisé, Florian Stegmaier and Joakim Söderberg. Ontology for Media Resource 1.0 . W3C Working Draft, 18 June 2009. Available at http://www.w3.org/TR/mediaont-10/ .

B References(Non-Normative)

[Cablelabs 1.1] CableLabs VOD Content Specification Version 1.1 . Available at http://www.cablelabs.com/specifications/MD-SP-VOD-CONTENT1.1-I05-060831.pdf . [Cablelabs 2.0] CableLabs VOD Content Specification Version 2.0 . Available at http://www.cablelabs.com/specifications/MD-SP-VOD-CONTENT2.0-I02-070105.pdf . [DIG35] DIG35 Specification - Metadata for Digital Image . April 2001. Available at http://www.bgbm.org/TDWG/acc/Documents/DIG35-v1.1WD-010416.pdf . [DMS-1] DMS-1 (SMPTE 380M-2004). April 2001. Available at http://www.smpte.org/standards . [Dublin Core] DCMI Metadata Terms . January 2008. Available at http://dublincore.org/documents/2008/01/14/dcmi-terms/ . The latest version of DCMI Metadata Terms is available at http://dublincore.org/documents/dcmi-terms/ . [EBUCore] EBUCore v.1.0 . December 2008. Available at http://tech.ebu.ch/docs/tech/tech3293-2008.pdf . [EBU P-META] EBU P-META 2.0 Metadata Library . July 2007. Available at http://tech.ebu.ch/docs/tech/tech3295v2.pdf . [EXIF] EXIF 2.2 . Specification by JEITA , April 2002. Available at http://www.exif.org/Exif2-2.PDF . [FRBR] FRBR TBD . [HTML 5] Hickson, I., and D. Hyatt. HTML 5. A vocabulary and associated APIs for HTML and XHTML . W3C Working Draft, June 2008. Available at http://www.w3.org/TR/2008/WD-html5-20080610/ . The latest version of HTML 5 is available at http://www.w3.org/TR/html5/ . [LOM] Draft Standard for Learning Object Metadata . July 2002. Available at http://ltsc.ieee.org/wg12/files/LOM_1484_12_1_v1_Final_Draft.pdf . [MIX] MIX 1.0 . Available at http://www.loc.gov/standards/mix/ . [MWG Guidelines Image] Guidelines for handling image metadata, version 1.0. . Metadata Working Group, September 2008. Available at http://www.metadataworkinggroup.com/pdf/mwg_guidance.pdf . [ID3] ID3 tag version 2.4.0 . February 1999. Available at http://www.id3.org/Developer_Information . [IPTC] IPTC Standard Photo Metadata 2008 . IPTC Core Specification Version 1.1, IPTC Extension Specification Version 1.0, Document Revision 2, June 2008. Available at http://www.iptc.org/std/photometadata/2008/specification/IPTC-PhotoMetadata-2008.pdf [IPTC NewsML] IPTC NewsML-G2 . Available at http://www.iptc.org/cms/site/ . [iTunes] iTunes Metadata Specification . Available at http://connect.apple.com/ . [MediaMonkey] MediaMonkey Media . Available at http://developer.yahoo.com/searchmonkey/smguide/searchmonkey-media-details.html . [METS] Metadata Encoding & Transmission Standard 1.7 . Available at http://www.loc.gov/standards/mets/ . [Media RDF] Media RDF . Available at http://digitalbazaar.com/media/video . [Media RSS] Yahoo! Media RSS Module - RSS 2.0 Module . March 2008. Available at http://video.search.yahoo.com/mrss . [MPEG-7] Information technology — Multimedia content description interface — Part 10: Schema definition . Available at http://www.chiariglione.org/mpeg/working_documents/mpeg-07/schema_def/cd.zip . [MPEG-21] MPGE 21 tbd. [QuickTime] Movie Atoms of QuickTime File Format Specification . September 2007. Available at http://developer.apple.com/documentation/QuickTime/QTFF/QTFFChap2/qtff2.html#//apple_ref/doc/uid/TP40000939-CH204-BBCCFFGD . [RFC 2119] RFC 2119: Key words for use in RFCs to Indicate Requirement Levels . Internet Engineering Task Force, 1997. [RFC 3986] Berners-Lee, T., R. Fielding, L. Masinter. Uniform Resource Identifier (URI): Generic Syntax . RFC 3986, January 2005. Available at http://www.ietf.org/rfc/rfc3986.txt [RFC 3987] Dürst, M. and M. Suignard. Internationalized Resource Identifiers (IRIs) . RFC 3987, January 2005. Available at http://www.ietf.org/rfc/rfc3987.txt. [RFC 4281] Gellens, R., Singer, D., and P. Frojdh. The Codecs Parameter for "Bucket" Media Types . RFC 4281, November 2005. Available at http://www.ietf.org/rfc/rfc4281.txt. [RFC 4646] [BCP 47]
Phillips, A., Ed. and M. Davis, Ed. Matching of Language Tags for Identifying Languages . RFC 4646, BCP 47, September 2006. Available at http://www.rfc-editor.org/rfc/rfc4646.txt. [SMPTE] SMPTE Metadata . Available at http://www.smpte-ra.org/mdd/RP210v11-pub-20080415.2048.xls . [TXFeed] TXFeed standard 0.9 . December 2007. Available at http://clearerchannel.org/docs/tx_metadata_standard_0_9.pdf . [TV-Anytime] ETSI 102 822-3-1 V1.4.1 . November 2007. Broadcast and On-line Services: Search, select, and rightful use of content on personal storage systems("TV-Anytime"). Part 3: Metadata, Sub-part 1: Phase 1 - Metadata schemas . [VRA] VRA Core 4.0 . Available at http://www.vraweb.org/projects/vracore4/index.html . [XML Schema 2] Biron, P. V. and A. Malhotra. XML Schema Part 2: Datatypes Second Edition . W3C Recommendation, October 2004. Available at http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/ . The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2/ . [XMP] XMP Specification Part 2 - Standard Schemas . Adobe, 2008. Available at http://www.adobe.com/devnet/xmp/pdfs/XMPSpecificationPart2.pdf . [YouTube Data API Protocol] YouTube Data API Protocol . April 2008. Available at http://code.google.com/intl/en/apis/youtube/2.0/reference.html . http://www.rfc-editor.org/rfc/bcp/bcp47.txt.
[WebIDL]
Cameron McCormack. Web IDL . W3C Working Draft, 19 December 2008. Available at http://www.w3.org/TR/WebIDL/ .

C Acknowledgements (Non-Normative)

This document is the work of the W3C Media Annotations Working Group .

Members of the Working Group are (at the time of writing, and by alphabetical order): Werner Bailer (K-Space), Tobias Bürger (University of Innsbruck), Eric Carlson (Apple, Inc.), Pierre-Antoine Champin ((public) Invited expert), Jaime Delgado (Universitat Politècnica de Catalunya), Jean-Pierre EVAIN ((public) Invited expert), Ralf Klamma ((public) Invited expert), WonSuk Lee (Electronics and Telecommunications Research Institute (ETRI)), Véronique Malaisé (Vrije Universiteit), Erik Mannens (IBBT), Hui Miao (Samsung Electronics Co., Ltd.), Thierry Michel (W3C/ERCIM), Frank Nack (University of Amsterdam), Soohong Daniel Park (Samsung Electronics Co., Ltd.), Silvia Pfeiffer (W3C Invited Experts), Chris Poppe (IBBT), Víctor Rodríguez (Universitat Politècnica de Catalunya), Felix Sasaki (Potsdam University of Applied Sciences), David Singer (Apple, Inc.), Joakim Söderberg (ERICSSON), Thai Wey Then (Apple, Inc.), Ruben Tous (Universitat Politècnica de Catalunya), Raphaël Troncy (CWI), Vassilis Tzouvaras (K-Space), Davy Van Deursen (IBBT).

The people who have contributed to discussions on public-media-annotation@w3.org are also gratefully acknowledged.