Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
Thiss 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 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.
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. The Working Group expects to advance this specification to Recommendation Status.
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.
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.2.1 Identification Properties
2.2.1.1 Identifier
2.2.1.2 Title
2.2.1.3 Language
2.2.1.4 Locator
2.2.2 Creation Properties
2.2.2.1 Contributors
2.2.2.2 Creators
2.2.2.3 CreateDate
2.2.2.4 Location
2.2.3 Content Properties
2.2.3.1 Description
2.2.3.2 Keyword
2.2.3.3 Genre
2.2.3.4 Rating
2.2.4 Relational
Properties
2.2.4.1 Relation
2.2.4.2 Collection
2.2.5 Rights Properties
2.2.5.1 Copyright
2.2.5.2 License
2.2.6 Distribution
Properties
2.2.6.1 Publisher
2.2.6.2 TargetAudience
2.2.7 Fragments
Properties
2.2.7.1 Fragments
2.2.7.2 NamedFragments
2.3 API for Technical
Properties
2.3.1 FrameSize
2.3.2 Compression
2.3.3 Duration
2.3.4 Format
2.3.5 Samplingrate
2.3.6 Framerate
2.3.7 Bitrate
2.3.8 NumTracks
2.4 API for Iterating
operation
3 Examples of how to use the API
A Web IDL description for API
B References(Normative)
C References(Non-Normative)
D Acknowledgements (Non-Normative)
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 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 Web IDL. 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.
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 contains only a 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.
Refers to the formats in scope of Ontology for Media Resource 1.0.
Refers to the Formats out of scope of Ontology for Media Resource 1.0.
In this document the terms "Media Resource", "Property", "Mapping" and "Property value type" are to be interpreted as defined in Section 2 of Ontology for Media Resource 1.0.
| 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. | |
This part defines the interface for accessing the metadata. The API has been
described using Web IDL. 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 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.
This part defines part of the interface for accessing the descriptive metadata that describes a work for purposes of discovery and identification, such as creators, title, language and extra. The properties have been grouped in different categories.
readonly attribute DOMString identifier getraises (NoValue);
The identifier property identifies a resource.
A DOMString which should represent a URI identifying
the resource.
The NoValue exception is thrown if no value is
available.
"http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG"
readonly attribute DOMString title getraises (NoValue);
The title property defines the title of the document,
or the name given to the resource.
A DOMString that holds the title as a plain string.
The NoValue exception is thrown if no value is
available.
"MAWG Stockholm 20090626"
readonly attribute DOMString language getraises (NoValue);
The language property specifies a language used in the
entity, Recommended best practice is to use BCP 47 [BCP 47].
A DOMString that represents the language as a plain
string.
The NoValue exception is thrown if no value is
available.
N/A
readonly attribute DOMString locator getraises (NoValue);
The locator property holds a URI at which the entity
can be accessed (e.g. a URL, or a DVB URI).
A DOMString that holds the URI.
The NoValue exception is thrown if no value is
available.
"http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG"
readonly attribute object[] contributors getraises (NoValue);
The contributors property holds a pair identifying the
contributors and the nature of the contribution. E.g.actor, cameraman,
dirctor,singer, author, artist (Note: subject see addition of
contributors type) identifies a resource.
An array of object elements implementing the
Contributors interface. This object has an attribute
id which identifies the contributors. Additionally, the
role attribute defines the role. For the latter a number of
suggested
terms are defined.
interface Contributors: Unstructured {
attribute DOMString id;
attribute DOMString role;
};
The NoValue exception is thrown if no value is
available.
[http://individuals.example.com/Author1, "author"], [http://individuals.example.com/Author2, "author"]
readonly attribute DOMString[] creators getraises (NoValue);
The creators property holds the authors of the resource
(listed in order of precedence, if significant).
An array of DOMString element, each identifying an
author of the resource.
The NoValue exception is thrown if no value is
available.
["http://individuals.example.com/Author1", "http://individuals.example.com/Author2"]
readonly attribute object createDate getraises (NoValue);
The createDate property holds the date and time the
entity was originally created. (for commercial purpose there might be an
annotation of publication date).
An object implementing the Date interface.
This object is currently undefined.
interface Date: Unstructured {
// to be defined …
};
The NoValue exception is thrown if no value is
available.
2009-06-26T15:30:00
readonly attribute object location getraises (NoValue);
The location property holds the location where the
resource has been shot/recorded.
A object implementing the Location
interface. This object is currently undefined.
interface Location: Unstructured {
// to be defined …
};
The NoValue exception is thrown if no value is available.
"Sweden", " Stockholm, Kistavägen 25, KISTA, KMUM Building", "Ericsson", ...
readonly attribute DOMString description getraises (NoValue);
The description property holds a textual description of
the content of the resource.
An DOMString holds the description of the content of
the resource.
The NoValue exception is thrown if no value is
available.
"Group picture of the W3C Media Annotations WG at the face-to-face meeting in Stockholm."
readonly attribute DOMString[] keyword getraises (NoValue);
The keyword property represents an unordered array of
descriptive phrases or keywords that specify the topic of the content of
the resource.
An Array of DOMString element, each corresponding to
one descriptive phrase or keyword.
The NoValue exception is thrown if no value is
available.
["W3C Media Annotations WG", "meeting", "group picture"]
readonly attribute DOMString genre getraises (NoValue);
The genre property describes the genre of the
entity.
An DOMString representing the genre of the entitiy.
The NoValue exception is thrown if no value is
available.
"Work"
| Editorial note | |
| It should be clarified about what the 'context' of a rating is | |
readonly attribute object rating getraises (NoValue);
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.
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;
};
The NoValue exception is thrown if no value is available.
[http://individuals.example.com/ChrisPoppe, 10.0, 0, 10.0, "quality"]
readonly attribute object[] relation getraises (NoValue);
The relation property holds pairs identifying the
entities and the nature of the realtionships. E.g. transcript,
original_work.
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;
};
The NoValue exception is thrown if no value is
available.
[http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626_thumb.JPG, "re-edit"]
readonly attribute DOMString collection getraises (NoValue);
The collection property holds a name of the collection
from wich the entities originates.
A DOMString representing the name of the collection
from wich the entities originates.
The NoValue exception is thrown if no value is
available.
"My Work Pictures"
readonly attribute object[] copyright getraises (NoValue);
The copyright property holds the copyright statement
and an identification of the copyrights holder (DRM is out of scope for
MAWG).
An array ofobject 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;
};
The NoValue exception is thrown if no value is
available.
["All images in the collection are copyrighted by John Doe", http://individuals.example.com/JohnDoe]
| Editorial note | |
| license/statement attribute: is this really free text? | |
readonly attribute object license getraises (NoValue);
The license property holds a description of the license
of the media resource or reference.
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;
};
The NoValue exception is thrown if no value is
available.
["Attribution 2.5 ", http://creativecommons.org/licenses/by/2.5]
readonly attribute DOMString publisher getraises (NoValue);
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.
A DOMString representing the name of the publisher.
The NoValue exception is thrown if no value is
available.
"http://individuals.example.com/JohnDoe"
readonly attribute object targetAudience getraises (NoValue);
The targetAudience property holds a pair identifying
the issuer of the classification (agency) and the classification. E.g.
parental guide, targeted geographical region.
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;
};
The NoValue exception is thrown if no value is
available.
[http://www.fosi.org/icra,"no nudity"]
readonly attribute object[] fragments getraises (NoValue);
The fragments property holds a list of pairs of
fragment role and fragment identifier (e.g. chapters, favourite
scenes).
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;
};
The NoValue exception is thrown if no value is
available.
[["Person", http://www.example.com/movie.mov#xywh=320,320,40,100],
["Person", http://www.example.com/movie.mov#xywh=300,350,40, 40]]
readonly attribute object[] namedFragments getraises (NoValue);
The namedFragments property holds the list of named
fragments annotated for this resource (pairs of label and fragment
identifier).
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;
};
The NoValue exception is thrown if no value is
available.
[["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]]
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.
readonly attribute object frameSize getraises (NoValue);
The frameSize property determines the frame size.
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;
};
The NoValue exception is thrown if no value is
available.
[3.072, 2.304]
readonly attribute DOMString compression getraises (NoValue);
The compression property holds the compression type
used. Note: it might be possible to use extended mime type, see RFC
4281.
A DOMString representing the compression type.
The NoValue exception is thrown if no value is
available.
"H.264/AVC"
| Editorial note | |
| Further consideration is required for the unit of Duration. (e.g. Is it fixed to 'second'?) | |
readonly attribute unsigned long duration getraises (NoValue);
The duration property represents the duration of the
entitiy.
An unsigned long representing the duration (in
secs).
The NoValue exception is thrown if no value is
available.
3600
readonly attribute DOMString format getraises (NoValue);
The format property holds the MIME type of the entity
(wrapper, bucket media types).
A DOMString representing the MIME type.
The NoValue exception is thrown if no value is
available.
"image/jpeg"
readonly attribute unsigned long samplingrate getraises (NoValue);
The samplingrate property holds the samplingrate of an
audio file. Only applicable for audio.
An unsigned long representing the samplingrate (in
Hz).
The NoValue exception is thrown if no value is
available.
100
readonly attribute float framerate getraises (NoValue);
The framerate property holds the frame rate of the
video. Only applicable for video.
An float representing the framerate (in fps).
The NoValue exception is thrown if no value is
available.
30
| Editorial note | |
| Should bitrate be a number? What about Variable Bit Rate? Or would we raise NoValue in that case? | |
readonly attribute float bitrate getraises (NoValue);
The bitrate property holds the average bitrate. Only
applicable for audio and video.
An float representing the bitrate (in kbps).
The NoValue exception is thrown if no value is
available.
100
readonly attribute unsigned short numTracks getraises (NoValue);
The numTracks property holds the number of tracks.
An unsigned short representing the number of tracks.
The NoValue exception is thrown if no value is
available.
2
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[] 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);
// 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 Contributors: 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;
};
};
};
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 (Eurecom), 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.