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.