Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines an API to access metadata information related to media resources on the Web. The overall purpose is to provide developers with a convenient access to metadata information stored in different metadata formats. The API provides means to access the set of metadata properties defined in the Ontology for Media Resources 1.0 specification. These properties are used as a pivot vocabulary in this API. The core of this specification is the definition of API interfaces for retrieving metadata information in synchronous and asynchronous. It also defines interfaces for structured return types along with the specification of the behavior of an API implementation.
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 third Last Call 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.
This document is based upon the API for Media Resources 1.0 Candidate Recommendation of 22 November 2011. Feedback received during that review resulted in clarifications and minor changes, and the mandatory synchronous mode changed to be optional. The asynchronous mode remains a MUST provide.
The Media Annotations Working Group believes that this specification addresses all Candidate Recommendation issues. The list of changes made since the Candidate Recommendation are highlighted in the LC3 Diff file.The W3C Membership and other interested parties are invited to review the document and send comments through 03 June 2013. The scope of comments is restricted to the changes introduced since the Candidate Recommendation. Comments must be sent to to public-media-annotation@w3.org mailing list (public archive). Use "[3rdLC Comment API]" in the subject line of your email.
The Working Group has adopted a public test suite and has produced an implementation report for this API for Media Resources 1.0, showing that the Candidate Recommendation exit criteria have been met and exceeded.
Therefore after this 3rd Last Call, the Media Annotations Working Group plans to publish this draft as a Proposed Recommendation.
Publication as a Last Call 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.
MediaResource
interface
AsyncMediaResource
interface
SyncMediaResource
interface
MediaAnnotation
interface
MetadataSource
interface
This specification defines an API to access metadata information related to media resources on the Web. The overall purpose is to provide developers with a convenient access to metadata information stored in different metadata formats. The core properties, defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY], will be used as a pivot vocabulary in this API. The description of relations between these core properties and the metadata formats in scope are documented in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY] in order to provide cross-community data integration. This API is described using the interface definition language Web IDL [WEBIDL]. The decision to use Web IDL, which offers bindings for ECMAScript and Java, is based on the Use Cases and Requirements for Ontology and API for Media Resources 1.0 [MEDIA-ANNOT-REQS].
This API defines interfaces that enables users/applications to consume metadata in an interoperable manner. Interoperability between metadata formats is ensured by the use of the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY] as pivot metadata format. This API offers operations to request particular metadata information represented in a certain metadata format related to media resources on the Web. Further it specifies the actual representation of the core properties and the behaviour of this API.
Refers to the formats in scope of the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].
Refers to the Formats out of scope of the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].
In this document the terms "Ontology", "Media Resource", "Property", "Mapping" and "Property value types" are to be interpreted as defined in Section 2 of the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].
In addition to sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The keywords must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
This section discusses different usage scenarios that led to design of the API. We consider two main scenarios, where this API be implemented and invoked:
in the User agent, or
as a client accessing Web Service.
In both client-only and client-server cases of the implementation, the media resources and/or the metadata sources are in many cases remote, and accessing the metadata sources. The API is by default specified as an asynchronous API, i.e., the calls are not blocking, but results (or errors) are returned using a callback mechanism. In order to better support the Web Service case, a synchronous mode is also defined. The synchronous mode is optional.
The two scenarios are shown in Figure 1.
This specification only defines the API for Media Resources. Other components depicted in Figure 1 (e.g., access/extraction/storage of metadata) are not covered.
In both scenarios, this API serves as a mediator between a client application and the actual metadata sources. Interoperability is ensured by defining i) operations for accessing the metadata information, ii) a common object structure and iii) API behaviour (e.g., status codes). Following this, an implementation has to implement this stack of components:
An implementation of the API for Media Resources (as defined in this document), which provides the actual GETTER methods for the properties.
An implementation of the mappings from a specific source format to the core properties. Here, the API for Media Resources 1.0 should use the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY], where applicable.
A format specific API to access the metadata. This can be an API for retrieving a metadata document describing a media resource (e.g. an XML parser and a set of XPath statements) or an extractor to read metadata embedded in the media resource (e.g. a library to read EXIF information from JPEG images). In order to define the context in which this API is applied, at least a unidirectional reference from the media resource to the metadata document or vice versa is needed. If this is not the case such a reference needs to be provided by the web application (scenario 1), web service (scenario 2) or media repository (scenario 2).
This API provides access to metadata information stored in different metadata formats. As such, different instances of the same property can exist.
This API defines a number of interfaces using [WEBIDL]. These can be grouped in the following categories:
Interfaces defining the actual retrieval operations for metadata,
called MediaResource
, and provided in both synchronous
and asynchronous versions (see Section 4.1,
Section 4.2 and Section
4.3)
Interfaces defining the data structure of response objects/metadata
annotations, called MediaAnnotation
(see Section
4.4 and Section 4.5)
An interfaces defining a data structure for metadata sources,
called MetadataSource
(see Section
4.6)
Next, the different interfaces and exposed operations (in case of the MediaResource
interfaces and its implementing interfaces) are discussed.
Implementations of this API must
support asynchronous mode of operation, may support the synchronous one and must support interfaces
defined in this document. Instead of exceptions, a status code
indicating the state of processing (see Section
4.7) is returned (in the synchronous API) or can be accessed (in
the asynchronous API) in case an error occurs.
Then, the interfaces for the return types, i.e., MediaAnnotation
and its specializations, and MetadataSource
are defined.
The IDL fragment in Appendix A of this specification must be interpreted as required for conforming IDL fragments, as described in the “Web IDL” specification. [WEBIDL]
MediaResource
interfaceThe MediaResource
interface is the core of this API and
provides operations to access the metadata properties of a specific
media resource. Here, a clear separation between asynchronous and
synchronous mode of operation has been achieved by defining two
implementing interfaces, the AsyncMediaResource
and the
SyncMediaResource
interface. Objects of these interfaces
will be created by calling createMediaResource
of the MediaResource
interface. The actual connection to a specified metadata source will
be created with the execution of the getMediaProperty
operation of AsyncMediaResource
or SyncMediaResource
interface.
interface MediaResource {
short getSupportedModes ();
MediaResource
createMediaResource (DOMString mediaResource, optional MetadataSource
[] metadataSources, optional short mode);
};
createMediaResource
AsyncMediaResource
or SyncMediaResource
interface. Further, it allows
to set the specific media resource and metadata sources to which
this API is applied.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mediaResource | DOMString |
✘ | ✘ | This attribute must set the specific media resource that should be processed by the API. |
metadataSources |
|
✘ | ✔ | This attribute should specify additional metadata sources. |
mode | short |
✘ | ✔ | This attribute should specify the
desired mode of operation. 1 for
asynchronous and 2 for synchronous
mode should be used. In the case the mode argument is omitted, and the implementation supports both modes, the asynchronous mode will be used. |
MediaResource
getSupportedModes
1
for
asynchronous, 2
for synchronous and 3
for both modes.
short
Example for getSupportedModes
:
ma = new MediaResource(); var mode = ma.getSupportedModes(); /** Resulting in: * { "supportedModes" : 3 } */
Example for createMediaResource
:
metadataSources = new MetadataSource[2]; metadataSources[0] = new MetadataSource( "http://www.w3.org/2008/WebVideo/Annotations/drafts/metadata_formats/DC_example1.xml","dc"); metadataSources[1] = new MetadataSource( "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG","exif"); mediaResource = new MediaResource(); if (mediaResource.getSupportedModes() == 1 || mediaResource.getSupportedModes() == 3) { aSyncObject = mediaResource.createMediaResource( "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG", metadataSources, 1); } else if (mediaResource.getSupportedModes() == 2 || mediaResource.getSupportedModes() == 3) { syncObject = mediaResource.createMediaResource( "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG", metadataSources, 2); }
AsyncMediaResource
interfaceThe AsyncMediaResource
interface provides a number of
operations that allow accessing the metadata of a media resource. This interface must be implemented.
Next, we give the Web IDL description of the AsyncMediaResource
interface and describe the different operations that are part of it.
The mediaResource
argument identifies the media resource, for which
the implementation of this API should try to find relevant metadata
sources. Optionally, references to metadata sources can be passed
using 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
).
In this section the MediaAnnotations
interface is used in the interface definitions. It serves as a
container to hold general values about properties enabling an
iteration over a set of different properties. Its definition can be
found in Section 4.4
interface AsyncMediaResource : MediaResource
{
void getMediaProperty (DOMString[] propertyNames, PropertyCallback
successCallback, ErrorCallback errorCallback,
optional DOMString fragment, optional DOMString sourceFormat, optional DOMString language);
void getOriginalMetadata (DOMString sourceFormat, MetadataCallback
successCallback, ErrorCallback errorCallback);
};
getMediaProperty
MediaAnnotation
interface, described in Section 4.4.
Depending on the requested property, the returned objects
implement a different subtypes (inheriting from the MediaAnnotation
interface). For example, requesting "title" gives back an array of
objects implementing the Title
interface, requesting
"creator" results in objects implementing the Creator
interface and so on. These interfaces are described in Section
4.5. An example can be found here.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
propertyNames | DOMString[] |
✘ | ✘ | This argument identifies an array containing the properties for which the values need to be retrieved. For an empty array all properties carrying values will be retrieved. Optional arguments allow refining the request. |
successCallback |
|
✘ | ✘ | This argument holds a callback object
for asynchronous requests to the property. The successCallback
object implements the PropertyCallback
interface and holds a handleEvent operation
that needs to be called once all data for the requested
property is gathered. This handleEvent
operation needs to be called with a new MediaAnnotation
array. |
errorCallback | ErrorCallback |
✘ | ✘ | This argument holds a callback object
for failure of asynchronous requests to the property. The
errorCallback object implements the ErrorCallback
interface and holds a handleEvent operation
that needs to be called if an attempt fails. This handleEvent
operation needs to be called with a new DOMString
representing the status code of the error (see Section
4.7 for details). |
fragment | DOMString |
✘ | ✔ | This argument contains a URI identifying the specific media fragment for which the metadata is requested. The URI must conform to the URI for Media Fragment [MEDIA-FRAGMENTS] specification. This parameter is optional. |
sourceFormat | DOMString |
✘ | ✔ | This argument identifies a specific metadata format. It should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]. If a metadata format is defined, only the metadata available in the corresponding metadata format are retrieved. This parameter is optional. |
language | DOMString |
✘ | ✔ | This argument allows to identify the language of the metadata. Values for the metadata will only be returned if it is available in the specified language. Recommended best practice is to use BCP 47 [BCP47]. This parameter is optional. |
void
getOriginalMetadata
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
sourceFormat | DOMString |
✘ | ✘ | This argument identifies a specific metadata format. It should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]. If a metadata format is defined, only the metadata available in the corresponding metadata format are retrieved. |
successCallback |
|
✘ | ✘ | This argument holds a callback object
for asynchronous requests for the original metadata. The successCallback
object implements the MetadataCallback
interface and holds a handleEvent operation
that needs to be called once all properties having values
are listed. This handleEvent operation needs
to be called with a new DOMString array holding the
original metadata. |
errorCallback | ErrorCallback |
✘ | ✘ | This argument holds a callback object
for failure of asynchronous requests for the original
metadata. The errorCallback object
implements the ErrorCallback interface and
holds a handleEvent operation that needs to
be called if an attempt fails. This handleEvent
operation needs to be called with a new DOMString
representing the status code of the error (see Section
4.7 for details). |
void
PropertyCallback
interfaceThe PropertyCallback
interface holds a handleEvent
operation that needs to be called once all data for the requested
property has been gathered.
interface PropertyCallback {
void handleEvent (MediaAnnotation
[] mediaAnnotations);
};
handleEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mediaAnnotations |
|
✘ | ✘ | This argument holds a list of
objects with values according to the requested
property. These objects implement the MediaAnnotation
interface, described in Section
4.4. Depending on the requested property, the
returned objects implement a different subtypes
(inheriting from the MediaAnnotation
interface). |
void
MetadataCallback
interfaceThe MetadataCallback
interface holds a handleEvent
operation that needs to be called once the requested metadata has
been gathered.
interface MetadataCallback {
void handleEvent (DOMString[] metadata);
};
handleEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
metadata | DOMString[] |
✘ | ✘ | This argument holds a list of DOMStrings representing the original metadata. Note that, multiple metadata instances can exist (e.g., one Dublin Core and one MPEG-7 document). |
void
Example for asynchronous getMediaProperty
:
aSyncMediaResource = mediaResource.createMediaResource("http://www.imdb.com/title/tt0133152/", new Array(), 1); aSyncMediaResource.getMediaProperty(["title"], successCallback, errorCallback, "", "", ""); function successCallback(MediaAnnotation[] mediaAnnotations) { ... } /** Resulting in: * [ { "Title" : { * "propertyName" : "title", * "value" : "Planet of the apes", * "language" : en-us", * ... * "statusCode" : 200 * } * }, * { "Title" : { * "propertyName" : "title", * "value" : "Monkey Planet", * "language" : en-us", * ..., * "statusCode" : 200 * } * }, * { ... * } ] */ function errorCallback(DOMString error) { ... } /** Resulting in: * { error: { "statusCode" : 200 } } */
Example for asynchronous getOriginalMetadata
:
aSyncMediaResource = mediaResource.createMediaResource( "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG", new Array(), 1); aSyncMediaResource.getOriginalMetadata("dc", successCallback, errorCallback); function successCallback(DOMString[] metadata) { ... } /** Resulting in: * [ { "statusCode" : 200 * }, * {"originalMetadata" : "<metadata xmlns='http://example.org/myapp/' * xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' * xsi:schemaLocation='http://example.org/myapp/ http://example.org/myapp/schema.xsd' * xmlns:dc='http://purl.org/dc/elements/1.1/'> * <dc:title>DC title</dc:title> * </metadata>" * } ] */ function errorCallback(DOMString error) { ... } /** Resulting in: * { error: { "statusCode" : 200 } } */
SyncMediaResource
interfaceThe SyncMediaResource
interface provides a number of
operations to access the metadata of a media resource. This interface may be implemented.
Next, we give
the Web IDL description of the SyncMediaResource
interface for synchronous requests and describe the different
operations that are part of it. The MediaResource
defines a constructor that can be called to construct the object based
on an identifier of the media resource and optionally some metadata
sources. The mediaResource
argument identifies the media resource, for
which the implementation of this API should try to find relevant
metadata sources. Optionally, references to metadata sources can be
passed using an array of objects, each implementing the MetadataSource
interface. This interface holds two attributes, namely an URI
identifying the metadata source (metadataSource
) and the
name of the actual metadata format (sourceFormat
). An
example, how to create this object can be found here.
interface SyncMediaResource : MediaResource
{
MediaAnnotation
[] getMediaProperty (DOMString[] propertyNames, optional DOMString fragment,
optional DOMString sourceFormat, optional DOMString language);
DOMString[] getOriginalMetadata (DOMString sourceFormat);
};
getMediaProperty
MediaAnnotation
interface (see Section
4.3). Depending on the requested property, the returned
objects implement a different subtypes (inheriting from the MediaAnnotation
interface). For example, requesting "title" gives back an array
of objects implementing the Title
interface,
requesting "creator" results in objects implementing the Creator
interface and so on. These subtypes are described in Section
4.4. The operation returns a MediaAnnotation
array holding the requested properties. If an error occurs during
retrieval, a MediaAnnotation
object with the
corresponding status code (e.g., 400, 404 or 415) will be
generated and inserted at the first position of the array. An
example can be found here.
In this section the MediaAnnotations
interface is used in the interface definitions. It serves as a
container to hold general values about properties enabling an
iteration over a set of different properties. Its explanation
can be found in Section 4.4
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
propertyNames | DOMString[] |
✘ | ✘ | This argument holds the requested properties as an array. If the array is empty, each property holding values will be returned. |
fragment | DOMString |
✘ | ✔ | This argument contains a URI identifying the specific media fragment for which the metadata is requested. The URI must conform to the URI for Media Fragment [MEDIA-FRAGMENTS] specification. This parameter is optional. |
sourceFormat | DOMString |
✘ | ✔ | This argument identifies a specific metadata format. It should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]. If a metadata format is defined, only the metadata available in the corresponding metadata format is retrieved. This parameter is optional. |
language | DOMString |
✘ | ✔ | This argument allows to identify the language of the metadata. Values for the metadata will only be returned if it is available in the specified language. Recommended best practice is to use BCP 47 [BCP47]. This parameter is optional. |
MediaAnnotation
[]
getOriginalMetadata
DOMString
array holding the
status code of the request at the first and the original metadata
at the second position. An example can be found here.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
sourceFormat | DOMString |
✘ | ✘ | This argument identifies a specific metadata format. It should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]. If a metadata format is defined, only the metadata available in the corresponding metadata format is retrieved. |
DOMString[]
The examples in this section use getMediaProperty()
to get an object implementing the MediaAnnotation
interface. The noErrorStatus
function ensures that no
error is present and the requested properties carry values.
We give some JavaScript examples on how to use the synchronous MediaResource
interface and it's operations.
Example for synchronous getMediaProperty
:
syncMediaResource = mediaResource.createMediaResource("http://www.imdb.com/title/tt0133152/", new Array(), 2); title = syncMediaResource.getMediaProperty(["title"], "", "", ""); if (noErrorStatus(title[0].statusCode) == true) { ... } /** Resulting in: * [ { "Title" : { * "propertyName" : "title", * "value" : "Planet of the apes", * "language" : en-us", * ..., * "statusCode" : 200 * } * }, * { "Title" : { * "propertyName" : "title", * "value" : "Planet der Affen", * "language" : "de-de", * ..., * "statusCode" : 200 * } * }, * { ... * } ] */
Example for synchronous getOriginalMetadata
:
syncMediaResource = mediaResource.createMediaResource("http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG", new Array(), 2); dcMetadata = syncMediaResource.getOriginalMetadata("DC"); if (noErrorStatus(dcMetadata[0].statusCode) == true) { ... } /** Resulting in: * [ { "statusCode" : 200 * }, * {"originalMetadata" : "<metadata xmlns='http://example.org/myapp/' * xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' * xsi:schemaLocation='http://example.org/myapp/ http://example.org/myapp/schema.xsd' * xmlns:dc='http://purl.org/dc/elements/1.1/'> * <dc:title>DC title</dc:title> * </metadata>" * } ] */
MediaAnnotation
interfaceMediaAnnotation
interface is used as the return type of
MediaResource.getMediaProperty
operation. It is a
container for holding general values about properties enabling an
iteration over a set of different properties.
As several properties are complex types, specific derived types of MediaAnnotation
have been defined, added these properties with the appropriate types.
However, MediaAnnotation
can be used as a generic return
type to access a printable string representation of the property (in
the value
attribute). It also includes a status code. In
case of general errors, the first element of the returned MediaAnnotation
array contains the global error code, otherwise the status can be
given for each of the returned properties.
The following design considerations have been used for specifying the derived types for each of the properties:
MediaAnnotation
,
adding typed attributes according to the specification in the
ontology document.value
with a printable string representation, it is recommended to follow
these steps:
value
a string
that is found in another attribute. This is considered an acceptable
amount of redundancy for the benefit of having a generic value field
for all properties that can be used regardless of the specific
property and data type of the attributes.URI|string
, the interface
shall have two attributes, one with "Link" and one with "Label"
appended to the attribute name, representing the URI and string
respectivelyMediaAnnotation
or one of the derived interfaces for one of the properties.interface MediaAnnotation {
attribute DOMString propertyName;
attribute DOMString value;
attribute DOMString language;
attribute DOMString sourceFormat;
attribute DOMString fragmentIdentifier;
attribute DOMString mappingType;
attribute short statusCode;
};
fragmentIdentifier
of type DOMStringlanguage
of type
DOMStringmappingType
of type DOMStringpropertyName
of type DOMStringsourceFormat
of type DOMStringstatusCode
of
type shortvalue
of type DOMStringThe noErrorStatus
function ensures that
no error is present and the requested properties carry values. The MediaAnnotation
interface will be never instantiated - only the implementing
subtypes will be created. These must
be filled at least with the parameters specified in the MediaAnnotation
interface and may be filled
with the specific attributes.
mediaAnnotation = image.getMediaProperty(["title"], "", "", ""); if (noErrorStatus(mediaAnnotation[0].statusCode) == true) { ... } /** Resulting in: * [ { "Title" : { * "propertyName" : "title", * "value" : "Gone with the Wind", * "language" : "en-us", * "sourceFormat" : "mpeg7", * "fragmentIdentifier" : "http://www.example.com/video.ogv#t=10,20", * "mappingType" : "Exact match", * "statusCode" : 200 * } * } ]
This section describes the different properties that can be requested
through the MediaResource.getMediaProperty()
operation.
When invoking this operation, objects implementing the MediaAnnotation
interface are returned that represent the specified property. All
properties are represented with an interface inherited from the MediaAnnotation
interface (following the design guidelines described above).
Several of the following return type interfaces can hold the value of the property as both URI (i.e., a pointer to a controlled vocabulary) or as free text. The URI is preferred, and the respective attribute of the return value shall be filled whenever possible (i.e., when the information is included in or can be constructed from the source metadata).
In the following, for each property, a (synchronous)
JavaScript example illustrates the usage of the property specific
attributes. In any case, the genereal attributes of the MediaAnnotation
interface could be also requested.
When the MediaResource.getMediaProperty
operation
is invoked with "identifier" as a value of the propertyName
parameter, an object implementing the Identifier
interface is returned representing the identifier property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].
interface Identifier : MediaAnnotation
{
attribute DOMString identifierLink;
};
identifierLink
of type DOMStringid = image.getMediaProperty(["identifier"]); /** Resulting in: * [ { "Identifier" : { * "propertyName" : "identifier", * "identifierLink" : "urn:uuid:36a87260-1102-11df-8a39-0800200c9a66", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "title" as a value of the propertyName
parameter, an object implementing the Title
interface is returned representing the title property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].
interface Title : MediaAnnotation
{
attribute DOMString titleLabel;
attribute DOMString typeLink;
attribute DOMString typeLabel;
};
title = song.getMediaProperty(["title"]); /** Resulting in: * [ { "Title" : { * "propertyName" : "title", * "titleLabel" : "Artificial Horizon" , * "typeLink" : "http://www.ebu.ch/metadata/cs/ebu_ObjectTypeCodeCS.xml#21", * "typeLabel" : "Album title", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "language" as a value of the propertyName
parameter, an object implementing the Language
interface is returned representing the language property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].
interface Language : MediaAnnotation
{
attribute DOMString languageLink;
attribute DOMString languageLabel;
};
languageLabel
of type DOMStringgetMediaProperty
operation. Recommended best practice is to use BCP 47 [BCP47].
languageLink
of
type DOMStringlanguage = video.getMediaProperty(["language"]); /** Resulting in: * [ { "Language" : { * "propertyName" : "language", * "languageLabel" : "en-us", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "locator" as a value of the propertyName
parameter, an object implementing the Locator
interface is returned representing the locator property
(defined inthe Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].
interface Locator : MediaAnnotation
{
attribute DOMString locatorLink;
};
locatorLink
of
type DOMStringlocator = image.getMediaProperty(["locator"]); /** Resulting in: * [ { "Locator" : { * "propertyName" : "locator", * "locatorLink" : "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "contributor" as a value of the propertyName
parameter, an object implementing the Contributor
interface is returned representing the contributor
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY].
interface Contributor : MediaAnnotation
{
attribute DOMString contributorLink;
attribute DOMString contributorLabel;
attribute DOMString roleLink;
attribute DOMString roleLabel;
};
contributorLabel
of type DOMStringcontributorLink
of type DOMStringroleLabel
of
type DOMStringroleLink
of type
DOMStringcontributor = video.getMediaProperty(["contributor"]); /** Resulting in: * [ { "Contributor" : { * "propertyName" : "contributor", * "contributorLink" : "http://en.wikipedia.org/wiki/Tim_Burton", * "contributorLabel" : "Tim Burton", * "roleLink" : "http://www.imdb.com/name/nm0000318/", * "roleLabel" : "director", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "creator" as a value of the propertyName
parameter, an object implementing the Creator
interface is returned representing the creator property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY].
interface Creator : MediaAnnotation
{
attribute DOMString creatorLink;
attribute DOMString creatorLabel;
attribute DOMString roleLink;
attribute DOMString roleLabel;
};
creatorLabel
of
type DOMStringcreatorLink
of
type DOMStringroleLabel
of type DOMStringroleLink
of type DOMStringcreator = video.getMediaProperty(["creator"]); /** Resulting in: * [ { "Creator" : { * "propertyName" : "creator", * "creatorLink" : "http://dbpedia.org/resource/William_Shakespeare", * "creatorLabel" : "William Shakespeare", * "roleLink" : "http://www.ebu.ch/metadata/cs/ebu_RoleCodeCS.xml#22.5", * "roleLabel" : "playwright", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "date" as a value of the propertyName
parameter, an object implementing the Date
interface
is returned representing the date property (defined in the
Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
This
property has been renamed from "Date" into "MADate" in order to
avoid naming conflicts is possible in web applications.
interface MADate : MediaAnnotation
{
attribute DOMString date;
attribute DOMString typeLink;
attribute DOMString typeLabel;
};
date
of type DOMStringtypeLabel
of type DOMStringtypeLink
of type DOMStringmaDate = video.getMediaProperty(["date"]); /** Resulting in: * [ { "MADate" : { * "propertyName" : "date", * "date": "2009-06-26T15:30:00", * "typeLink" : "urn:smpte:ul:06.0E.2B.34.01.01.01.02.07.02.01.10.02.03.00.00", * "typeLabel" : "modification date", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "location" as a value of the propertyName
parameter, an object implementing the Location
interface is returned representing the location property
(defined inthe Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Location : MediaAnnotation
{
attribute DOMString locationLink;
attribute DOMString locationLabel;
attribute double longitude;
attribute double latitude;
attribute double altitude;
attribute DOMString coordinateSystemLabel;
attribute DOMString coordinateSystemLink;
};
altitude
of type doublecoordiateSystem
attribute (default is WGS84).
coordinateSystemLabel
of type DOMStringcoordinateSystemLink
of type DOMStringlatitude
of type doublecoordiateSystem
attribute (default is WGS84).
locationLabel
of type DOMStringlocationLink
of
type DOMStringlongitude
of type
doublecoordiateSystem
attribute (default is WGS84).
location = video.getMediaProperty(["location"]); /** Resulting in: * [ { "Location" : { * "propertyName" : "location", * "locationLink" : "http://en.wikipedia.org/wiki/San_Jose,_California", * "locationLabel" : "San Jose", * "longitude" : 37.33986481118008, * "latitude" : -121.88507080078125, * "altitude" : 0, * "coordinateSystemLabel" : "WGS84", * "coordinateSystemLink" : "http://www.w3.org/2003/01/geo/wgs84_pos#Point", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "description" as a value of the propertyName
parameter, an object implementing the Description
interface is returned representing the description
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).
interface Description : MediaAnnotation
{
attribute DOMString descriptionLabel;
};
descriptionLabel
of type DOMStringdescription = image.getMediaProperty(["description"]); /** Resulting in: * [ { "Description" : { * "propertyName" : "description", * "descriptionLabel" : "Group picture of the W3C MAWG at the F2F meeting in Stockholm.", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "keyword" as a value of the propertyName
parameter, an object implementing the Keyword
interface is returned representing the keyword property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Keyword : MediaAnnotation
{
attribute DOMString keywordLabel;
attribute DOMString keywordLink;
};
keyword = image.getMediaProperty(["keyword"]); /** Resulting in: * [ { "Keyword" : { * "propertyName" : "keyword", * "keywordLabel" : "meeting with people from outside the organisation", * "keywordLink" : "http://sw.opencyc.org/2008/06/10/concept/en/MeetingWithOrganizationalOutsiders", * "statusCode" : 200 * } * }, * { "Keyword" : { * "propertyName" : "keyword", * "keywordLabel" : "standardisation", * "keywordLink" : "http://purl.org/vocabularies/princeton/wn30/synset-standardization-noun-1", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "genre" as a value of the propertyName
parameter, an object implementing the Genre
interface is returned representing the genre property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Genre : MediaAnnotation
{
attribute DOMString genreLabel;
attribute DOMString genreLink;
};
genre = image.getMediaProperty(["genre"]); /** Resulting in: * [ { "Genre" : { * "propertyName" : "genre", * "genreLabel" : "Sports", * "genreLink" : "http://www.ebu.ch/metadata/cs/ebu_ContentGenreCS.xml#3.1.1.9" * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "rating" as a value of the propertyName
parameter, an object implementing the Rating
interface is returned representing the rating property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Rating : MediaAnnotation
{
attribute double ratingValue;
attribute DOMString ratingSystemLabel;
attribute DOMString ratingSystemLink;
attribute double minimum;
attribute double maximum;
};
maximum
of type doubleminimum
of type doubleratingSystemLabel
of type DOMStringratingSystemLink
of type DOMStringratingValue
of
type doublerating = image.getMediaProperty(["rating"]); /** Resulting in: * [ { "Rating" : { * "propertyName" : "rating", * "ratingValue" : 10.0, * "ratingSystemLabel" : "John Doe", * "ratingSystemLink" : "http://individuals.example.com/JohnDoe", * "minimum" : 0, * "maximum" : 10.0, * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "relation" as a value of the propertyName
parameter, an object implementing the Relation
interface is returned representing the relation property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Relation : MediaAnnotation
{
attribute DOMString targetLink;
attribute DOMString targetLabel;
attribute DOMString typeLink;
attribute DOMString typeLabel;
};
targetLabel
of
type DOMStringtargetLink
of
type DOMStringtypeLabel
of type
DOMStringtypeLink
of type DOMStringrelation = image.getMediaProperty(["relation"]); /** Resulting in: * [ { "Relation" : { * "propertyName" : "relation", * "targetLink" : "http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626_thumb.JPG", * "targetLabel" : "Group picture of MAWG in Stockholm", * "typeLink" : "http://www.ebu.ch/metadata/cs/ebu_HowRelatedCS.xml#19", * "typeLabel" : "thumbnail", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "collection" as a value of the propertyName
parameter, an object implementing the Collection
interface is returned representing the collection property
(defined inthe Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Collection : MediaAnnotation
{
attribute DOMString collectionLink;
attribute DOMString collectionLabel;
};
collectionLabel
of type DOMStringcollectionLink
of type DOMStringcollection = image.getMediaProperty(["collection"]); /** Resulting in: * [ { "Collection" : { * "propertyName" : "collection", * "collectionLink" : "http://individuals.example.com/JohnDoe/myWorkPictures/", * "collectionLabel" : "My Work Pictures", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "copyright" as a value of the propertyName
parameter, an object implementing the Copyright
interface is returned representing the copyright property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Copyright : MediaAnnotation
{
attribute DOMString copyrightLabel;
attribute DOMString holderLabel;
attribute DOMString holderLink;
};
copyrightLabel
of type DOMStringholderLabel
of
type DOMStringholderLink
of
type DOMStringcopyright = image.getMediaProperty(["copyright"]); /** Resulting in: * [ { "Copyright" : { * "propertyName" : "copyright", * "copyrightLabel" : "All images in the collection are copyrighted by John Doe.", * "holderLabel" : "John Doe", * "holderLink" : "http://individuals.example.com/JohnDoe", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "policy" as a value of the propertyName
parameter, an object implementing the Policy
interface is returned representing the policy property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Policy : MediaAnnotation
{
attribute DOMString statementLink;
attribute DOMString statementLabel;
attribute DOMString typeLink;
attribute DOMString typeLabel;
};
statementLabel
of type DOMStringstatementLink
of
type DOMStringtypeLabel
of type DOMStringtypeLink
of type DOMStringpolicy = image.getMediaProperty(["policy"]); /** Resulting in: * [ { "Policy" : { * "propertyName" : "policy", * "statementLink" : "http://creativecommons.org/licenses/by/2.5/", * "statementLabel" : "Attribution 2.5 Generic (CC BY 2.5)", * "typeLabel" : "license", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "publisher" as a value of the propertyName
parameter, an object implementing the Publisher
interface is returned representing the publisher property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Publisher : MediaAnnotation
{
attribute DOMString publisherLink;
attribute DOMString publisherLabel;
};
publisher = image.getMediaProperty(["publisher"]); /** Resulting in: * [ { "Publisher" : { * "propertyName" : "publisher", * "publisherLabel" : "ACME", * "publisherLink" : "http://company.example.com/ACME", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "targetAudience" as a value of the propertyName
parameter, an object implementing the TargetAudience
interface is returned representing the targetAudience
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).
interface TargetAudience : MediaAnnotation
{
attribute DOMString audienceLink;
attribute DOMString audienceLabel;
attribute DOMString classificationSystemLink;
attribute DOMString classificationSystemLabel;
};
audienceLabel
of type DOMStringaudienceLink
of type DOMStringclassificationSystemLabel
of type DOMStringclassificationSystemLink
of type DOMStringtargetAudience = image.getMediaProperty(["targetAudience"]); /** Resulting in: * [ { "TargetAudience" : { * "propertyName" : "targetAudience", * "audienceLink" : "http://www.mpaa.org/ratings/what-each-rating-means#NC-17", * "audienceLabel" : "No One 17 and Under Admitted", * "classificationSystemLink" : "http://www.mpaa.org/ratings", * "classificationSystemLabel" : "MPAA", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "fragment" as a value of the propertyName
parameter, an object implementing the Fragment
interface is returned representing the fragment property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Fragment : MediaAnnotation
{
attribute DOMString identifier;
attribute DOMString roleLink;
attribute DOMString roleLabel;
};
identifier
of
type DOMStringroleLabel
of type
DOMStringgetMediaProperty
operation.
roleLink
of type DOMStringgetMediaProperty
operation.
fragment = movie.getMediaProperty(["fragment"]); /** Resulting in: * [ { "Fragment" : { * "propertyName" : "fragment", * "identifier" : "http://www.example.com/video.ogv#t=10,20", * "roleLabel" : "chapter", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "namedFragment" as a value of the propertyName
parameter, an object implementing the NamedFragment
interface is returned representing the namedFragment
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).
interface NamedFragment : MediaAnnotation
{
attribute DOMString identifier;
attribute DOMString label;
};
namedFragment = movie.getMediaProperty(["namedFragment"]); /** Resulting in: * [ { "NamedFragment" : { * "propertyName" : "namedFragment", * "identifier" : "http://www.example.com/video.ogv#t=30,35", * "label" : "kissScene", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "frameSize" as a value of the propertyName
parameter, an object implementing the FrameSize
interface is returned representing the frameSize property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface FrameSize : MediaAnnotation
{
attribute double width;
attribute double height;
attribute DOMString unit;
};
height
of type doubleunit
of type DOMStringwidth
of type doubleframeSize = image.getMediaProperty(["frameSize"]); /** Resulting in: * [ { "FrameSize" : { * "propertyName" : "framesize", * "width" : 3072, * "height" : 2304, * "unit" : "pixels", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "compression" as a value of the propertyName
parameter, an object implementing the Compression
interface is returned representing the compression
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).
interface FrameSize : MediaAnnotation
{
attribute DOMString compressionLink;
attribute DOMString compressionLabel;
};
compression = video.getMediaProperty(["compression"]); /** Resulting in: * [ { "Compression" : { * "propertyName" : "compression", * "compressionLabel" : "H.264/AVC", * "compressionLink" : "urn:example-org:codingnames2010#ITU-H264", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "duration" as a value of the propertyName
parameter, an object implementing the Duration
interface is returned representing the duration property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Duration : MediaAnnotation
{
attribute double duration;
};
duration
of type doubleduration = video.getMediaProperty(["duration"]); /** Resulting in: * [ { "Duration" : { * "propertyName" : "duration", * "duration" : 3600, * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "format" as a value of the propertyName
parameter, an object implementing the Format
interface is returned representing the format property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface Format : MediaAnnotation
{
attribute DOMString formatLink;
attribute DOMString formatLabel;
};
format = image.getMediaProperty(["format"]); /** Resulting in: * [ { "Format" : { * "propertyName" : "format", * "formatLabel" : "image/jpeg", * "formatLink" : "http://dbpedia.org/resource/JPEG", * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "samplingRate" as a value of the propertyName
parameter, an object implementing the SamplingRate
interface is returned representing the samplingRate
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).
interface SamplingRate : MediaAnnotation
{
attribute double samplingRate;
};
samplingRate
of type doublesamplingrate = audio.getMediaProperty(["samplingRate"]); /** Resulting in: * [ { "SamplingRate" : { * "propertyName" : "samplingRate", * "samplingRate" : 44100, * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "frameRate" as a value of the propertyName
parameter, an object implementing the FrameRate
interface is returned representing the frameRate property
(defined inthe Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface FrameRate : MediaAnnotation
{
attribute double frameRate;
};
frameRate
of type
doubleframerate = video.getMediaProperty(["frameRate"]); /** Resulting in: * [ { "FrameRate" : { * "propertyName" : "frameRate", * "frameRate" : 30, * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "averageBitRate" as a value of the propertyName
parameter, an object implementing the AverageBitRate
interface is returned representing the averageBitRate
property (defined in the Ontology for Media Resources 1.0
specification [MEDIA-ONTOLOGY]).
interface AverageBitRate : MediaAnnotation
{
attribute double averageBitRate;
};
averageBitRate
of type doublebitrate = video.getMediaProperty(["averageBitRate"]); /** Resulting in: * [ { "AverageBitRate" : { * "propertyName" : "averageBitRate", * "averageBitRate" : 45.06, * "statusCode" : 200 * } * } ] */
When the MediaResource.getMediaProperty
operation
is invoked with "numTracks" as a value of the propertyName
parameter, an object implementing the NumTracks
interface is returned representing the numTracks property
(defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]).
interface NumTracks : MediaAnnotation
{
attribute short number;
attribute DOMString typeString;
};
numTracks = video.getMediaProperty(["numTracks"]); /** Resulting in: * [ { "NumTracks" : { * "propertyName" : "numTracks", * "number" : 2, * "typeString" : "audio", * "statusCode" : 200 * } * } ] */
MetadataSource
interfaceMetadataSource
interface is used to identify other
metadata sources.
interface MetadataSource {
attribute DOMString metadataSource;
attribute DOMString sourceFormat;
};
metadataSource
of type DOMStringsourceFormat
of type DOMStringmetadataSources = new MetadataSource("http://www.w3.org/2008/WebVideo/Annotations/drafts/metadata_formats/DC_example1.xml","dc");
This section introduces a set of status codes for the defined API to indicate the system behavior. As described in section 4.4, the status code is returned as one of the attributes of the MediaAnnotation object returned by a method call to the API. These status codes are used on the API level, and applied to either client side or server side implementations.
Numerical Code | Textual Description | Example |
---|---|---|
200 | OK | property delivered correctly |
204 | No Content | property retrieved without content |
206 | Partial Content | only a subset of the available data stored in the result set |
400 | Bad Request | syntactical error |
404 | Not Found | the queries resource is not found |
415 | Unsupported Media Type | get duration call on an image data store |
462 | Property not defined in Source Format | location is not defined in MediaRSS |
500 | Internal Server Error | internal library (e.g., extractor) crashes |
562 | Property not supported | a subset of properties implemented |
This part illustrates some examples how to use this API using
JavaScript in actual implementations. Moreover, in these examples it
is assumed that the implementation of this API knows where to find the
metadata that corresponds to a specific media resource (if necessary
the location of the metadata can be configured by the use of the MetadataSource
interface). The implementation should provide the mappings
of different metadata formats to the core
properties of the Ontology for Media Resources 1.0 specification
[MEDIA-ONTOLOGY]).
//search the video array for the one with title "Apocalypse now" for (var i = 0; i < mediaResourceVideoArray.length; i++) { //request for the titles of the video, the variable "titles" //will be filled with an array of MediaAnnotation objects. titles = mediaResourceVideoArray[i].getMediaProperty(["title"], "", "", ""); //check if the request is finished correctly if (noErrorStatus(titles[0].statusCode) == true) { for (var j = 0; j < titles.length; j++) { //check if the title matches if (titles[j].titleLabel == "Apocalypse Now") { //request for the director of the video, the variable "results" //will be filled with an array of MediaAnnotation objects. tempResults = mediaResourceVideoArray[i].getMediaProperty(["contributor"], "", "", ""); for (var k = 0; k < tempResults.length; k++) { if (tempResults[i].roleLabel == "director") { result = tempResults[i]; break; } } } } } } /** Resulting in: * [ { "Contributor" : { * "propertyName" : "contributor", * "value" : "Francis Ford Coppola", * ..., * "statusCode" = 200 * } * } ] */
//get the id of the second song using the fragments property tracks = albumMediaResource.getMediaProperty(["fragment"], "", "", ""); trackIdentifier = tracks[1].identifier; //use this identifier to get the mediaResource object that represents the track mediaResource = new MediaResource(); if (mediaResource.getSupportedModes() == 2 || mediaResource.getSupportedModes() == 3) { syncMediaResource = mediaResource.createMediaResource(trackIdentifier, new Array(), 2); } //get the title of the track title = syncMediaResource.getMediaProperty(["title"], "", "", ""); /** Resulting in: * [ { "Title" : { * "propertyName" : "title", * "value" : "I Still Haven't Found What I'm Looking For", * ..., * "statusCode" = 200 * } * } ] */
genre = movie.getMediaProperty(["genre"], "", "", "en-us"); /** Resulting in: * [ { "Genre" : { * "propertyName" : "genre", * "value" : "Action", * ..., * "statusCode" = 200 * } * }, * { "Genre" : { * "propertyName" : "genre", * "value" : "Drama", * ..., * "statusCode" = 200 * } * }, * { ... * } ] */
This part illustrates how this API could be implemented using web services. Note that, Web IDL currently does not provide bindings for web services. The given examples correspond to the examples given in Section 4.5 for each property.
Request: http://example.com/my-media-resource/?getOriginalMetadata=DC
Response (JSON format):
[ { "statusCode" : "200" }, {"originalMetadata" : "<?xml version='1.0'?><metadata xmlns='http://example.org/myapp/' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://example.org/myapp/ http://example.org/myapp/schema.xsd' xmlns:dc='http://purl.org/dc/elements/1.1/'><dc:title>DC title</dc:title></metadata>"} ]
The following examples illustrate how to request values for the different properties.
Request: http://example.com/my-media-resource/?ma-query=identifier
Response (JSON format):
[ { "Identifier" : { "propertyName" : "identifier", "identifierLink" : "urn:uuid:36a87260-1102-11df-8a39-0800200c9a66", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=title
Response (JSON format):
[ { "Title" : { "propertyName" : "title", "value" : "Artificial Horizon", "typeLink" : "http://www.ebu.ch/metadata/cs/ebu_ObjectTypeCodeCS.xml#21", "typeLabel" : "Album title", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=language
Response (JSON format):
[ { "Language" : { "propertyName" : "language", "languageLabel" : "en-us", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=locator
Response (JSON format):
[ { "Locator" : { "propertyName" : "locator", "locatorLink" : "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=contributor
Response (JSON format):
[ { "Contributor" : { "propertyName" : "contributor", "contributorLink" : "http://en.wikipedia.org/wiki/Tim_Burton", "contributorLabel" : "Tim Burton", "roleLink" : "http://www.imdb.com/name/nm0000318/", "roleLabel" : "director", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=creator
Response (JSON format):
[ { "Creator" : { "propertyName" : "creator", "creatorLink" : "http://dbpedia.org/resource/William_Shakespeare", "creatorLabel" : "William Shakespeare", "roleLink" : "http://www.ebu.ch/metadata/cs/ebu_RoleCodeCS.xml#22.5", "roleLabel" : "playwright", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=date
Response (JSON format):
[ { "MADate" : { "propertyName" : "date", "date": "2009-06-26T15:30:00", "typeLink" : "urn:smpte:ul:06.0E.2B.34.01.01.01.02.07.02.01.10.02.03.00.00", "typeLabel" : "modification date", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=location
Response (JSON format):
[ { "Location" : { "propertyName" : "location", "locationLink" : "http://en.wikipedia.org/wiki/San_Jose,_California", "locationLabel" : "San Jose", "longitude" : 37.33986481118008, "latitude" : -121.88507080078125, "altitude" : 0, "coordinateSystemLabel" : "WGS84", "coordinateSystemLink" : "http://www.w3.org/2003/01/geo/wgs84_pos#Point", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=description
Response (JSON format):
[ { "Description" : { "propertyName" : "description", "descriptionLabel" : "Group picture of the W3C MAWG at the F2F meeting in Stockholm.", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=keyword
Response (JSON format):
[ { "Keyword" : { "propertyName" : "keyword", "keywordLabel" : "meeting with people from outside the organisation", "keywordLink" : "http://sw.opencyc.org/2008/06/10/concept/en/MeetingWithOrganizationalOutsiders", "statusCode" : 200 } }, { "Keyword" : { "propertyName" : "keyword", "keywordLabel" : "standardisation", "keywordLink" : "http://purl.org/vocabularies/princeton/wn30/synset-standardization-noun-1", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=genre
Response (JSON format):
[ { "Genre" : { "propertyName" : "genre", "genreLabel" : "Sports", "genreLink" : "http://www.ebu.ch/metadata/cs/ebu_ContentGenreCS.xml#3.1.1.9", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=rating
Response (JSON format):
[ { "Rating" : { "propertyName" : "rating", "ratingValue" : 10.0, "ratingSystemLabel" : "John Doe", "ratingSystemLink" : "http://individuals.example.com/JohnDoe", "minimum" : 0, "maximum" : 10.0, "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=relation
Response (JSON format):
[ { "Relation" : { "propertyName" : "relation", "targetLink" : "http://www.w3.org/2008/WebVideo/Annotations/wiki/Image:MAWG-Stockholm-20090626_thumb.JPG", "targetLabel" : "Group picture of MAWG in Stockholm", "typeLink" : "http://www.ebu.ch/metadata/cs/ebu_HowRelatedCS.xml#19", "typeLabel" : "thumbnail", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=collection
Response (JSON format):
[ { "Collection" : { "propertyName" : "collection", "collectionLink" : "http://individuals.example.com/JohnDoe/myWorkPictures/", "collectionLabel" : "My Work Pictures", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=copyright
Response (JSON format):
[ { "Copyright" : { "propertyName" : "copyright", "copyrightLabel" : "All images in the collection are copyrighted by John Doe.", "holderLabel" : "John Doe", "holderLink" : "http://individuals.example.com/JohnDoe", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=policy
Response (JSON format):
[ { "Policy" : { "propertyName" : "policy", "statementLink" : "http://creativecommons.org/licenses/by/2.5/", "statementLabel" : "Attribution 2.5 Generic (CC BY 2.5)", "typeLabel" : "license", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=publisher
Response (JSON format):
[ { "Publisher" : { "propertyName" : "publisher", "publisherLabel" : "ACME", "publisherLink" : "http://company.example.com/ACME", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=targetAudience
Response (JSON format):
[ { "TargetAudience" : { "propertyName" : "targetAudience", "audienceLink" : "http://www.mpaa.org/ratings/what-each-rating-means#NC-17", "audienceLabel" : "No One 17 and Under Admitted", "classificationSystemLink" : "http://www.mpaa.org/ratings", "classificationSystemLabel" : "MPAA", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=fragment
Response (JSON format):
[ { "Fragment" : { "propertyName" : "fragment", "identifier" : "http://www.example.com/video.ogv#t=10,20", "roleLabel" : "chapter", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=namedFragment
Response (JSON format):
[ { "NamedFragment" : { "propertyName" : "namedFragment", "label" : "kissScene", "identifier" : "http://www.example.com/video.ogv#t=30,35", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=frameSize
Response (JSON format):
[ { "FrameSize" : { "propertyName" : "framesize", "width" : 3072, "height" : 2304, "unit" : "pixels", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=compression
Response (JSON format):
[ { "Compression" : { "propertyName" : "compression", "compressionLabel" : "H.264/AVC", "urn:example-org:codingnames2010#ITU-H264", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=duration
Response (JSON format):
[ { "Duration" : { "propertyName" : "duration", "duration" : 3600, "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=format
Response (JSON format):
[ { "Format" : { "propertyName" : "format", "formatLabel" : "image/jpeg", "formatLink" : "http://dbpedia.org/resource/JPEG", "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=samplingRate
Response (JSON format):
[ { "SamplingRate" : { "propertyName" : "samplingRate", "samplingRate" : 44100, "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=frameRate
Response (JSON format):
[ { "FrameRate" : { "propertyName" : "frameRate", "frameRate" : 30, "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=averageBitRate
Response (JSON format):
[ { "AverageBitRate" : { "propertyName" : "averageBitRate", "averageBitRate" : 45.06, "statusCode" : 200 } } ]
Request: http://example.com/my-media-resource/?ma-query=numTracks
Response (JSON format):
[ { "NumTracks" : { "propertyName" : "numTracks", "number" : 2, "typeString" : "audio", "statusCode" : 200 } } ]
This section contains recommendations for implementators for handling missing or multiple identifiers of media resources/fragments.
In some source formats, it could be possible to identify the resource or one of its fragments in multiple ways, e.g. by one or more identifiers, fragment name or temporal/spatial fragment URIs. For example, there could be a temporal media fragment, which can be addressed by the time range, that also has an assigned ID.
In the RDF representation of the Ontology for Media Resources, this can be represented (as recommended in the guidelines) by using owl:sameAs. To ensure a similar behaviour in the API, an implementation SHOULD return all such identifiers in a response. If queries to properties of a fragment with multiple are made, the implementation SHOULD accept each of the alternative identifiers and return the same response for each of them.
There are source formats, which may contain metadata about a fragment (e.g. a track) without specifying any kind of identifier for it. For the RDF representation this is not a problem, as blank nodes can be used. In an API implementation, a client requesting the list of fragments cannot query properties of a fragment in case there is no identifier.
An implementation SHOULD generate an identifier for the fragment in such a case and SHOULD ensure that it is valid for a sufficiently long time so that the client can use it in subsequent queries to properties of fragments. The identifier is not guaranteed to remain permanently valid.
This can be implemented in different ways, including the following:
The API can be implemented in two different modes. The asynchronous mode is mandatory while the synchrounous one is optional. In same cases, interoperability between these modes is desired, for example to access a Web Service by asynchronous calls.
An implementation of the optional synchronous mode of the API (e.g. in a Web Service) is turned into the mandatory asynchronous communication by a wrapper.
Therefore the required wrapper functionality is implemented in JavaScript using the Web Workers specification [WEBWORKERS] processing non-blocking scripts.
A demo of the wrapper code can be downloaded from [MAWG-REPO].
First, the existing operations of the MediaResource interface are adapted in order to support the synchronous as well as asynchronous mode (mawg_api.js
).
Then, the implementation of the AsyncMediaResource interface wrapping the synchronous communication is added.
Therefore, the two operations of the AsyncMediaResource interface (getMediaProperty
and getOriginalMetadata
) refer to the corresponding synchronous calls by Web Workers (media_property_worker.js
, media_property_worker.js
).
Finally, the result of the synchronous communication is pushed forward to the synchronous operation by invoking a callback function.
Wrapping an asynchronous implementation by an synchronous call is infeasible in JavaScript since threads cannot be suspended and interact with concurrent ones. Nonetheless, another programming language (e.g. Java), can be used to warp asynchronous API calls in web service calls.
This specification defines a API to access metadata information related to media resources on the Web. These APIs will provide means for requesting metadata information, which can already be accessed in one or different formats, either as separate document or embedded in media resources. As such, this API introduces no additional security issue.
One should nevertheless note that some metadata could be used to access personal information about someone without declaration of agreement. For example, temporal and geographic information about a media resource could indirectly provide information about its creator.
There are related activities and technical documents in W3C working on this topics, such as Policy Requirements [POLICY-REQS] in DAP WG, ODRL 1.1 [ODRL11], P3P 1.1 [P3P11] and PLING Wiki [PLING-WIKI].
Follow this link to download the WebIDL description as IDL file.
interface MediaResource { short getSupportedModes(); MediaResource createMediaResource(DOMString mediaResource, optional MetadataSource[] metadataSources, optional short mode); }; interface AsyncMediaResource : MediaResource { void getMediaProperty(DOMString[] propertyNames, PropertyCallback successCallback, ErrorCallback errorCallback, optional DOMString fragment, optional DOMString sourceFormat, optional DOMString language ); void getOriginalMetadata (DOMString sourceFormat, MetadataCallback successCallback, ErrorCallback errorCallback); }; interface PropertyCallback { void handleEvent (MediaAnnotation[] mediaAnnotations); }; interface MetadataCallback { void handleEvent (DOMString[] metadata); }; interface ErrorCallback { void handleEvent (DOMString errorStatus); }; interface SyncMediaResource : MediaResource { MediaAnnotation[] getMediaProperty(DOMString[] propertyNames, optional DOMString fragment, optional DOMString sourceFormat, optional DOMString language); DOMString[] getOriginalMetadata (DOMString sourceFormat); }; interface MetadataSource { attribute DOMString metadataSource; attribute DOMString sourceFormat; }; interface MediaAnnotation { attribute DOMString propertyName; attribute DOMString value; attribute DOMString language; attribute DOMString sourceFormat; attribute DOMString fragmentIdentifier; attribute DOMString mappingType; attribute short statusCode; }; interface Identifier : MediaAnnotation { attribute DOMString identifierLink; }; interface Title : MediaAnnotation { attribute DOMString titleLabel; attribute DOMString typeLink; attribute DOMString typeLabel; }; interface Language : MediaAnnotation { attribute DOMString languageLink; attribute DOMString languageLabel; }; interface Locator : MediaAnnotation { attribute DOMString locatorLink; }; interface Contributor : MediaAnnotation { attribute DOMString contributorLink; attribute DOMString contributorLabel; attribute DOMString roleLink; attribute DOMString roleLabel; }; interface Creator : MediaAnnotation { attribute DOMString creatorLink; attribute DOMString creatorLabel; attribute DOMString roleLink; attribute DOMString roleLabel; }; interface MADate : MediaAnnotation { attribute DOMString date; attribute DOMString typeLink; attribute DOMString typeLabel; }; interface Location : MediaAnnotation { attribute DOMString locationLink; attribute DOMString locationLabel; attribute double longitude; attribute double latitude; attribute double altitude; attribute DOMString coordinateSystemLabel; attribute DOMString coordinateSystemLink; }; interface Description : MediaAnnotation { attribute DOMString descriptionLabel; }; interface Keyword : MediaAnnotation { attribute DOMString keywordLink; attribute DOMString keywordLabel; }; interface Genre : MediaAnnotation { attribute DOMString genreLink; attribute DOMString genreLabel; }; interface Rating : MediaAnnotation { attribute double ratingValue; attribute DOMString ratingSystemLink; attribute DOMString ratingSystemLabel; attribute double min; attribute double max; }; interface Relation : MediaAnnotation { attribute DOMString targetLink; attribute DOMString targetLabel; attribute DOMString typeLink; attribute DOMString typeLabel; }; interface Collection : MediaAnnotation { attribute DOMString collectionLink; attribute DOMString collectionLabel; }; interface Copyright : MediaAnnotation { attribute DOMString copyrightLabel; attribute DOMString holderLink; attribute DOMString holderLabel; }; interface Policy : MediaAnnotation { attribute DOMString statementLink; attribute DOMString statementLabel; attribute DOMString typeLink; attribute DOMString typeLabel; }; interface Publisher : MediaAnnotation { attribute DOMString publisherLink; attribute DOMString publisherLabel; }; interface TargetAudience : MediaAnnotation { attribute DOMString audienceLink; attribute DOMString audienceLabel; attribute DOMString classificationSystemLink; attribute DOMString classificationSystemLabel; }; interface Fragment : MediaAnnotation { attribute DOMString identifier; attribute DOMString roleLink; attribute DOMString roleLabel; }; interface NamedFragment : MediaAnnotation { attribute DOMString identifier; attribute DOMString label; }; interface FrameSize : MediaAnnotation { attribute double width; attribute double height; attribute DOMString unit; }; interface Compression : MediaAnnotation { attribute DOMString compressionLink; attribute DOMString compressionLabel; }; interface Duration : MediaAnnotation { attribute double duration; }; interface Format : MediaAnnotation { attribute DOMString formatLink; attribute DOMString formatLabel; }; interface SamplingRate : MediaAnnotation { attribute double samplingRate; }; interface FrameRate : MediaAnnotation { attribute double frameRate; }; interface AverageBitRate : MediaAnnotation { attribute double averageBitRate; }; interface NumTracks : MediaAnnotation { attribute short number; attribute DOMString typeString; };
Note: The following subsections lists all significant changes applied to the API for Media Resources 1.0 specification received in CR.
-- editorial changes ---
Note: The following subsections lists all significant changes applied to the API for Media Resources 1.0 specification received in LC.
-- General changes ---
---[LC 2406] 2001-09-10 ---
---[LC 2410] 2001-09-10 ---
---[LC 2419] 2001-09-10 ---
---[LC 2394] 2001-09-10 ---
The following subsection lists all significant changes applied to the API for Media Resources 1.0 specification. These have been decided during the 10th Face-to-face meeting hosted by Apple in Silicon Valley, Ca, USA.
The following subsection lists all significant changes applied to the API for Media Resources 1.0 specification. These have been decided during the 12th Face-to-face meeting hosted by JOANNEUM, Graz, Austria.
The following subsection lists all significant changes applied to the API for Media Resources 1.0 specification in preparation of the 3rd LC document.
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 (JOANNEUM RESEARCH), Tobias Bürger ((public) Invited expert), Eric Carlson (Apple, Inc.), Pierre-Antoine Champin (Université de Lyon), Ashish Chawla ((public) Invited expert), Jaime Delgado (Universitat Politècnica de Catalunya), Jean-Pierre Evain ((public) Invited expert), Martin Höffernig (JOANNEUM RESEARCH), Philip Jägenstedt (Opera Software), Ralf Klamma ((public) Invited expert), WonSuk Lee (Samsung Electronics Co., Ltd.), 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), Victor Rodríguez (Universitat Politècnica de Catalunya), Felix Sasaki (Potsdam University of Applied Sciences), David Singer (Apple, Inc.), Florian Stegmaier ((public) Invited expert), John Strassner ((public) Invited expert), Joakim Söderberg (ERICSSON), Mari Carmen Suárez-Figueroa ((public) Invited expert) 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.