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 with a convenient access to metadata information stored in
different metadata formats. The API is described 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 a Last Call 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.
The W3C Membership and other interested parties are invited to review the
document and send comments through 11 July 2010. Comments must be sent to to public-media-annotation@w3.org
mailing list (public
archive). Use "[LC Comment API]" in the subject line of your email.
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.
2. Design
consideration
We consider two scenarios where the API could be implemented: either in a
user agent (scenario 1) or as a web service (scenario 2). The two scenarios are
shown in the figure.
- Scenario 1: User agent
- The API is implemented in a user agent (e.g., browser or browser
plugin) and exposed as a JavaScript API (using the WebIDL JavaScript
binding). The user agent includes the components for metadata access
(possibly extraction) and mappings for a supported set of formats. The
metadata sources (the media resource and/or metadata document(s)) must be
retrievable and access (establish connection, retrieval) of the metadata
sources is handled by the user agent.
- Scenario 2: Web service
- The API is implemented as a Web service. Such an implementation would
be typically used by a non-UI client, such as an agent harvesting
metadata. However, the API could be also accessed from a user agent, and
used the same way as described in scenario 1 by the help of a JavaScript
library for accessing the web service. At the back-end of the web
service, this scenario also allows supporting a media repository (e.g.
content provider's archive database, movie store) from which the user
agent could directly retrieve metadata sources and which might have a
custom metadata format not supported by a user agent. In contrast to an
integrated component (see scenario 1), an implementation of the API in a
web service could do more complex mappings on the fly as a component
integrated in a user agent, and can be more flexible (e.g., supporting
additional formats).
In both scenarios, the access to the metadata properties needs the following
stack of components:
An implementation of the API for Media Resource (as defined in this
document), which providers the actual getter methods for the properties.
An implementation of the mappings from a specific source format to the
properties of the media ontology (as defined in Ontology for Media Resource
1.0).
A format specific API to access the metadata. This can be an API for
accessing a metadata document describing a media resource (e.g. an XML
parser and a set of XPath statements) or an extractor to read metadata
embedded in the media resource (e.g. a library to read EXIF information
from JPEG images). In order to define the context on which the API for
Media Resource is working, it is assumed that there is at least a
unidirectional reference from the media resource to the metadata document
or vice versa. If this is not the case such a reference needs to be
provided by the web application (scenario 1), web service (scenario 2) or
media repository (scenario 2).
3. API Description
The JavaScript examples in this document will only work if the
API is implemented by the browser.
The API exists of a number of interfaces, described using Web IDL. Implementations of the API should
provide objects implementing the different interfaces. The entire description
can be found in Appendix A. The API is contained
within the MediaResource interface within the mawg
module. Objects implementing this interface provide the necessary methods to
access metadata properties of a Media Resource. The object holds methods to
identify the actual Media Resource and the metadata sources. All properties can
be accessed through a specific operation getProperty. When an
attempt to read a property fails, diagnostics information can be obtained using
a diagnosis operation. Subtypes in the API are relevant for those properties
mentioned in 4.1.3 Core
properties of Ontology for
Media Resource 1.0. Lastly, methods are available that allow to iterate
through the available metadata. Next, the different interfaces and exposed
methods are discussed. Finally, examples of the usage of the API can be found
in section 4.
3.3 Language
interface
Language interface is used to identify the language of the
metadata.
[NoInterfaceObject]
interface Language {
attribute DOMString language;
};
3.3.1 Attributes
language of type DOMString- This attribute holds the language of the metadata.
No exceptions.
3.4
MAObject interface
MAObject interface is used as the return type of
MediaResource.getProperty method. This is used to hold the values
of the requested property. Depending on the requested property, these objects
implement a different interface.
[NoInterfaceObject]
interface MAObject {
attribute DOMString unstructuredValue;
attribute DOMString uri;
attribute DOMString sourceFormat;
attribute DOMString fragmentIdentifier;
attribute DOMString mappingType;
};
3.4.1 Attributes
fragmentIdentifier of
type DOMString- This attribute determines the fragment for which the metadata is
relevant.
No exceptions.
mappingType of type DOMString- This attribute specifies the kind of mapping as discussed in the
semantic level mappings.
No exceptions.
sourceFormat of type DOMString- This attribute allows to specify the metadata source from which the
metadata was retrieved.
No exceptions.
unstructuredValue of
type 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.
No exceptions.
uri of type DOMString- This attribute is provided which should hold an URI. This can for
example be used to represent labels as URIs.
No exceptions.
3.5
Identification Properties
3.5.1
Identifier interface
Identifier interface is used as the specific return type of
MediaResource.getProperty method which has "Identifier" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Identifier : MAObject {
attribute DOMString value;
attribute DOMString type;
};
3.5.1.1 Attributes
type of type DOMString- This attribute holds the type of the identifier, which can be filtered
on in the
getProperty operation. Possible values are " UMID"
and "ISAN".
No exceptions.
value of type DOMString- This attribute should represent a URI identifying the resource.
No exceptions.
Example in JavaScript is as below:
image = document.getElementsByTagName("img")[0];
id = image.getProperty("identifier");
http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=identifier
Response (JSON format): { "identifier" : [ {"value" :
"http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG",
"type" : "URI" } , { "value" : "ISAN 0000-3BAB-9352-0000-G-0000-0000-Q",
"type" : "ISAN" }, { "value" :
"urn:uuid:36a87260-1102-11df-8a39-0800200c9a66", "type" : "UUID" } ] }
3.5.2 Title
interface
Title interface is used as the specific return type of
MediaResource.getProperty method which has "Title" as a value of
propertyName parameter.
[NoInterfaceObject]
interface Title : MAObject, Language {
attribute DOMString value;
attribute DOMString type;
};
3.5.2.1 Attributes
type of type DOMString- This attribute contains the type of the title, which can be filtered on
in the
getProperty operation.
No exceptions.
value of type DOMString- This attribute should hold the title as a plain string.
No exceptions.
Example in JavaScript is as below:
song = document.getElementsByTagName("audio")[0];
title = song.getProperty("title");
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=title
Response (JSON format): { "title" : { "value" : "Artificial Horizon" ,
"type" : "Album title" } }
3.5.3
Language interface
Language interface is used as the specific return type of
MediaResource.getProperty method which has "Language" as a value
of propertyName parameter. Recommended best practice is to use BCP
47 [BCP-47].
[NoInterfaceObject]
interface Language : MAObject {
attribute DOMString value;
};
3.5.3.1 Attributes
value of type DOMString- This attribute should represent the language as a plain string.
No exceptions.
Example in JavaScript is as below:
video = document.getElementsByTagName("video")[0];
language = video.getProperty("language");
Usage as a service:
3.5.4
Locator interface
Locator interface is used as the specific return type of
MediaResource.getProperty method which has "Locator" as a value of
propertyName parameter.
[NoInterfaceObject]
interface Locator : MAObject {
attribute DOMString value;
};
3.5.4.1 Attributes
value of type DOMString- This attribute should hold the URI.
No exceptions.
Example in JavaScript is as below:
image = document.getElementsByTagName("img")[0];
locator = image.getProperty("locator");
http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=locator
Response (JSON format): { "locator" : { "value" :
"http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG"
} }
3.6 Creation
Properties
3.6.1
Contributor interface
Contributor interface is used as the specific return type of
MediaResource.getProperty method which has "Contributor" as a
value of propertyName parameter.
[NoInterfaceObject]
interface Contributor : MAObject {
attribute DOMString id;
attribute DOMString role;
};
3.6.1.1 Attributes
id of type DOMString- This attribute identifies the contributor.
No exceptions.
role of type DOMString- This attribute defines the role, which can be filtered on in the
getProperty operation. For the latter a number of suggested
terms are defined:
editor (EBU 11.1)
actor (EBU 25.9)
composer
featured_in
cinematographer
director
musicproducer
producer
screenplayer
writer
distributor (company)
production company
No exceptions.
Example in JavaScript is as below:
video = document.getElementsByTagName("video")[0];
contributor = video.getProperty("contributor");
http://individuals.example.com/Contributor1
Usage as a service:
Request:
http://example.com/my-media-resource/?ma-query=contributors
Response (JSON format): { "contributors" : { "id" :
"http://individuals.example.com/Contributor1", "role" : "editor" } }
3.6.2
Creator interface
Creator interface is used as the specific return type of
MediaResource.getProperty method which has "Creator" as a value of
propertyName parameter.
[NoInterfaceObject]
interface Creator : MAObject {
attribute DOMString value;
};
3.6.2.1 Attributes
value of type DOMString- This attribute should hold an identifier for an author.
No exceptions.
Example in JavaScript is as below:
video = document.getElementsByTagName("video")[0];
creator = video.getProperty("creator");
http://individuals.example.com/Author1
Usage as a service:
3.6.3
CreateDate interface
CreateDate interface is used as the specific return type of
MediaResource.getProperty method which has "CreateDate" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Date : MAObject {
attribute DOMString date;
attribute DOMString type;
};
3.6.3.1 Attributes
date of type DOMString- The exact format of this attribute is currently undefined.
No exceptions.
type of type DOMString- This attribute define the particular category of creation date (e.g.
"release date", "date recorded" and "date edited".), which can be
filtered on in the
getProperty operation.
No exceptions.
Example in JavaScript is as below:
video = document.getElementsByTagName("video")[0];
createdate = video.getProperty("createdate");
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=createDate
Response (JSON format): { "createDate" : { "date":
"2009-06-26T15:30:00", "type" : "date recorded" } }
3.6.4
Location interface
Location interface is used as the specific return type of
MediaResource.getProperty method which has "Location" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Location : MAObject, Language {
attribute DOMString name;
attribute Float longitude;
attribute Float latitude;
attribute Float altitude;
attribute DOMString system;
};
3.6.4.1 Attributes
altitude of type Float- This attribute holds the altitude value from system defined in
system.
No exceptions.
latitude of type Float- This attribute holds the latitude value from system defined in
system.
No exceptions.
longitude of type Float- This attribute holds the longitude value from system defined in
system.
No exceptions.
name of type DOMString- This attribute holds a free text name of the location.
No exceptions.
system of type DOMString- This attribute holds the name of location system.
No exceptions.
Example in JavaScript is as below:
video = document.getElementsByTagName("video")[0];
location = video.getProperty("location");
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=location
Response (JSON format): { "location" : { "name" : "San Jose",
"longitude" : 37.33986481118008, "latitude" : -121.88507080078125,
"altitude" : 0, system : "GPS" } }
3.7 Content
Properties
3.7.1
Description interface
Description interface is used as the specific return type of
MediaResource.getProperty method which has "Description" as a
value of propertyName parameter.
[NoInterfaceObject]
interface Description : MAObject, Language {
attribute DOMString value;
};
3.7.1.1 Attributes
value of type DOMString- This attribute should hold a description of the content of the media
resource.
No exceptions.
image = document.getElementsByTagName("img")[0];
description = image.getProperty("description");
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=description
Response (JSON format): { "description" : { "value" : "Group picture
of the W3C Media
Annotations WG at the face-to-face meeting in Stockholm." } }
3.7.2
Keyword interface
Keyword interface is used as the specific return type of
MediaResource.getProperty method which has "Keyword" as a value of
propertyName parameter.
[NoInterfaceObject]
interface Keyword : MAObject, Language {
attribute DOMString value;
};
3.7.2.1 Attributes
value of type DOMString- This attribute should hold one keyword.
No exceptions.
image = document.getElementsByTagName("img")[0];
keyword = image.getProperty("keyword");
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=keyword
Response (JSON format): { "keyword" : [ { "value" : "W3C Media Annotations WG" }, {
"value" : "meeting" }, { "value" : "group picture" } ] }
3.7.3
Genre interface
Genre interface is used as the specific return type of
MediaResource.getProperty method which has "Genre" as a value of
propertyName parameter.
[NoInterfaceObject]
interface Genre : MAObject, Language {
attribute DOMString value;
};
3.7.3.1 Attributes
value of type DOMString- This attribute should represent the genre of the media resource.
No exceptions.
image = document.getElementsByTagName("img")[0];
genre = image.getProperty("genre");
Usage as a service:
3.7.4
Rating interface
Rating interface is used as the specific return type of
MediaResource.getProperty method which has "Rating" as a value of
propertyName parameter.
[NoInterfaceObject]
interface Rating : MAObject, Language {
attribute DOMString issuer;
attribute short value;
attribute short minimum;
attribute short maximum;
attribute DOMString type;
};
3.7.4.1 Attributes
issuer of type DOMString- This attribute identifies the rating person or organization
No exceptions.
maximum of type short- This attribute specifies the maximum rating.
No exceptions.
minimum of type short- This attribute specifies the minimum rating.
No exceptions.
type of type DOMString- This attribute specifies the type of the rating, which can be filtered
on in the
getProperty operation. Examples are "Review
Rating", "MPAA", "Personal Rating".
No exceptions.
value of type short- This attribute indicates the average rating.
No exceptions.
image = document.getElementsByTagName("img")[0];
rating = image.getProperty("rating");
http://individuals.example.com/ChrisPoppe
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=rating
Response (JSON format): "rating" : { "rating" : { "issuer" :
"http://individuals.example.com/ChrisPoppe", "value" : 10.0, "minimum" : 0,
"maximum" : 10.0, "type" : "Personal Rating" } }
3.8 Relational
Properties
3.8.1
Relation interface
Relation interface is used as the specific return type of
MediaResource.getProperty method which has "Relation" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Relation : MAObject {
attribute DOMString id;
attribute DOMString relationship;
};
3.8.1.1 Attributes
id of type DOMString- This attribute identifies the entitiy.
No exceptions.
relationship of type DOMString- This attribute specifies textual description of the relationship, which
can be filtered on in the
getProperty operation. For the
latter a number of suggested terms are defined:
No exceptions.
image = document.getElementsByTagName("img")[0];
relation = image.getProperty("relation");
http://www.w3.org/2008/WebVideo/Annotations/wiki/Image
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=relation
Response (JSON format): { "relation" : { "id" :
"http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626_thumb.JPG"
, "relationship" : "re-edit" } }
3.8.2
Collection interface
Collection interface is used as the specific return type of
MediaResource.getProperty method which has "Collection" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Collection : MAObject, Language {
attribute DOMString value;
};
3.8.2.1 Attributes
value of type DOMString- This attribute should hold the name of the collection from which the
media resource originates.
No exceptions.
image = document.getElementsByTagName("img")[0];
collection = image.getProperty("collection");
Usage as a service:
3.9 Rights
Properties
3.9.1
Copyright interface
Copyright interface is used as the specific return type of
MediaResource.getProperty method which has "Copyright" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Copyright : MAObject, Language {
attribute DOMString statement;
attribute DOMString[] holder;
};
3.9.1.1 Attributes
holder of type array of DOMString- This attribute denotes the copyright holders.
No exceptions.
statement of type DOMString- This attribute should holds the copyright statement.
No exceptions.
image = document.getElementsByTagName("img")[0];
copyright = image.getProperty("copyright");
http://individuals.example.com/JohnDoe
Usage as a service:
Request:
http://example.com/my-media-resource/?ma-query=rights-properties
Response (JSON format): { "rights-properties" : { "statement" : "All
images in the collection are copyrighted by John Doe", "holder" :
"http://individuals.example.com/JohnDoe" } }
3.9.2
Policy interface
Policy interface is used as the specific return type of
MediaResource.getProperty method which has "Policy" as a value of
propertyName parameter.
[NoInterfaceObject]
interface Policy : MAObject, Language {
attribute DOMString value;
attribute DOMString link;
attribute DOMString organization;
attribute DOMString type;
};
3.9.2.1 Attributes
link of type DOMString- This attribute holds a link to the license if it is externally
available.
No exceptions.
organization of type DOMString- This attribute identifies the organization that issued the license.
No exceptions.
type of type DOMString- This attribute holds the actual type of the policy, which can be
filtered on in the
getProperty operation. Examples are
"license", "access", and "privacy".
No exceptions.
value of type DOMString- This attribute holds the description of the license.
No exceptions.
image = document.getElementsByTagName("img")[0];
policy = image.getProperty("policy");
http://creativecommons.org/licenses/by/2.5
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=policy
Response (JSON format): { "policy" : { "value": "Attribution 2.5 ",
"organization" : "http://creativecommons.org/licenses/by/2.5", "type":
"license" } }
3.10
Distribution Properties
3.10.1
Publisher interface
Publisher interface is used as the specific return type of
MediaResource.getProperty method which has "Publisher" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Publisher : MAObject {
attribute DOMString value;
};
3.10.1.1
Attributes
value of type DOMString- This attribute should represent the name of the publisher.
No exceptions.
image = document.getElementsByTagName("img")[0];
publisher = image.getProperty("publisher");
http://individuals.example.com/JohnDoe
Usage as a service:
3.10.2
TargetAudience interface
TargetAudience interface is used as the specific return type of
MediaResource.getProperty method which has "TargetAudience" as a
value of propertyName parameter.
[NoInterfaceObject]
interface TargetAudience : MAObject, Language {
attribute DOMString issuer;
attribute DOMString classification;
attribute DOMString type;
};
3.10.2.1
Attributes
classification of
type DOMString- This attribute defines the actual classification.
No exceptions.
issuer of type DOMString- This attribute identifies the issuer of the classification.
No exceptions.
type of type DOMString- This attribute specifies the type of the classification, which can be
filtered on in the
getProperty operation. Examples are "Age
group" and "Geographical".
No exceptions.
image = document.getElementsByTagName("img")[0];
targetAudience = image.getProperty("targetaudience");
http://www.fosi.org/icra
Usage as a service:
Request:
http://example.com/my-media-resource/?ma-query=targetaudience
Response (JSON format): { "targetaudience" : { "issuer" :
"http://www.fosi.org/icra", "classification" : "no nudity", "type" : "Age
Group" } }
3.11 Fragments
Properties
3.11.1
Fragments interface
Fragments interface is used as the specific return type of
MediaResource.getProperty method which has "Fragments" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Fragments : MAObject {
attribute DOMString role;
attribute DOMString id;
};
3.11.1.1
Attributes
id of type DOMString- This attribute identifies the fragment.
No exceptions.
role of type DOMString- This attribute holds the role of the fragment, which can be filtered on
in the
getProperty operation.
No exceptions.
movie = document.getElementsByTagName("movie")[0];
fragments = movie.getProperty("fragments");
http://www.example.com/movie.mov
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=fragments
Response (JSON format): { "fragments" : { "role" : "Person",
"identifier" : "http://www.example.com/movie.mov#xywh=320,320,40,100" }
}
3.11.2
NamedFragments interface
NamedFragments interface is used as the specific return type of
MediaResource.getProperty method which has "NamedFragments" as a
value of propertyName parameter.
[NoInterfaceObject]
interface NamedFragments : MAObject {
attribute DOMString name;
attribute DOMString id;
};
3.11.2.1
Attributes
id of type DOMString- This attribute identifies the fragment.
No exceptions.
name of type DOMString- This attribute specifies the name given to the fragment.
No exceptions.
image = document.getElementsByTagName("img")[0];
namedFragments = image.getProperty("NamedFragments");
http://www.w3.org/2008/WebVideo/Annotations/wiki/Image
Usage as a service:
Request:
http://example.com/my-media-resource/?ma-query=namedFragments
Response (JSON format): { "namedfragments" : { "name" : "Joakim
Söderberg", "identifier" :
"http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG#xywh=1600,550,80,150"
} }
3.12 Technical
Properties
3.12.1
FrameSize interface
FrameSize interface is used as the specific return type of
MediaResource.getProperty method which has "FrameSize" as a value
of propertyName parameter.
[NoInterfaceObject]
interface FrameSize : MAObject {
attribute unsigned long width;
attribute unsigned long height;
attribute DOMString unit;
};
3.12.1.1
Attributes
height of type unsigned long- This attribute represents the height of the frame.
No exceptions.
unit of type DOMString- This attribute represents the unit of the frame. The default value is
pixels.
No exceptions.
width of type unsigned long- This attribute represents the width of the frame.
No exceptions.
image = document.getElementsByTagName("img")[0];
frameSize = image.getProperty("framesize");
Usage as a service:
Request: http://example.com/my-media-resource/?ma-query=frameSize
Response (JSON format): { "framesize" : { "width" : 3.072, "height" :
2.304 } }
3.12.2
Compression interface
Compression interface is used as the specific return type of
MediaResource.getProperty method which has "Compression" as a
value of propertyName parameter.
[NoInterfaceObject]
interface Compression : MAObject, Language {
attribute DOMString value;
};
3.12.2.1
Attributes
value of type DOMString- This attribute specifies the compression type as a plain string.
No exceptions.
video = document.getElementsByTagName("video")[0];
compression = video.getProperty("compression");
Usage as a service:
3.12.3
Duration interface
Duration interface is used as the specific return type of
MediaResource.getProperty method which has "Duration" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Duration : MAObject {
attribute unsigned long value;
};
3.12.3.1
Attributes
value of type unsigned long- This attribute should represent the duration (in secs).
No exceptions.
video = document.getElementsByTagName("video")[0];
duration = video.getProperty("duration");
Usage as a service:
3.12.5
Samplingrate interface
Samplingrate interface is used as the specific return type of
MediaResource.getProperty method which has "Samplingrate" as a
value of propertyName parameter.
[NoInterfaceObject]
interface Samplingrate : MAObject {
attribute unsigned long value;
};
3.12.5.1
Attributes
value of type unsigned long- This attribute specifies the samplingrate (in Hz).
No exceptions.
audio = document.getElementsByTagName("audio")[0];
samplingrate = audio.getProperty("samplingrate");
Usage as a service:
3.12.6
Framerate interface
Framerate interface is used as the specific return type of
MediaResource.getProperty method which has "Framerate" as a value
of propertyName parameter.
[NoInterfaceObject]
interface Framerate : MAObject {
attribute float value;
};
3.12.6.1
Attributes
value of type float- This attribute specifies the framerate (in fps).
No exceptions.
video = document.getElementsByTagName("video")[0];
framerate = video.getProperty("framerate");
Usage as a service:
3.12.7
AverageBitrate interface
AverageBitrate interface is used as the specific return type of
MediaResource.getProperty method which has "AverageBitrate" as a
value of propertyName parameter.
[NoInterfaceObject]
interface AverageBitrate : MAObject {
attribute float value;
};
3.12.7.1
Attributes
value of type float- This attribute specifies the average bitrate (in kbps).
No exceptions.
Example is as below:
video = document.getElementsByTagName("video")[0];
bitrate = video.getProperty("averagebitrate");
Usage as a service:
3.12.8
NumTracks interface
NumTracks interface is used as the specific return type of
MediaResource.getProperty method which has "NumTracks" as a value
of propertyName parameter.
[NoInterfaceObject]
interface NumTracks : MAObject {
attribute unsigned short value;
attribute DOMString type;
};
3.12.8.1
Attributes
type of type DOMString- This attribute specifies the type of the tracks e.g., "Songs", "Data
streams".
No exceptions.
value of type unsigned short- This attribute specifies the number of tracks.
No exceptions.
video = document.getElementsByTagName("video")[0];
numTracks = video.getProperty("NumTracks");
Usage as a service:
4. Usage examples
This part illustrates some examples to show how to use the API using
JavaScript in actual implementations. The examples assume that the methods
getElementsByTagName() and getElementsById() return an element that implements
the MediaResource interface. Moreover, in these examples it is
assumed that the implementation of the API knows where to find the metadata
that corresponds to a specific media resource (if necessary the location of the
metadata can be configured using the selectMAResource method). The
implementation should provide the mappings of different metadata formats to the
core properties.
- Example 1: Return the name of the director of the movie "Apocalypse now".
video = document.getElementsByTagName("video");
for(i=0; i<video.length; i++)
{
titles = video[i].getProperty("title");
for(j = 0; j<titles.length; j++)
{
if(titles[j].value == "Apocalypse Now")
{
director = video[i].getProperty("contributor","","","director");
}
}
}
- Example 2: Retrieve the title of the second song from the album "Josuha
Tree" by U2.
album = document.getElementById("JosuhaTree_U2");
trackid = album.getProperty("Fragments","","","Song")[1].id;
mediaResource = new MediaResource();
mediaResource.selectMediaResource(trackid);
title = mediaResource.getProperty("Title")[0].value;
- Example 3: Return the copyright of the movie "Planet of the apes".
movie = document.getElementById("Planet_of_the_apes_id");
copyright = movie.getProperty("copyright","","","","en-us")[0].statement;
- Example 4: Return the genre of the movie "Apocalypse Now".
movie = document.getElementById("Apocalypse_Now_id");
genre = movie.getProperty("genre","","","","en-us");
5. API Status
Codes
This section introduces a set of status codes for the defined API to
indicate the system behaviour. It uses a subset of the HTML/1.1 [HTTP11] status
codes for general informations (e.g., bad request), but also system
specific ones (e.g., property not defined in source format). The specific
status codes have been arranged in the HTML/1.1 [HTTP11] status codes categories.
These codes can be retrieved by calling the getDiagnosis
method.
The set of status codes my be enlarged or changed in later
versions of this document. The numerical code range for the system specific
status codes start with x62 (x = number of HTML/1.1 [HTTP11] status
codes category and 62 = MA).
| Numerical Code |
Textual Description |
Example |
| 200 |
Ok |
property delivered correctly |
| 204 |
No Content |
property retrieved without content |
| 206 |
Partial Content |
only a subset of the available data stored in the result set |
| 262 |
Syntactic Mapping |
retrieval used a syntactic mapping |
| 263 |
Semantic Mapping |
retrieval used a semantic mapping |
| 264 |
Structured Return Value |
result is structured |
| 265 |
Unstructured Return Value |
result is unstructured |
| 400 |
Bad Request |
syntactical error with respect to the GET method used |
| 404 |
Not Found |
the queries resource is not found |
| 415 |
Unsupported Media Type |
get duration call on an image data store |
| 462 |
Property not defined in Source Format |
location is not defined in MediaRSS |
| 500 |
Internal Server Error |
internal library (e.g., extractor) crashes |
| 501 |
Not Implemented |
only a subset of GET methods for properties implemented |
A. Web IDL
description for API
module mawg {
interface MediaResource {
//Media Resource context
boolean selectMAResource(in DOMString mediaResource, in optional MetadataSource[] metadataSources );
// Property Access
MAObject[] getProperty(in DOMString propertyName, in optional DOMString fragment, in optional DOMString sourceFormat, in optional DOMString subtype,
in optional DOMString language );
//Iterating
DOMString[] getPropertyNamesWithValues(in optional DOMString sourceFormat,
in optional DOMString language, in optional DOMString fragment);
DOMString[] getSourceFormatsWithValues(in optional DOMString language);
DOMString getOriginalData(in DOMString sourceFormat);
//Operation for retrieval of the reason of an error
DOMString getDiagnosis();
};
interface MetadataSource {
attribute DOMString metadataSource;
attribute DOMString sourceFormat;
};
module returnValues {
interface MAObject {
attribute DOMString unstructuredValue;
attribute DOMString uri;
attribute DOMString sourceFormat;
attribute DOMString fragmentIdentifier;
attribute DOMString mappingType;
};
interface Language {
attribute DOMString language;
};
interface UnsignedLongObject: MAObject {
attribute unsigned long value;
};
interface UnsignedShortObject: MAObject {
attribute unsigned short value;
};
interface FloatObject: MAObject {
attribute float value;
};
interface Identifier: MAObject {
attribute DOMString value;
attribute DOMString type;
};
interface Title: MAObject, Language {
attribute DOMString value;
attribute DOMString type;
};
interface Language : MAObject {
attribute DOMString value;
};
interface Locator : MAObject {
attribute DOMString value;
};
interface Contributor: MAObject {
attribute DOMString id;
attribute DOMString role;
};
interface Creator : MAObject {
attribute DOMString value;
};
interface Date: MAObject {
attribute DOMString date;
attribute DOMString type;
};
interface Location: MAObject, Language {
attribute DOMString name;
attribute Float longitude;
attribute Float latitude;
attribute Float altitiude;
attribute DOMString system;
};
interface Description : MAObject, Language {
attribute DOMString value;
};
interface Keyword : MAObject, Language {
attribute DOMString value;
};
interface Genre : MAObject, Language {
attribute DOMString value;
};
interface Rating: MAObject, Language {
attribute DOMString issuer;
attribute short value;
attribute short minimum;
attribute short maximum;
attribute DOMString context;
attribute DOMString type;
};
interface Relation: MAObject, Language {
attribute DOMString id;
attribute DOMString relationship;
};
interface Copyright: MAObject, Language {
attribute DOMString statement;
attribute DOMString[] holder;
};
interface Policy: MAObject, Language {
attribute DOMString statement;
attribute DOMString link;
attribute DOMString organization;
attribute DOMString type;
};
interface Publisher: MAObject {
attribute DOMString value;
};
interface TargetAudience: MAObject, Language {
attribute DOMString issuer;
attribute DOMString classification;
};
interface Fragment: MAObject, Language {
attribute DOMString role;
attribute DOMString id;
};
interface NamedFragment: MAObject, Language {
attribute DOMString name;
attribute DOMString id;
};
interface FrameSize: MAObject {
attribute unsigned long width;
attribute unsigned long height;
attribute DOMString unit;
};
interface Compression : MAObject, Language {
attribute DOMString value;
};
interface Duration : MAObject {
attribute unsigned long value;
};
interface Format : MAObject {
attribute DOMString value;
};
interface Samplingrate : MAObject {
attribute unsigned long value;
};
interface Framerate : MAObject {
attribute float value;
};
interface AverageBitrate : MAObject {
attribute float value;
};
interface NumTracks : MAObject {
attribute unsigned short value;
attribute DOMString type;
};
};
};
B. Acknowledgements
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): Members of the Working Group are (at the time of writing,
and by alphabetical order): Werner Bailer (JOANNEUM RESEARCH), Tobias B체rger
(University of Innsbruck), Eric Carlson (Apple, Inc.), Pierre-Antoine Champin
((public) Invited expert), Ashish Chawla ((public) Invited expert), Jaime
Delgado (Universitat Polit챔cnica de Catalunya), Jean-Pierre EVAIN ((public)
Invited expert), Philip J채genstedt (Opera Software), 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.),
Florian Stegmaier ((public) Invited expert), John Strassner ((public) Invited
expert), 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.
