Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 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.