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.
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
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.