This specification defines a client-side API to access metadata information related to media resources on the Web. The overall purpose of the API is to provide developers with a convenient access to metadata information stored in different metadata formats. The API is described using the interface definition language Web IDL. Thereby, the Media Ontology Core Properties will be used as a pivot vocabulary in the API.

Introduction

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.2 Formats in scope) are stored in the Media Ontology in order to provide cross-community data integration. The API is described using the interface definition language [[WEBIDL]]. 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 Resources 1.0 [[!MEDIA-ANNOT-REQS]]. This document clearly states that the focus for this API is on multimedia services on the Web.

The API serves as a mediator between a developer and the Ontology for Media Resources 1.0 [[!MEDIA-ANNOT-ONTOLOGY]] with the goal of supporting interoperability between metadata formats. It offers operations to retrieve 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 addition, 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.

Usage examples

This part will illustrate some examples to show how to use the API in the actual (working) implementations. This part should be added before going to the LC.

Formats in scope

Refers to the formats in scope of Ontology for Media Resources 1.0.

Formats out of scope

Refers to the Formats out of scope of Ontology for Media Resources 1.0.

Terminology

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

Design consideration

We consider two scenarios where the API could be implemented: either in the user agent (scenario 1) or as a web service (scenario 2). The two scenarios are shown in the figure.

Scenario 1: User agent
The API is implemented in the user agent (e.g., browser or browser plugin) and exposed as a JavaScript API (using the WebIDL JavaScript binding). The user agent includes the components for metadata access (possibly extraction) and mappings for a supported set of formats. The metadata sources (the media resource and/or metadata document(s)) must be retrievable and access (establish connection, retrieval) of the metadata sources is handled by the user agent.
Scenario 2: Web service
The API is implemented as a Web service. Such an implementation would be typically used by a non-UI client, such as an agent harvesting metadata. However, the API could be also accessed from a user agent, and used the same way as described in scenario 1 by the help of a JavaScript library for accessing the web service. At the back-end of the web service, this scenario also allows supporting a media repository (e.g. content provider's archive database, movie store) from which the user agent could directly retrieve metadata sources and which might have a custom metadata format not supported by a user agent. In contrast to an integrated component (see scenario 1), an implementation of the API in a web service could do more complex mappings on the fly as a component integrated in a user agent, and can be more flexible (e.g., supporting additional formats).The API is implemented as a Web service. Such an implementation would be typically used by a non-UI client, such as an agent harvesting metadata. However, the API could be also accessed from a user agent, and used the same way as described in scenario 1 by the help of a JavaScript library for accessing the web service. At the back-end of the web service, this scenario also allows supporting a media repository (e.g. content provider's archive database, movie store) from which the user agent could directly retrieve metadata sources and which might have a custom metadata format not supported by a user agent. In contrast to an integrated component (see scenario 1), an implementation of the API in a web service could do more complex mappings on the fly as a component integrated in a user agent, and can be more flexible (e.g., supporting additional formats).

Overview of different API options.

In both scenarios, the access to the metadata properties needs the following stack of components:

API Description

There are many open issues about setting interfaces, meaning changing the value of properties, so these issues will be covered later.

The API has been described using Web IDL and can be found in Appendix A. The API is contained within the MediaResource interface within the mawg module. Objects implementing this interface provide the necessary methods to access metadata of a Media Resource. The object holds methods to identify the actual Media Resource and the metadata sources. All properties can be accessed through a specific operation getProperty. Currently, only read access is defined. When an attempt to read a property fails, diagnostics information can be obtained using a diagnosis operation. Lastly, methods are available that allow to iterate through the available metadata.

MediaResource interface

MediaResource interface offers a number of operations that allow accessing the metadata of a Media Resource.

Example on how to introduce this in HTML5 by making the HTMLMediaElement inherit from the MediaResource interface:

interface HTMLMediaElement : MediaResource, HTMLElement {...}

Example of usage in javascript:

						mediaResource = document.getElementsByTagName("video")[0];
						titleProperty = mediaResource.getProperty("title");
						...

The javascript examples in this document will only work if the API is implemented by the browser.

boolean selectMAResource ()
This operation allows to set the specific Media Resource and metadata sources for which the API applies.
DOMString mediaResource
The mediaResource argument identifies the Media Resource. The implementation of the API should try to find relevant metadata sources for this Media Resource
optional MetadataSource[] metadataSources
This argument is an array of objects, each implementing the MetadataSource interface. This interface holds an uri identifying the metadata source (metadataSource) and the name of the actual metadata format (sourceFormat). This parameter is OPTIONAL.
MAObject[] getProperty ()
This operation allows to retrieve the value of a certain property.
DOMString propertyName
This argument identifies the property for which the values need to be retrieved. Optional arguments allow to refine the request
optional DOMString fragment
This argument allows to identify the specific media fragment for which the metadata is requested. This parameter is OPTIONAL.
optional DOMString sourceFormat
This argument identifies a specific metadata format. If a metadata format is defined, only the metadata available in the corresponding metadata format are retrieved. This parameter is OPTIONAL.
optional DOMString subtype
This argument identifies a subtype. Some properties can be filtered on subtypes. This parameter is OPTIONAL.
optional DOMString language
This argument allows to identify the language of the metadata. Only if the metadata is available in the specified language, the values are returned. This parameter is OPTIONAL.

Example in javascript:

						video = document.getElementsByTagName("video")[0];
						titleProperty = video.getProperty("title","","","","");

						/*Resulting in:
						titleProperty[0].value = "Planet of the apes"
						titleProperty[0].type = "Main title"
						titleProperty[0].language = "en-us"
						titleProperty[1].value = "La planete des singes"
						titleProperty[1].type = "Main title"
						titleProperty[1].language = "fr"
						titleProperty[2].value = "Monkey Planet"
						titleProperty[2].type = "Alternative title"
						titleProperty[2].language = "en-us"
						*/
						
						titleProperty = video.getProperty("title","","","Main title","en-us");
						
						/*Resulting in:
						titleProperty[0].value = "Planet of the apes"
						titleProperty[0].type = "Main title"
						titleProperty[0].language = "en-us"
						*/
DOMString[] getPropertyNamesWithValues ()
This operation allows to retrieve all property names for which metadata is available. If this operation returns a property name, this means that a call to the getProperty operation with the corresponding property name will return at least one object.
optional DOMString sourceFormat
This argument identifies a specific metadata format. If a metadata format is defined, only the metadata available in the corresponding metadata format are retrieved. This parameter is OPTIONAL.
optional DOMString language
This argument allows to identify the language of the metadata. Only if the metadata is available in the specified language, the values are returned. This parameter is OPTIONAL.
optional DOMString fragment
This argument allows to identify the specific media fragment for which the metadata is requested. This parameter is OPTIONAL.

Example in javascript:

						video = document.getElementsByTagName("video")[0];
						propertyNames = video.getPropertyNamesWithValues();

						/*Resulting in:
						propertyNames[0] = "identifier"
						propertyNames[1] = "title"
						*/

Usage as a service:

DOMString[] getSourceFormatsWithValues ()
This operation allows to retrieve all source formats for which metadata is available. If this operation returns a source format, this means that a call to the getProperty operation with the corresponding source format will return at least one object.
optional DOMString language
This argument allows to identify the language of the metadata. Only if the metadata is available in the specified language, the values are returned. This parameter is OPTIONAL.

Example in javascript:

						video = document.getElementsByTagName("video")[0];
						sourceFormats = video.getSourceFormatsWithValues();

						/*Resulting in:
						sourceFormats[0] = "OGG"
						sourceFormats[1] = "MPEG-7"
						*/

Usage as a service:

DOMString getDiagnosis()

This operation allows to retrieve the reason for an error (e.g., the getProperty operation returning a null value).

Example in javascript:

						audio = document.getElementsByTagName("audio")[0];
						framerate = audio.getProperty("framerate");
						error = audio.getDiagnosis();

						/*Resulting in:
						error = "OGG"
						*/

Usage as a service:

DOMString[] getOriginalData ()
This operation allows to retrieve the original metadata according to the specified source format.
DOMString sourceFormat
This argument identifies a specific metadata format. If a metadata format is defined, only the metadata available in the corresponding metadata format are retrieved.

Example in javascript:

						video = document.getElementsByTagName("video")[0];
						DCMetadata = video.getOriginalData("DC");

						/*Resulting in:
						DCMetadata[0] = "  DC title"; 
						*/

Usage as a service:

MetadataSource interface

MetadataSource interface is used to identify other metadata sources.

attribute DOMString metadataSource
An URI identifying the metadata source.
attribute DOMString sourceFormat
The name of the actual metadata format.

Language interface

Language interface is used to identify the language of the metadata.

attribute DOMString language
This attribute holds the language of the metadata.

MAObject interface

MAObject interface is used as the return type of MediaResource.getProperty method. This is used to hold the values of the requested property. Depending on the requested property, these objects implement a different interface.

attribute DOMString unstructuredValue
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.
attribute DOMString uri
This attribute is provided which should hold an URI. This can for example be used to represent labels as URIs.
attribute DOMString sourceFormat
This attribute allows to specify the metadata source from which the metadata was retrieved.
attribute DOMString fragmentIdentifier
This attribute determines the fragment for which the metadata is relevant.
attribute DOMString mappingType
This attribute specifies the kind of mapping as discussed in the semantic level mappings.

Identification Properties

Identifier interface

Identifier interface is used as the specific return type of MediaResource.getProperty method which has "Identifier" as a value of propertyName parameter.

attribute DOMString value
This attribute should represent a URI identifying the resource.
attribute DOMString type
This attribute holds the type of the identifier, which can be filtered on in the getProperty operation. Possible values are " UMID" and "ISAN".

Example in javascript is as below:

					image = document.getElementsByTagName("img")[0];
					id = image.getProperty("identifier");

					/*Resulting in:
					id[0].value = "http://www.w3c.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG"
					id[0].type = "URI"
					id[1].value= "ISAN 0000-3BAB-9352-0000-G-0000-0000-Q"
					id[1].type="ISAN"
					*/

The javascript example assumes that getElementsByTagName("img") returns an object implementing the MediaResource interface.

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=identifier

  • Response (JSON format): "identifier" : ["ISAN 0000-3BAB-9352-0000-G-0000-0000-Q"]

Title interface

Title interface is used as the specific return type of MediaResource.getProperty method which has "Title" as a value of propertyName parameter.

attribute DOMString value
This attribute should hold the title as a plain string.
attribute DOMString type
This attribute contains the type of the title, which can be filtered on in the getProperty operation.

Example in javascript is as below:

					song = document.getElementsByTagName("audio")[0];
					title = song.getProperty("title");

					/*Resulting in:
					title[0].value = "Artificial Horizon"
					title[0].type = "Album title"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=title

  • Response (JSON format): "title" : [:"Artificial Horizon"]

Language interface

Language interface is used as the specific return type of MediaResource.getProperty method which has "Language" as a value of propertyName parameter. Recommended best practice is to use BCP 47 [[BCP-47]].

attribute DOMString value
This attribute should represent the language as a plain string.

Example in javascript is as below:

					video = document.getElementsByTagName("video")[0];
					language = video.getProperty("language");

					/*Resulting in:
					language[0].value = "en-us"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=language

  • Response (JSON format): "language" : ["en-us"]

Locator interface

Locator interface is used as the specific return type of MediaResource.getProperty method which has "Locator" as a value of propertyName parameter.

attribute DOMString value
This attribute should hold the URI.

Example in javascript is as below:

					image = document.getElementsByTagName("img")[0];
					locator = image.getProperty("locator");

					/*Resulting in:
					locator[0].value = "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=locator

  • Response (JSON format): "locator" : ["http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG"]

Creation Properties

Contributor interface

Contributor interface is used as the specific return type of MediaResource.getProperty method which has "Contributor" as a value of propertyName parameter.

attribute DOMString id
This attribute identifies the contributor.
attribute DOMString role
This attribute defines the role, which can be filtered on in the getProperty operation. For the latter a number of suggested terms are defined:

  • editor (EBU 11.1)

  • actor (EBU 25.9)

  • composer

  • featured_in

  • cinematographer

  • director

  • musicproducer

  • producer

  • screenplayer

  • writer

  • distributor (company)

  • production company

Example in javascript is as below:

					video = document.getElementsByTagName("video")[0];
					contributor = video.getProperty("contributor");

					/*Resulting in:
					contributor[0].id = "http://individuals.example.com/Contributor1"
					contributor[0].role = "editor"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=contributors

  • Response (JSON format): "contributors" : ["http://individuals.example.com/Contributor1"]

Creator interface

Creator interface is used as the specific return type of MediaResource.getProperty method which has "Creator" as a value of propertyName parameter.

attribute DOMString value
This attribute should hold an identifier for an author.

Example in javascript is as below:

					video = document.getElementsByTagName("video")[0];
					creator = video.getProperty("creator");

					/*Resulting in:
					creator[0].value = "http://individuals.example.com/Author1"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=creator

  • Response (JSON format): "creator" : ["http://individuals.example.com/Author1"]

CreateDate interface

CreateDate interface is used as the specific return type of MediaResource.getProperty method which has "CreateDate" as a value of propertyName parameter.

attribute DOMString date
The exact format of this attribute is currently undefined.
attribute DOMString type
This attribute define the specific type of creation, which can be filtered on in the getProperty operation. Possibilities are "Create Date" and "Publish Date".

Example in javascript is as below:

					video = document.getElementsByTagName("video")[0];
					createdate = video.getProperty("createdate");

					/*Resulting in:
					createdate[0].date = "2009-06-26T15:30:00"
					createdate[0].type = "Create Date"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=createDate

  • Response (JSON format): "createDate" : ["2009-06-26T15:30:00"]

Location interface

Location interface is used as the specific return type of MediaResource.getProperty method which has "Location" as a value of propertyName parameter.

attribute DOMString name
This attribute holds a free text name of the location.
attribute Float longitude
This attribute holds the longitude value from system defined in system.
attribute Float latitude
This attribute holds the latitude value from system defined in system.
attribute Float altitude
This attribute holds the altitude value from system defined in system.
attribute DOMString system
This attribute holds the name of location system.

Example in javascript is as below:

					video = document.getElementsByTagName("video")[0];
					location = video.getProperty("location");

					/*Resulting in:
					location[0].name = "San Jose"
					location[0].longitude = 37.33986481118008
					location[0].latitude = -121.88507080078125
					location[0].altitude = 0
					location[0].system = "GPS"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=location

  • Response (JSON format): "location" : ["San Jose", 37.33986481118008, -121.88507080078125, 0, "GPS"]

Content Properties

Description interface

Description interface is used as the specific return type of MediaResource.getProperty method which has "Description" as a value of propertyName parameter.

attribute DOMString value
This attribute should hold a description of the content of the media resource.
					image = document.getElementsByTagName("img")[0];
					description = image.getProperty("description");

					/*Resulting in:
					description[0].value = "Group picture of the W3C Media Annotations WG at the face-to-face meeting in Stockholm."
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=description

  • Response (JSON format): "description" : ["Group picture of the W3C Media Annotations WG at the face-to-face meeting in Stockholm."]

Keyword interface

Keyword interface is used as the specific return type of MediaResource.getProperty method which has "Keyword" as a value of propertyName parameter.

attribute DOMString value
This attribute should hold one keyword.
					image = document.getElementsByTagName("img")[0];
					keyword = image.getProperty("keyword");

					/*Resulting in:
					keyword[0].value = "W3C Media Annotations WG"
					keyword[1].value = "meeting"
					keyword[2].value = "group picture"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=keyword

  • Response (JSON format): "keyword" : ["W3C Media Annotations WG", "meeting", "group picture"]

Genre interface

Genre interface is used as the specific return type of MediaResource.getProperty method which has "Genre" as a value of propertyName parameter.

attribute DOMString value
This attribute should represent the genre of the media resource.
					image = document.getElementsByTagName("img")[0];
					genre = image.getProperty("genre");

					/*Resulting in:
					genre[0].value = "Work"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=genre

  • Response (JSON format): "genre" : ["Work"]

Rating interface

It should be clarified about what the 'context' of a rating is

Rating interface is used as the specific return type of MediaResource.getProperty method which has "Rating" as a value of propertyName parameter.

attribute DOMString issuer
This attribute identifies the rating person or organization
attribute short value
This attribute indicates the average rating.
attribute short minimum
This attribute specifies the minimum rating.
attribute short maximum
This attribute specifies the maximum rating.
attribute DOMString type
This attribute specifies the type of the rating, which can be filtered on in the getProperty operation. Possibilities are "Review Rating", "MPAA", "Personal Rating".
					image = document.getElementsByTagName("img")[0];
					rating = image.getProperty("rating");

					/*Resulting in:
					rating[0].issuer = "http://individuals.example.com/ChrisPoppe"
					rating[0].value = 10.0
					rating[0].minimum = 0
					rating[0].maximum = 10.0
					rating[0].type = "Personal Rating"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=rating

  • Response (JSON format): "rating" : ["http://individuals.example.com/ChrisPoppe", 10.0, 0, 10.0, "Personal Rating"]

Relational Properties

Relation interface

Relation interface is used as the specific return type of MediaResource.getProperty method which has "Relation" as a value of propertyName parameter.

attribute DOMString id
This attribute identifies the entitiy.
attribute DOMString relationship
This attribute specifies textual description of the relationship, which can be filtered on in the getProperty operation. For the latter a number of suggested terms are defined:

  • version of

  • reference

  • sound tracks

  • influenced by

  • re-edit

  • adapted_work

  • translated

  • interpretation

  • followed by

  • similar theme

  • similar touch

  • is similar to

  • nominated award

  • origin country

					image = document.getElementsByTagName("img")[0];
					relation = image.getProperty("relation");

					/*Resulting in:
					relation[0].id = "http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626_thumb.JPG"
					relation[0].relationship = "re-edit"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=relation

  • Response (JSON format): "relation" : ["http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626_thumb.JPG", "re-edit"]

Collection interface

Collection interface is used as the specific return type of MediaResource.getProperty method which has "Collection" as a value of propertyName parameter.

attribute DOMString value
This attribute should hold the name of the collection from which the media resource originates.
					image = document.getElementsByTagName("img")[0];
					collection = image.getProperty("collection");

					/*Resulting in:
					collection[0].value = "My Work Pictures"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=collection

  • Response (JSON format): "collection" : ["My Work Pictures"]

Rights Properties

Copyright interface

Copyright interface is used as the specific return type of MediaResource.getProperty method which has "Copyright" as a value of propertyName parameter.

attribute DOMString statement
This attribute should holds the copyright statement.
attribute DOMString[] holder
This attribute denotes the copyright holders.
					image = document.getElementsByTagName("img")[0];
					copyright = image.getProperty("copyright");

					/*Resulting in:
					copyright[0].statement = "All images in the collection are copyrighted by John Doe"
					copyright[0].holder[0] = "http://individuals.example.com/JohnDoe"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=rights-properties

  • Response (JSON format): "rights-properties" : ["All images in the collection are copyrighted by John Doe", "http://individuals.example.com/JohnDoe]"

Policy interface

license/statement attribute: is this really free text?

Policy interface is used as the specific return type of MediaResource.getProperty method which has "Policy" as a value of propertyName parameter.

attribute DOMString value
This attribute holds the description of the license.
attribute DOMString link
This attribute holds a link to the license if it is externally available.
attribute DOMString organization
This attribute identifies the organization that issued the license.
attribute DOMString type
This attribute holds the actual type of the policy, which can be filtered on in the getProperty operation. Current possibilities are "license", "access", and "privacy".
					image = document.getElementsByTagName("img")[0];
					policy = image.getProperty("policy");

					/*Resulting in:
					policy[0].value = "Attribution 2.5"
					policy[0].organization = "http://creativecommons.org/licenses/by/2.5"
					policy[0].type = "license"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=policy

  • Response (JSON format): "policy" : ["Attribution 2.5 ", "http://creativecommons.org/licenses/by/2.5"]

Distribution Properties

Publisher interface

Publisher interface is used as the specific return type of MediaResource.getProperty method which has "Publisher" as a value of propertyName parameter.

attribute DOMString value
This attribute should represent the name of the publisher.
					image = document.getElementsByTagName("img")[0];
					publisher = image.getProperty("publisher");

					/*Resulting in:
					publisher[0].value = "http://individuals.example.com/JohnDoe"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=publisher

  • Response (JSON format): "publisher" : ["http://individuals.example.com/JohnDoe"]

TargetAudience interface

TargetAudience interface is used as the specific return type of MediaResource.getProperty method which has "TargetAudience" as a value of propertyName parameter.

attribute DOMString issuer
This attribute identifies the issuer of the classification.
attribute DOMString classification
This attribute defines the actual classification.
attribute DOMString type
This attribute specifies the type of the classification, which can be filtered on in the getProperty operation. Possibilities include "Age group" and "Geographical".
					image = document.getElementsByTagName("img")[0];
					targetAudience = image.getProperty("targetaudience");

					/*Resulting in:
					targetAudience[0].issuer = "http://www.fosi.org/icra"
					targetAudience[0].classification = "no nudity"
					targetAudience[0].type = "Age Group"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=targetaudience

  • Response (JSON format): "targetaudience" : [http://www.fosi.org/icra,"no nudity", "Age Group"]

Fragments Properties

Fragments interface

Fragments interface is used as the specific return type of MediaResource.getProperty method which has "Fragments" as a value of propertyName parameter.

attribute DOMString role
This attribute holds the role of the fragment, which can be filtered on in the getProperty operation.
attribute DOMString id
This attribute identifies the fragment.
					movie = document.getElementsByTagName("movie")[0];
					fragments = movie.getProperty("fragments");

					/*Resulting in:
					fragments[0].role = "Person"
					fragments[0].id = "http://www.example.com/movie.mov#xywh=320,320,40,100"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=fragments

  • Response (JSON format): "fragments" : ["Person", "http://www.example.com/movie.mov#xywh=320,320,40,100"]

NamedFragments interface

NamedFragments interface is used as the specific return type of MediaResource.getProperty method which has "NamedFragments" as a value of propertyName parameter.

attribute DOMString name
This attribute specifies the name given to the fragment.
attribute DOMString id
This attribute identifies the fragment.
					image = document.getElementsByTagName("img")[0];
					namedFragments = image.getProperty("NamedFragments");

					/*Resulting in:
					namedFragments[0].name = "Joakim Söderberg"
					namedFragments[0].id = "http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG#xywh=1600,550,80,150"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=namedFragments

  • Response (JSON format): "namedfragments" : ["Joakim Söderberg", "http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626.JPG#xywh=1600,550,80,150"]

Technical Properties

FrameSize interface

FrameSize interface is used as the specific return type of MediaResource.getProperty method which has "FrameSize" as a value of propertyName parameter.

attribute unsigned long width
This attribute represents the width of the frame.
attribute unsigned long height
This attribute represents the height of the frame.
					image = document.getElementsByTagName("img")[0];
					frameSize = image.getProperty("framesize");

					/*Resulting in:
					frameSize[0].width = 3.072
					frameSize[0].height = 2.304
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=frameSize

  • Response (JSON format): "technical-properties" : [3.072, 2.304]

Compression interface

Compression interface is used as the specific return type of MediaResource.getProperty method which has "Compression" as a value of propertyName parameter.

attribute DOMString value
This attribute specifies the compression type as a plain string.
					video = document.getElementsByTagName("video")[0];
					compression = video.getProperty("compression");

					/*Resulting in:
					compression[0].value = "H.264/AVC"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=compression

  • Response (JSON format): "compression" : ["H.264/AVC"]

Duration interface

Duration interface is used as the specific return type of MediaResource.getProperty method which has "Duration" as a value of propertyName parameter.

attribute unsigned long value
This attribute should represent the duration (in secs).
					video = document.getElementsByTagName("video")[0];
					duration = video.getProperty("duration");

					/*Resulting in:
					duration[0].value = 3600
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=duration

  • Response (JSON format): "duration" : [3600]

Format interface

Format interface is used as the specific return type of MediaResource.getProperty method which has "Format" as a value of propertyName parameter.

attribute DOMString value
This attribute specifies the MIME type as a plain string.
					image = document.getElementsByTagName("img")[0];
					format = image.getProperty("format");

					/*Resulting in:
					format[0].value = "image/jpeg"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=format

  • Response (JSON format): "format" : ["image/jpeg"]

Samplingrate interface

Samplingrate interface is used as the specific return type of MediaResource.getProperty method which has "Samplingrate" as a value of propertyName parameter.

attribute unsigned long value
This attribute specifies the samplingrate (in Hz).
					audio = document.getElementsByTagName("audio")[0];
					samplingrate = audio.getProperty("samplingrate");

					/*Resulting in:
					samplingrate[0].value = 44100
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=samplingrate

  • Response (JSON format): "samplingrate" : [44100]

Framerate interface

Framerate interface is used as the specific return type of MediaResource.getProperty method which has "Framerate" as a value of propertyName parameter.

attribute float value
This attribute specifies the framerate (in fps).
					video = document.getElementsByTagName("video")[0];
					framerate = video.getProperty("framerate");

					/*Resulting in:
					framerate[0].value = 30
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=framerate

  • Response (JSON format): "framerate" : [30]

AverageBitrate interface

Should bitrate be a number? What about Variable Bit Rate? Or would we raise NoValue in that case?

AverageBitrate interface is used as the specific return type of MediaResource.getProperty method which has "AverageBitrate" as a value of propertyName parameter.

attribute float value
This attribute specifies the average bitrate (in kbps).

Example is as below:

					video = document.getElementsByTagName("video")[0];
					bitrate = video.getProperty("averagebitrate");

					/*Resulting in:
					bitrate[0].value = 45.06
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=averageBitrate

  • Response (JSON format): "bitrate" : [45.06]

NumTracks interface

NumTracks interface is used as the specific return type of MediaResource.getProperty method which has "NumTracks" as a value of propertyName parameter.

attribute unsigned short value
This attribute specifies the number of tracks.
attribute DOMString type
This attribute specifies the type of the tracks e.g., "Songs", "Data streams".
					video = document.getElementsByTagName("video")[0];
					numTracks = video.getProperty("NumTracks");

					/*Resulting in:
					numTracks[0].value = 2
					numTracks[0].type = "Data streams"
					*/

Usage as a service:

  • Request: http://example.com/my-media-resource/?ma-query=numtracks

  • Response (JSON format): "numtracks" : [2]

Security Considerations

It is required to be considered in the perspectives of developer, user and content’s provider. This will be revised with more security issues.

This specification defines a client-side API to access metadata information related to media resources on the Web. These APIs will provide the methods for getting metadata information which can be in one of different formats, either as separate document or embedded in media resources.

There are related activity and technical documents in W3C such as Policy Requirements [[POLICY-REQS]] in DAP WG, ODRL 1.1 [[ODRL11]], P3P 1.1 [[P3P11]] and PLING Wiki [[PLING-WIKI]].

Web IDL description for API

module mawg {
	interface MediaResource {

	  	//Media Resource context
	  	boolean selectMAResource(in DOMString mediaResource, in optional MetadataSource[] metadataSources );

	  	// Property Access
	  	MAObject[] getProperty(in DOMString propertyName, in optional DOMString fragment, in optional DOMString sourceFormat, in optional DOMString subtype,
	  			       in optional DOMString language );

	  	//Iterating
	  	DOMString[] getPropertyNamesWithValues(in optional DOMString sourceFormat,
	  						      in optional DOMString language, in optional DOMString fragment);
	  	DOMString[] getSourceFormatsWithValues(in optional DOMString language);
	  	DOMString getOriginalData(in DOMString sourceFormat);

	  	//Operation for retrieval of the reason of an error
	  	DOMString getDiagnosis();

	  };

	interface MetadataSource {
  		attribute DOMString metadataSource;
  		attribute DOMString sourceFormat;
  	};

	module returnValues {

		interface MAObject {
			attribute DOMString unstructuredValue;
	  		attribute DOMString uri;
			attribute DOMString sourceFormat;
			attribute DOMString fragmentIdentifier;
	  		attribute DOMString mappingType;
	  	};

		interface Language {
			attribute DOMString language;
			};


		interface UnsignedLongObject: MAObject {
			attribute unsigned long value;
	  	};

	  	interface UnsignedShortObject: MAObject {
			attribute unsigned short value;
	  	};

	  	interface FloatObject: MAObject {
			attribute float value;
	  	};

	  	interface Identifier: MAObject {
	  		attribute DOMString value;
	  		attribute DOMString type;
	  	};

	  	interface Title: MAObject, Language {
	  		attribute DOMString value;
	  		attribute DOMString type;
	  	};

	  	interface Language : MAObject {
			attribute DOMString value;
		};

		interface Locator : MAObject {
			attribute DOMString value;
		};

		interface Contributor: MAObject {
			attribute DOMString id;
			attribute DOMString role;
		};

		interface Creator : MAObject {
			attribute DOMString value;
		};

	  	interface Date: MAObject {
		  	attribute DOMString date;
		  	attribute DOMString type;
	  	};

	  	interface Location: MAObject, Language {
		  	attribute DOMString name;
		  	attribute Float longitude;
		  	attribute Float latitude;
		  	attribute Float altitiude;
		  	attribute DOMString system;
	  	};

		interface Description : MAObject, Language {
			attribute DOMString value;
		};
	  	
		interface Keyword : MAObject, Language {
			attribute DOMString value;
		};

		interface Genre : MAObject, Language {
			attribute DOMString value;
		};

		interface Rating: MAObject, Language {
	               	 attribute DOMString issuer;
			attribute short value;
			attribute short minimum;
			attribute short maximum;
			attribute DOMString context;
	  		attribute DOMString type;
		};

	  	interface Relation: MAObject, Language {
			attribute DOMString id;
			attribute DOMString relationship;
		};

	  	interface Copyright: MAObject, Language {
			attribute DOMString statement;
			attribute DOMString[] holder;
		};

		interface Policy: MAObject, Language {
			attribute DOMString statement;
			attribute DOMString link;		
			attribute DOMString organization;
			attribute DOMString type;
		};
		
		interface Publisher: MAObject {
			attribute DOMString value;
		};

	  	interface TargetAudience: MAObject, Language {
			attribute DOMString issuer;
			attribute DOMString classification;
		};

	  	interface Fragment: MAObject, Language {
			  attribute DOMString role;
			  attribute DOMString id;
		};

		interface NamedFragment: MAObject, Language {
			  attribute DOMString name;
			  attribute DOMString id;
		};

	  	interface FrameSize: MAObject {
			  attribute unsigned long width;
			  attribute unsigned long height;
		};
		
		interface Compression : MAObject, Language {
			attribute DOMString value;
		};
		
		interface Duration : MAObject {
			attribute unsigned long value;
		};
		
		interface Format : MAObject {
			attribute DOMString value;
		};

		interface Samplingrate : MAObject {
			attribute unsigned long value;
		};
		
		interface Framerate : MAObject {
			attribute float value;
		};

		interface AverageBitrate : MAObject {
			attribute float value;
		};
		
		interface NumTracks : MAObject {
			attribute unsigned short value;
			attribute DOMString type;
		};

	};
};

Acknowledgements

This document is the work of the W3C Media Annotations Working Group.

Members of the Working Group are (at the time of writing, and by alphabetical order): 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 (CWI), Vassilis Tzouvaras (K-Space), Davy Van Deursen (IBBT).

The people who have contributed to discussions on public-media-annotation@w3.org are also gratefully acknowledged.