Copyright
© 2010 2011
W3C ® (
MIT ,
ERCIM
, Keio ), All Rights Reserved.
W3C liability
, trademark
and document
use rules apply.
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 a second 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 .
The W3C Membership and other interested parties are invited to
review the document and send comments through 11 July 2010. 07 August
2011. Comments must be sent to to
public-media-annotation@w3.org mailing list ( public
archive ). Use "[LC "[2ndLC Comment API]" in the subject line of your
email.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
MediaResource
interface
MetadataSource AsyncMediaResource
interface
SyncMediaResource
interface
MAObject MediaAnnotation
interface
NumTracks MetadataSource
interface
This section is non-normative. This
specification defines a client-side
an 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 The
Media core properties
,defined in the Ontology Core Properties for Media
Resources 1.0 specification,
will be used as a pivot vocabulary in the this API. The
description of relations between these core properties and the
metadata formats in scope ( 1.2 Formats in scope ) are stored
documented in the Media Ontology for Media Resources 1.0 specification in order to provide cross-community
data integration. The 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, can be based on the Use
Cases and Requirements for Ontology and API for Media Resource Resources 1.0
[ MEDIA-ANNOT-REQS ]. This
document clearly states that the focus for this API lies on
multimedia services on the Web.
The This
API serves as a mediator defines/exposes interfaces that enables
users/applications to consume metadata in an interoperable manner.
Here, interoperability between a
developer and metadata formats is
ensured by the underlying
use of the Ontology for Media Resource Resources 1.0
[ MEDIA-ANNOT-ONTOLOGY ] with the goal to support interoperability
between as pivot metadata
formats. It format. This API offers operations to retrieve request
particular metadata informations
information represented in a certain
metadata format related to media resources on the Web. This document is being published with Further it specifies the aspiration to gather wide feedback on actual representation of the yet available API design.
core properties and the behaviour
of this API.
Refers to the formats in
scope of Ontology
for Media Resource Resources 1.0 .
Refers to the Formats
out of scope of Ontology for Media Resource Resources
1.0 .
In this document the terms "Ontology", "Media Resource", "Property",
"Mapping" and "Property value type"
types" are to be interpreted as defined
in Section
2 of Ontology for
Media Resource Resources 1.0 .
As well as 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 key words must ,must not ,required ,should ,should not ,recommended ,may ,and optional in this specification are to be interpreted as described in [ RFC2119 ].
Before introducing the two example usage scenarios of this API, two modes of operations must be defined: asynchronous and synchronous mode. For this API the asynchronous mode is considered to be used as default. Here, a request will be executed within a certain time period and then returned. In contrast to that, the synchronous mode implicates an immediate answer to every request.
We consider two scenarios
scenarios, where the this API could be
implemented: either in a user
User agent (scenario 1) or as a web service (scenario 2).
Web Service
The two scenarios are shown in the
figure. Figure
1.
Note: This specification only defines this 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 access to the actual
metadata properties needs sources. Interoperability is ensured by defining i)
operations for accessing the following metadata
information, ii) 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 Resource Resources (as
defined in this document), which providers provides the
actual getter methods for the properties.
An implementation of the mappings from a specific source format
to the properties of core properties. Here, the media ontology (as defined in API for Media Resources 1.0 may use the Ontology for Media Resource 1.0). Resources
1.0 specification.
A format specific API to access the metadata. This can be an API
for accessing 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 on in which the
this API for
Media Resource is working, it is assumed that there is
applied, at least a unidirectional
reference from the media resource to the metadata document or vice
versa. 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).
Note that, this API provides access to metadata information stored in different metadata formats. As such, different instances of the same property can exist.
The This
API exists of defines a number of interfaces, described interfaces using [
Web IDL WEBIDL . Implementations
of the API should provide objects implementing the different
interfaces. The entire description ]. These can be found
grouped in Appendix A . The API is contained within 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
)interface within
Interfaces defining the data structure of response objects/metadata annotations,
called mawg MediaAnnotationmodule. Objects implementing this interface provide the
necessary methods to access metadata properties of a Media
Resource. The object holds methods to identify the actual Media
Resource (see Section 4.4
and the metadata sources. All properties can
be accessed through a specific operation getProperty . When an
attempt to read a property fails, diagnostics information can be
obtained using Section 4.5 )
An interfaces defining a diagnosis operation. Subtypes in the API are
relevant data structure for
those properties mentioned in 4.1.3 Core
properties metadata sources,
called MetadataSource
(see Section 4.6 of Ontology
for Media Resource 1.0 . Lastly, methods are available that allow
to iterate through the available metadata. )
Next, the different interfaces and exposed methods operations (in case
of the MediaResource
interfaces and its implementing
interfaces) are discussed. Finally,
examples Implementations of
the usage this
API must support at least
one of the API versions and must support the other interfaces defined in this document.
We have not specified exceptions on the operations or on accessing
the attributes. Instead, a status code is returned (in the
synchronous API) or can be found
accessed (in the asynchronous API) in
section 4 . case
an error occurs indicating the state of processing (see
Section
4.7 ).
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 offers a number is the
core of this API and provides
operations that allow accessing
to access the metadata properties of a Media
Resource. Example on how to introduce this in HTML5
specific media resource. Here, a clear
separation between asynchronous and synchronous mode of operation
has been achieved by making the
HTMLMediaElement inherit from defining
two implementing interfaces, the MediaResource AsyncMediaResourceinterface: interface HTMLMediaElement : MediaResource ,
HTMLElement { ... } Example of usage in JavaScript: title ... As
shown, and the getElementsByTagName SyncMediaResourcereturns a interface. Objects
of these interfaces will be created by calling
HTMLMediaElement createMediaResourcewhich inherits from of
the MediaResource
interface. The getProperty method is part of this interface so
actual connection to a specified metadata
source will be created with the returned element has an implementation execution of this method. By
calling the getProperty
getMediaPropertymethod with the argument "title" we can retrieve the
title of the corresponding media resource. The JavaScript examples
in this section all assume that getElementsByTagName() returns an
object implementing the MediaResource interface. Next, we give the
Web IDL description operation of
the MediaResource AsyncMediaResourceinterface and describe the different operations that are
part of it. or SyncMediaResource
interface.
interface MediaResource {
short getSupportedModes ();
MediaResource
createMediaResource (in DOMString mediaResource, in optional MetadataSource
[] metadataSources,
in optional short mode);
};
getDiagnosis createMediaResource
DOMString
AsyncMediaResource
or getOriginalData SyncMediaResource
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
DOMString |
✘ | ✘ | This |
|
metadataSources |
|
✘ | ✔ | This attribute should
specify additional metadata |
mode | short |
✘ | ✔ | This 1 for
asynchronous and 2 for synchronous
mode should be used. |
DOMString MediaResource
[]
getProperty 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/wiki/MAWG-Stockholm-20090626.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. By calling the
getMediaProperty
operation with the argument "title" we
can retrieve the title of the
corresponding media resource.
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 explanation can be found in Section
4.4
interface AsyncMediaResource : MediaResource
{ void getMediaProperty (in DOMString[] propertyNames, in PropertyCallback
successCallback,
in ErrorCallback errorCallback, in optional DOMString fragment,
in optional DOMString sourceFormat, in optional DOMString language); void getOriginalMetadata (in DOMString sourceFormat, in MetadataCallback
successCallback,
in ErrorCallback errorCallback);
};
getMediaProperty
MAObject MediaAnnotation
interface, described in
MAObject MediaAnnotation
interface). Requesting
Title
interface, requesting
Creator
interface and so on. These
interfaces are described in Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
DOMString [] |
✘ | ✘ | This argument identifies an array containing the |
|
successCallback |
|
✘ | ✘ | This argument holds a
callback object for asynchronous requests to 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 |
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. If a metadata format is defined,
only the metadata available in the corresponding metadata format
are retrieved. This parameter is |
language | DOMString |
✘ | ✔ | This argument allows to identify the language
of the metadata. |
MAObject void
[]
getPropertyNamesWithValues
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. If a metadata format is defined,
only the metadata available in the corresponding metadata format
are retrieved. |
|
✘ | ✘ | This argument successCallback object implements the MetadataCallback interface and holds a handleEvent operation
that needs to be called once all properties having values are
handleEvent operation
needs to be called with a new DOMString array holding the original
metadata. |
|
|
✘ | ✘ | This argument 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). |
DOMString void
[]
getSourceFormatsWithValues
PropertyCallback
interfaceThe PropertyCallback
interface holds a handleEvent
This operation allows
that needs to retrieve be called
once all source formats
data for which
metadata is available. If this operation returns a source format,
this means that a call to the requested
property has been gathered.
interface PropertyCallback { void handleEvent (in MediaAnnotation
[] mediaAnnotations);
};
getProperty handleEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
|
✘ | ✘ | This argument MediaAnnotation interface, described in Section 4.4
.Depending on the MediaAnnotation interface). |
DOMString void
[]
selectMAResource MetadataCallback
interfaceThe MetadataCallback
interface holds a handleEvent
operation
that needs to be called once the requested metadata has been
gathered.
interface MetadataCallback { void handleEvent (in DOMString[] metadata);
};
handleEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
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" : 415 } } */
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" : 415 } } */
SyncMediaResource
interfaceThe SyncMediaResource
interface provides a number of operations to access the
metadata of a media resource. 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. The
media resource, for which the
implementation of the this API should try to find relevant metadata
sources. Optionally, references to
metadata sources for 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 Media
Resource object can be found
here .
interface SyncMediaResource : MediaResource
{ MediaAnnotation
[] getMediaProperty (in DOMString[] propertyNames,
in optional DOMString fragment, in optional DOMString sourceFormat, in optional DOMString language); DOMString[] getOriginalMetadata (in 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). 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 |
---|---|---|---|---|
DOMString [] |
✘ | ✘ | This argument holds the requested properties as an array. If the array is empty, each property holding values will be returned. | |
fragment |
|
✘ | ✔ | This argument contains a
URI identifying the specific media fragment for which the
metadata is |
sourceFormat | DOMString |
✘ | ✔ | This argument identifies
a specific metadata format. It should use the metadata
|
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. |
boolean MediaAnnotation
[]
MetadataSource getOriginalMetadata
MetadataSource DOMString
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
sourceFormat | |
✘ | ✘ | This argument identifies
a specific metadata format. It should use the metadata
|
sourceFormat of type
DOMString The name of the actual
metadata format. No exceptions. []
The examples in this section
use Language getMediaProperty()interface to get an object
implementing the Language
MediaAnnotationinterface interface.
The noErrorStatus
function ensures that no error is
used to identify present and the language
of requested properties carry
values.
We give some JavaScript examples on how to
use the metadata. 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"], "", "", "");3.3.1 Attributesif (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
:language of type 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");DOMStringif (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>" * } ] */This attribute holds the language of the metadata. No exceptions.
MAObject MediaAnnotation
interface
interface is used as the
return type of MAObject MediaAnnotationMediaResource.getProperty MediaResource.getMediaPropertymethod. This operation.
It is used a container to hold the general values
about properties enabling an iteration over a
set of the requested property.
different properties. Depending on the
requested property, this interface will be
enlarged by more specific attributes.
As several properties are complex types,
specific derived types of MediaAnnotation
have
been defined, added these objects
implement properties with the
appropriate types. However, MediaAnnotation
can
be used as a different interface.
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 DOMStringunstructuredValue statusCode
of type uri value
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"], "", "", "");3.5.1if (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
operation. When invoking this operation,
objects implementing the Identifier MediaResource.getMediaProperty()MediaAnnotation
interface are returned that represent the specified property. All
properties are represented with an interface inherited from
the
interface Identifier MediaAnnotationis used as (following
the specific design guidelines described above).
Several of the following return type
interfaces can hold the value of
MediaResource.getProperty method which has
"Identifier" 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
propertyName MediaAnnotationparameter. interface could
be also requested.
When the type MediaResource.getMediaPropertyof type DOMString This attribute holds the type
operation is invoked with "identifier" as a
value of the identifier, which can be
filtered on in propertyName
parameter, an object implementing the
getProperty Identifieroperation.
Possible values are " UMID" and "ISAN". No exceptions.
interface is returned representing the
identifier property (defined in the Ontology
for Media Resources 1.0 specification).
interface Identifier : MediaAnnotation
{ attribute DOMString identifierLink;
};
value identifierLink
of type DOMStringid = image.getMediaProperty(["identifier"]); /** Resulting in: * [ { "Identifier" : { * "propertyName" : "identifier", * "identifierLink" : "urn:uuid:36a87260-1102-11df-8a39-0800200c9a66", * "statusCode" : 200 * } * } ] */
Title interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Title" operation is invoked with "title" as a value of
the propertyName
parameter. parameter, an object implementing the
Title
interface is returned representing the
title property (defined in the Ontology
for Media Resources 1.0 specification).
interface Title : MediaAnnotation
{
attribute DOMString titleLabel;
attribute DOMString typeLink;
attribute DOMString typeLabel;
};
titleLabel
of
type DOMStringtypeLabel
of type DOMStringvalue typeLink
of type DOMStringtitle = 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 used
as returned representing the
specific return type of language property
(defined in the Ontology
for Media Resources 1.0 specification).
interface Language : MediaAnnotation
{ attribute DOMString languageLink; attribute DOMString languageLabel;
};
MediaResource.getProperty languageLabel
propertyName
getMediaProperty
value languageLink
of type DOMStringlanguage = video.getMediaProperty(["language"]); /** Resulting in: * [ { "Language" : { * "propertyName" : "language", * "languageLabel" : "en-us", * "statusCode" : 200 * } * } ] */
Locator interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Locator" operation is invoked with "locator" as a value of
the propertyName
parameter. parameter, an object implementing the
Locator
interface is returned representing the
locator property (defined in the Ontology
for Media Resources 1.0 specification).
interface Locator : MediaAnnotation
{
attribute DOMString locatorLink;
};
value 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 * } * } ] */
Contributor interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Contributor" operation is invoked with "contributor" as a value
of the propertyName
parameter. parameter, an object implementing the
Contributor
interface is returned representing the
contributor property (defined in the Ontology
for Media Resources 1.0 specification).
interface Contributor : MediaAnnotation
{
attribute DOMString contributorLink;
attribute DOMString contributorLabel;
attribute DOMString roleLink;
attribute DOMString roleLabel;
};
id contributorLabel
of type DOMStringrole contributorLink
of type DOMStringroleLabel
of
type roleLink
of
type contributor = 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 * } * } ] */
Creator interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Creator" operation is invoked with "creator" as a value of
the propertyName
parameter. parameter, an object implementing the
Creator
interface is returned representing the
creator property (defined in the Ontology
for Media Resources 1.0 specification).
interface Creator : MediaAnnotation
{
attribute DOMString creatorLink;
attribute DOMString creatorLabel;
attribute DOMString roleLink;
attribute DOMString roleLabel;
};
value 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 * } * } ] */
CreateDate interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "CreateDate" operation is invoked with "date" as a value of
the propertyName
parameter. parameter, an object implementing the
Date
interface is returned representing the
date property (defined in the Ontology
for Media Resources 1.0 specification). This property has been renamed from
"Date" into "MADate" since the appearance of naming conflicts is
possible in web applications.
interface MADate : MediaAnnotation
{
attribute DOMString date;
attribute DOMString typeLink;
attribute DOMString typeLabel;
};
date
of type DOMStringtype typeLabel
of type DOMStringgetProperty typeLink
maDate = 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 * } * } ] */
Location interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Location" operation is invoked with "location" as a value of
the propertyName
parameter. parameter, an object implementing the
Location
interface is returned representing the
location property (defined in the Ontology
for Media Resources 1.0 specification).
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
system . coordiateSystem
attribute (default is WGS84).
latitude coordinateSystemLabel
of type coordinateSystemLink
of type DOMStringlongitude latitude
of type system . coordiateSystem
attribute (default is WGS84).
name locationLabel
of type DOMStringlocationLink
of type DOMStringsystem longitude
of type coordiateSystem
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 * } * } ] */
Description interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Description" operation is invoked with "description" as a value
of the propertyName
parameter. parameter, an object implementing the
Description
interface is returned representing the
description property (defined in the Ontology
for Media Resources 1.0 specification).
interface Description : MediaAnnotation
{
attribute DOMString descriptionLabel;
};
value 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 * } * } ] */
Keyword interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Keyword" operation is invoked with "keyword" as a value of
the propertyName
parameter. parameter, an object implementing the
Keyword
interface is returned representing the
keyword property (defined in the Ontology
for Media Resources 1.0 specification).
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://www.ontologyportal.org/WordNet#WN30Word-standardisation", * "statusCode" : 200 * } * } ] */
Genre interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Genre" operation is invoked with "genre" as a value of
the propertyName
parameter. parameter, an object implementing the
Genre
interface is returned representing the
genre property (defined in the Ontology
for Media Resources 1.0 specification).
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 * } * } ] */
Rating interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Rating" operation is invoked with "rating" as a value of
the propertyName
parameter. parameter, an object implementing the
Rating
interface is returned representing the
rating property (defined in the Ontology
for Media Resources 1.0 specification).
interface Rating : MediaAnnotation
{
attribute double ratingValue;
attribute DOMString ratingSystemLabel;
attribute DOMString ratingSystemLink;
attribute double minimum;
attribute double maximum;
};
issuer maximum
of type maximum minimum
of type minimum ratingSystemLabel
of type type ratingSystemLink
of type DOMStringvalue ratingValue
of type rating = 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 * } * } ] */
Relation interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Relation" operation is invoked with "relation" as a value of
the propertyName
parameter. parameter, an object implementing the
Relation
interface is returned representing the
relation property (defined in the Ontology
for Media Resources 1.0 specification).
interface Relation : MediaAnnotation
{
attribute DOMString targetLink;
attribute DOMString targetLabel;
attribute DOMString typeLink;
attribute DOMString typeLabel;
};
id targetLabel
of type DOMStringrelationship targetLink
of type DOMStringgetProperty typeLabel
typeLink
of relation = 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 * } * } ] */
Collection interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Collection" operation is invoked with "collection" as a value
of the propertyName
parameter. parameter, an object implementing the
Collection
interface is returned representing the
collection property (defined in the Ontology
for Media Resources 1.0 specification).
interface Collection : MediaAnnotation
{
attribute DOMString collectionLink;
attribute DOMString collectionLabel;
};
value 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 * } * } ] */
Copyright interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Copyright" operation is invoked with "copyright" as a value
of the propertyName
parameter. parameter, an object implementing the
Copyright
interface is returned representing the
copyright property (defined in the Ontology
for Media Resources 1.0 specification).
interface Copyright : MediaAnnotation
{
attribute DOMString copyrightLabel;
attribute DOMString holderLabel;
attribute DOMString holderLink;
};
holder copyrightLabel
of type holderLabel
of type DOMStringstatement holderLink
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 * } * } ] */
Policy interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Policy" operation is invoked with "policy" as a value of
the propertyName
parameter. parameter, an object implementing the
Policy
interface is returned representing the
policy property (defined in the Ontology
for Media Resources 1.0 specification).
interface Policy : MediaAnnotation
{
attribute DOMString statementLink;
attribute DOMString statementLabel;
attribute DOMString typeLink;
attribute DOMString typeLabel;
};
link statementLabel
of type DOMStringorganization statementLink
of type DOMStringtype typeLabel
of type DOMStringvalue typeLink
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 * } * } ] */
Publisher interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Publisher" operation is invoked with "publisher" as a value
of the propertyName
parameter. parameter, an object implementing the
Publisher
interface is returned representing the
publisher property (defined in the Ontology
for Media Resources 1.0 specification).
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 * } * } ] */
TargetAudience interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "TargetAudience" operation is invoked with "targetAudience" as a
value of the propertyName
parameter. parameter, an object implementing the
TargetAudience
interface is returned representing the
targetAudience property (defined in the Ontology
for Media Resources 1.0 specification).
interface TargetAudience : MediaAnnotation
{
attribute DOMString audienceLink;
attribute DOMString audienceLabel;
attribute DOMString classificationSystemLink;
attribute DOMString classificationSystemLabel;
};
classification audienceLabel
of type DOMStringissuer audienceLink
of type DOMStringtype classificationSystemLabel
of type
DOMStringgetProperty classificationSystemLink
targetAudience = 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 * } * } ] */
Fragments interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Fragments" operation is invoked with "fragment" as a value of
the propertyName
parameter. parameter, an object implementing the
Fragment
interface is returned representing the
fragment property (defined in the Ontology
for Media Resources 1.0 specification).
interface Fragment : MediaAnnotation
{
attribute DOMString identifier;
attribute DOMString roleLink;
attribute DOMString roleLabel;
};
id identifier
of type DOMStringroleLabel
of
type DOMStringgetMediaProperty
operation.
roleLink
of type DOMStringgetProperty getMediaProperty
operation.
fragment = movie.getMediaProperty(["fragment"]);/** Resulting in: * [ { "Fragment" : { * "propertyName" : "fragment", * "identifier" : "http://www.example.com/video.ogv#t=10,20", * "roleLabel" : "chapter", * "statusCode" : 200 * } * } ] */
NamedFragments interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "NamedFragments" operation is invoked with "namedFragment" as a
value of the propertyName
parameter. parameter, an object implementing the
NamedFragment
interface is returned representing the
namedFragment property (defined in the Ontology
for Media Resources 1.0 specification).
interface NamedFragment : MediaAnnotation
{
attribute DOMString identifier;
attribute DOMString label;
};
id identifier
of type DOMStringname label
of
type DOMStringnamedFragment = movie.getMediaProperty(["namedFragment"]);/** Resulting in: * [ { "NamedFragment" : { * "propertyName" : "namedFragment", * "identifier" : "http://www.example.com/video.ogv#t=30,35", * "label" : "kissScene", * "statusCode" : 200 * } * } ] */
FrameSize interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "FrameSize" operation is invoked with "frameSize" as a value
of the propertyName
parameter. parameter, an object implementing the
FrameSize
interface is returned representing the
frameSize property (defined in the Ontology
for Media Resources 1.0 specification).
interface FrameSize : MediaAnnotation
{
attribute double width;
attribute double height;
attribute DOMString unit;
};
height
of type
unit
of type DOMStringwidth
of type
frameSize = image.getMediaProperty(["frameSize"]);/** Resulting in: * [ { "FrameSize" : { * "propertyName" : "framesize", * "width" : 3072, * "height" : 2304, * "unit" : "pixels", * "statusCode" : 200 * } * } ] */
Compression interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Compression" operation is invoked with "compression" as a value
of the propertyName
parameter. parameter, an object implementing the
Compression
interface is returned representing the
compression property (defined in the Ontology
for Media Resources 1.0 specification).
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 * } * } ] */
Duration interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Duration" operation is invoked with "duration" as a value of
the propertyName
parameter. parameter, an object implementing the
Duration
interface is returned representing the
duration property (defined in the Ontology
for Media Resources 1.0 specification).
interface Duration : MediaAnnotation
{
attribute double duration;
};
value duration
of type duration = video.getMediaProperty(["duration"]); /** Resulting in: * [ { "Duration" : { * "propertyName" : "duration", * "duration" : 3600, * "statusCode" : 200 * } * } ] */
Format interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Format" operation is invoked with "format" as a value of
the propertyName
parameter. parameter, an object implementing the
Format
interface is returned representing the
format property (defined in the Ontology
for Media Resources 1.0 specification).
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 * } * } ] */
Samplingrate interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Samplingrate" operation is invoked with "samplingRate" as a
value of the propertyName
parameter. parameter, an object implementing the
SamplingRate
interface is returned representing the
samplingRate property (defined in the Ontology
for Media Resources 1.0 specification).
interface SamplingRate : MediaAnnotation
{
attribute double samplingRate;
};
value samplingRate
of type samplingrate = audio.getMediaProperty(["samplingRate"]);/** Resulting in: * [ { "SamplingRate" : { * "propertyName" : "samplingRate", * "samplingRate" : 44100, * "statusCode" : 200 * } * } ] */
Framerate interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "Framerate" operation is invoked with "frameRate" as a value
of the propertyName
parameter. parameter, an object implementing the
FrameRate
interface is returned representing the
frameRate property (defined in the Ontology
for Media Resources 1.0 specification).
interface FrameRate : MediaAnnotation
{
attribute double frameRate;
};
value frameRate
of type framerate = video.getMediaProperty(["frameRate"]);/** Resulting in: * [ { "FrameRate" : { * "propertyName" : "frameRate", * "frameRate" : 30, * "statusCode" : 200 * } * } ] */
AverageBitrate interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "AverageBitrate" operation is invoked with "averageBitRate" as a
value of the propertyName
parameter. parameter, an object implementing the
AverageBitRate
interface is returned representing the
averageBitRate property (defined in the Ontology
for Media Resources 1.0 specification).
interface AverageBitRate : MediaAnnotation
{
attribute double averageBitRate;
};
value averageBitRate
of type bitrate = video.getMediaProperty(["averageBitRate"]); /** Resulting in: * [ { "AverageBitRate" : { * "propertyName" : "averageBitRate", * "averageBitRate" : 45.06, * "statusCode" : 200 * } * } ] */
NumTracks interface is used as
When the specific
return type of MediaResource.getProperty MediaResource.getMediaPropertymethod which has "NumTracks" operation is invoked with "numTracks" as a value
of the propertyName
parameter. parameter, an object implementing the
NumTracks
interface is returned representing the
numTracks property (defined in the Ontology
for Media Resources 1.0 specification).
interface NumTracks : MediaAnnotation
{
attribute short number;
attribute DOMString typeString;
};
type number
of
type value typeString
of type numTracks = video.getMediaProperty(["numTracks"]);/** Resulting in: * [ { "NumTracks" : { * "propertyName" : "numTracks", * "number" : 2, * "typeString" : "audio", * "statusCode" : 200 * } * } ] */
MetadataSource
interfaceThis part illustrates some examples to
show how to use the API using JavaScript in actual implementations.
The examples assume that the methods getElementsByTagName() and
getElementsById() return an element that implements the
MediaResource MetadataSourceinterface. Moreover, in these examples it
interface is assumed that the implementation of the API knows where
to find the metadata that corresponds used to a specific media
resource (if necessary the location of the metadata can be
configured using the selectMAResource method). The implementation
should provide the mappings of different identify other metadata formats to the core properties. sources.
interface MetadataSource {
attribute DOMString metadataSource;
attribute DOMString sourceFormat;
};
metadataSource
of sourceFormat
of
type metadataSources =,new""MetadataSource,("""http://www.w3.org/2008/WebVideo/Annotations/wiki/MAWG-Stockholm-20090626.xml" ,"en-us""dc")[ 0);]. statement ;
This section introduces a set of status codes for the defined
API to indicate the system behaviour.
behavior. It uses a subset of the
HTML/1.1 [ HTTP11 ] status codes for general
informations information (e.g., bad request), but also system
specific ones information (e.g., property not defined in source
format). This choice was made because
developers are familiar with these status codes and it does not
imply any specific link with HTTP. The specific status codes
have been arranged in the HTML/1.1 [ HTTP11 ]
status codes categories. These codes
can be retrieved by calling the getDiagnosis method.
The set Later versions of this
document may include additional status codes my be enlarged or changed in
later versions of this document. other
changes. The numerical code range for the system specific
status codes start with x62 (x = number of HTML/1.1 [
HTTP11 ] status codes category and 62 =
MA).
Numerical Code | Textual Description | Example |
---|---|---|
200 | 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 with respect to the GET method used |
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 |
501 | Not Implemented | only a subset of GET methods for properties implemented |
This part illustrates some examples how to
use this specification are
non-normative. Everything else API
using JavaScript in this specification
is normative. The key words must , must not , required , should ,
should not , recommended , may , and optional actual implementations. Moreover, in these examples it is assumed that the implementation
of this specification are
API knows where to find the metadata that corresponds to a specific media
resource (if necessary the location of the metadata can be
interpreted 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.
//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 [
RFC2119 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://www.ontologyportal.org/WordNet#WN30Word-standardisation", "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 is non-normative. This
specification defines a client-side API
to access metadata information related to media resources on the
Web. These APIs will provide the
methods means for getting requesting
metadata information information, which can already be accessed in
one of 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 activity
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.
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 );interface MediaResource { short getSupportedModes(); MediaResource createMediaResource(in DOMString mediaResource, in optional MetadataSource[] metadataSources, in optional short mode); };//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);interface AsyncMediaResource : MediaResource { void getMediaProperty(in DOMString[] propertyNames, in PropertyCallback successCallback, in ErrorCallback errorCallback, in optional DOMString fragment, in optional DOMString sourceFormat, in optional DOMString language ); void getOriginalMetadata (in DOMString sourceFormat, in MetadataCallback successCallback, in ErrorCallback errorCallback); };//Operation for retrieval of the reason of an error DOMString getDiagnosis();interface PropertyCallback { void handleEvent (in MediaAnnotation[] mediaAnnotations); };};interface MetadataCallback { void handleEvent (in DOMString[] metadata); };interface MetadataSource { attribute DOMString metadataSource; attribute DOMString sourceFormat; };interface ErrorCallback { void handleEvent (in DOMString errorStatus); }; interface SyncMediaResource : MediaResource { MediaAnnotation[] getMediaProperty(in DOMString[] propertyNames, in optional DOMString fragment, in optional DOMString sourceFormat, in optional DOMString language); DOMString[] getOriginalMetadata (in 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; };module returnValues {interface Identifier : MediaAnnotation { attribute DOMString identifierLink; };interface MAObject { attribute DOMString unstructuredValue; attribute DOMString uri; attribute DOMString sourceFormat; attribute DOMString fragmentIdentifier; attribute DOMString mappingType; };interface Title : MediaAnnotation { attribute DOMString titleLabel; attribute DOMString typeLink; attribute DOMString typeLabel; };interface Language { attribute DOMString language; };interface Language : MediaAnnotation { attribute DOMString languageLink; attribute DOMString languageLabel; }; interface Locator : MediaAnnotation { attribute DOMString locatorLink; };interface UnsignedLongObject: MAObject { attribute unsigned long value; };interface Contributor : MediaAnnotation { attribute DOMString contributorLink; attribute DOMString contributorLabel; attribute DOMString roleLink; attribute DOMString roleLabel; };interface UnsignedShortObject: MAObject { attribute unsigned short value; };interface Creator : MediaAnnotation { attribute DOMString creatorLink; attribute DOMString creatorLabel; attribute DOMString roleLink; attribute DOMString roleLabel; };interface FloatObject: MAObject { attribute float value; };interface MADate : MediaAnnotation { attribute DOMString date; attribute DOMString typeLink; attribute DOMString typeLabel; };interface Identifier: MAObject { attribute DOMString value; attribute DOMString type; };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 Title: MAObject, Language { attribute DOMString value; attribute DOMString type; };interface Description : MediaAnnotation { attribute DOMString descriptionLabel; };interface Language : MAObject { attribute DOMString value; };interface Keyword : MediaAnnotation { attribute DOMString keywordLink; attribute DOMString keywordLabel; };interface Locator : MAObject { attribute DOMString value; };interface Genre : MediaAnnotation { attribute DOMString genreLink; attribute DOMString genreLabel; };interface Contributor: MAObject { attribute DOMString id; attribute DOMString role; };interface Rating : MediaAnnotation { attribute double ratingValue; attribute DOMString ratingSystemLink; attribute DOMString ratingSystemLabel; attribute double min; attribute double max; };interface Creator : MAObject { attribute DOMString value; };interface Relation : MediaAnnotation { attribute DOMString targetLink; attribute DOMString targetLabel; attribute DOMString typeLink; attribute DOMString typeLabel; };interface Date: MAObject { attribute DOMString date; attribute DOMString type; };interface Collection : MediaAnnotation { attribute DOMString collectionLink; attribute DOMString collectionLabel; };interface Location: MAObject, Language { attribute DOMString name; attribute Float longitude; attribute Float latitude; attribute Float altitiude; attribute DOMString system; };interface Copyright : MediaAnnotation { attribute DOMString copyrightLabel; attribute DOMString holderLink; attribute DOMString holderLabel; };interface Description : MAObject, Language { attribute DOMString value; }; interface Keyword : MAObject, Language { attribute DOMString value; };interface Policy : MediaAnnotation { attribute DOMString statementLink; attribute DOMString statementLabel; attribute DOMString typeLink; attribute DOMString typeLabel; };interface Genre : MAObject, Language { attribute DOMString value; };interface Publisher : MediaAnnotation { attribute DOMString publisherLink; attribute DOMString publisherLabel; };interface Rating: MAObject, Language { attribute DOMString issuer; attribute short value; attribute short minimum; attribute short maximum; attribute DOMString context; attribute DOMString type; };interface TargetAudience : MediaAnnotation { attribute DOMString audienceLink; attribute DOMString audienceLabel; attribute DOMString classificationSystemLink; attribute DOMString classificationSystemLabel; };interface Relation: MAObject, Language { attribute DOMString id; attribute DOMString relationship; };interface Fragment : MediaAnnotation { attribute DOMString identifier; attribute DOMString roleLink; attribute DOMString roleLabel; };interface Copyright: MAObject, Language { attribute DOMString statement; attribute DOMString[] holder; };interface NamedFragment : MediaAnnotation { attribute DOMString identifier; attribute DOMString label; };interface Policy: MAObject, Language { attribute DOMString statement; attribute DOMString link; attribute DOMString organization; attribute DOMString type; }; interface Publisher: MAObject { attribute DOMString value; };interface FrameSize : MediaAnnotation { attribute double width; attribute double height; attribute DOMString unit; };interface TargetAudience: MAObject, Language { attribute DOMString issuer; attribute DOMString classification; };interface Compression : MediaAnnotation { attribute DOMString compressionLink; attribute DOMString compressionLabel; };interface Fragment: MAObject, Language { attribute DOMString role; attribute DOMString id; };interface Duration : MediaAnnotation { attribute double duration; };interface NamedFragment: MAObject, Language { attribute DOMString name; attribute DOMString id; };interface Format : MediaAnnotation { attribute DOMString formatLink; attribute DOMString formatLabel; };interface FrameSize: MAObject { attribute unsigned long width; attribute unsigned long height; attribute DOMString unit; }; interface Compression : MAObject, Language { attribute DOMString value; }; interface Duration : MAObject { attribute unsigned long value; }; interface Format : MAObject { attribute DOMString value; };interface SamplingRate : MediaAnnotation { attribute double samplingRate; };interface Samplingrate : MAObject { attribute unsigned long value; }; interface Framerate : MAObject { attribute float value; };interface FrameRate : MediaAnnotation { attribute double frameRate; };interface AverageBitrate : MAObject { attribute float value; }; interface NumTracks : MAObject { attribute unsigned short value; attribute DOMString type; };interface AverageBitRate : MediaAnnotation { attribute double averageBitRate; };};interface NumTracks : MediaAnnotation { attribute short number; attribute DOMString typeString; }; };
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): Members of the Working
Group are (at the time of writing, and by alphabetical
order): Werner Bailer (JOANNEUM RESEARCH), Tobias B체rger Bürger
(University of Innsbruck), Eric Carlson (Apple, Inc.),
Pierre-Antoine Champin ((public) Invited expert), Ashish Chawla
((public) Invited expert), Jaime Delgado (Universitat Polit챔cnica Politècnica de Catalunya), Jean-Pierre EVAIN Evain ((public)
Invited expert), Martin Höffernig (JOANNEUM
RESEARCH), Philip J채genstedt
Jägenstedt (Opera Software), Ralf
Klamma ((public) Invited expert), WonSuk Lee (Electronics and Telecommunications Research Institute
(ETRI)), V챕ronique Malais챕 (Samsung
Electronics Co., Ltd.), Véronique Malaisé (Vrije
Universiteit), Erik Mannens (IBBT), Hui Miao (Samsung Electronics
Co., Ltd.), Thierry Michel ( W3C / ERCIM
), (W3C/ERCIM), Frank Nack
(University of Amsterdam), Soohong Daniel Park (Samsung Electronics
Co., Ltd.), Silvia Pfeiffer ( W3C
(W3C Invited Experts), Chris Poppe
(IBBT), V챠ctor Rodr챠guez Victor Rodríguez (Universitat Polit챔cnica 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 Söderberg
(ERICSSON), Mari Carmen Suárez-Figueroa
((public) Invited expert) Thai Wey Then (Apple, Inc.), Ruben
Tous (Universitat Polit챔cnica
Politècnica de Catalunya), Rapha챘l Raphaël Troncy
(CWI), (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.