Formats in scope

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

Formats out of scope

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

Terminology

In this document the terms "Ontology", "Media Resource", "Property", "Mapping" and "Property value types" are to be interpreted as defined in Section 2 of Ontology for Media Resources 1.0.

MediaResource interface

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

short getSupportedModes()

This operation is called to identify the implemented mode. The return codes should be as follows: 1 for asynchronous, 2 for synchronous and 3 for both modes.

MediaResource createMediaResource(in DOMString mediaResource, in optional MetadataSource[] metadataSources, in optional int mode)

This operation instantiates an object of either AsyncMediaResource or SyncMediaResource interface. Further, it allows to set the specific media resource and metadata sources to which this API is applied.

DOMString mediaResource

This attribute must set the specific media resource that should be processed by the API.

optional MetadataSource[] metadataSources

This attribute should specify additional metadata sources.

optional short mode

This attribute should specify the desired mode of operation. 1 for asynchronous and 2 for synchronous mode should be used.

ma = new MediaResource();
var mode = ma.getSupportedModes();

/** Resulting in:
 * { "supportedModes" : 3 }
 */

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 interface

The 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

void getMediaProperty (DOMString[] propertyNames, PropertyCallback successCallback, ErrorCallback errorCallback, optional DOMString fragment, optional DOMString sourceFormat, optional DOMString subtype, optional DOMString language)

This operation allows retrieval of the value of a specific property, several or all properties in an asynchronous manner. The specific property is passed as an argument and a list of objects is returned that hold the 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). 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.

DOMString[] propertyNames

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.

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

optional DOMString fragment

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.

optional DOMString sourceFormat

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

optional DOMString language

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 (DOMString sourceFormat, MetadataCallback successCallback, ErrorCallback errorCallback)

This operation allows retrieval of the original metadata according to the specified source format in an asynchronous manner. An example can be found here.

DOMString sourceFormat

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.

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

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 } }
 */

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 interface

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

MediaAnnotation[] getMediaProperty (DOMString[] propertyNames, optional DOMString fragment, optional DOMString sourceFormat, optional DOMString subtype, optional DOMString language)

This operation allows retrieval of the metadata of a specific property, several or all properties in a synchronous manner. The passed array holds the requested properties and a array of objects is returned. If the array is empty, every property holding values will be requested and returned. The returned objects implement the 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

DOMString[] propertyNames

This argument holds the requested properties as an array. If the array is empty, each property holding values will be returned.

optional DOMString fragment

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.

optional DOMString sourceFormat

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 is retrieved. This parameter is optional.

optional DOMString language

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.

DOMString[] getOriginalMetadata(DOMString sourceFormat)

This operation allows retrieval of the original metadata according to the specified source format in a synchronous manner. The operation returns a 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.

DOMString sourceFormat

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

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
 *         }
 * },
 * { ...
 * } ]
 */

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 interface

MediaAnnotation interface is used as the return type of MediaResource.getMediaProperty operation. It is a container to hold general values about properties enabling an iteration over a set of 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 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:

• For all properties, an interface is derived from MediaAnnotation, adding typed attributes according to the specification in the ontology document.
• This API MUST fill value with a printable string representation, it is recommended to follow these steps:
  • use a name/label if present
  • for a URI
    • if a URI identifies a value known by this API, use the appropriate label
    • dereference a URI to obtain a label, if possible
    • return the URI
  • create a string from the values of the set of attributes (e.g. numeric values)
• This approach possibly duplicates in 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.
• If an attribute has type 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 respectively
• For consistency, this approach is also followed if the property has only a single attribute.
• This approach allows for user extensions by deriving from MediaAnnotation or one of the derived interfaces for one of the properties.

attribute DOMString propertyName

The name of the property MUST be specified and SHOULD correspond to the property names defined in the Ontology for Media Resources 1.0 specification.

attribute DOMString value

This attribute MUST be filled with an printable string representation.

attribute DOMString language

This attribute SHOULD hold the language of the metadata. The attribute is empty if language is not applicable for a specific property. Recommended best practice is to use BCP 47 [[BCP47]].

attribute DOMString sourceFormat

This attribute allows to specify the metadata source from which the metadata was retrieved. It SHOULD use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification.

attribute DOMString fragmentIdentifier

This attribute SHOULD be an URI determining the fragment for which the metadata is relevant.

attribute DOMString mappingType

This attribute specifies the kind of mapping as discussed in the semantic level mappings. The value of this attribute SHOULD be one of the mapping characteristics.

attribute short statusCode

This attribute MUST specify the status code for the associated property (e.g., 264 indicating a structured return value).

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
 *         } 
 * } ]

Properties

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.

id = image.getMediaProperty(["identifier"]);
                                     
/** Resulting in:
 * [ { "Identifier" : {
 *         "propertyName" : "identifier",
 *         "identifierLink" : "urn:uuid:36a87260-1102-11df-8a39-0800200c9a66",		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

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
 *         }
 * } ]
 */
					

language = video.getMediaProperty(["language"]);
	
/** Resulting in:
 * [ { "Language" : {
 *         "propertyName" : "language",
 *         "languageLabel" : "en-us",		    
 *         "statusCode" : 200
 *         }
 * } ]
 */

locator = 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 = 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 = 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
 *         }
 * } ]
 */

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 = 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 = image.getMediaProperty(["description"]);

/** Resulting in:
 * [ { "Description" : {
 *         "propertyName" : "description",
 *         "descriptionLabel" : "Group picture of the W3C MAWG at the F2F meeting in Stockholm.",
 *         "statusCode" : 200
 *         }
 * } ]
 */
					

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
 *         } 
 * } ]
 */
					

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 = 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 = 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 = image.getMediaProperty(["collection"]);

/** Resulting in:
 * [ { "Collection" : {
 *         "propertyName" : "collection",
 *         "collectionLink" : "http://individuals.example.com/JohnDoe/myWorkPictures/",
 *         "collectionLabel" : "My Work Pictures",		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

copyright = 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 = 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 = image.getMediaProperty(["publisher"]);

/** Resulting in:
 * [ { "Publisher" : {
 *         "propertyName" : "publisher",
 *         "publisherLabel" : "ACME",
 *         "publisherLink" : "http://company.example.com/ACME",		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

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
 *         }
 * } ]
 */

fragment = movie.getMediaProperty(["fragment"]);

/** Resulting in:
 * [ { "Fragment" : {
 *         "propertyName" : "fragment",
 *         "identifier" : "http://www.example.com/video.ogv#t=10,20",
 *         "roleLabel" : "chapter",		    
 *         "statusCode" : 200
 *         }
 * } ]
 */

namedFragment = movie.getMediaProperty(["namedFragment"]);

/** Resulting in:
 * [ { "NamedFragment" : {
 *         "propertyName" : "namedFragment",
 *         "identifier" : "http://www.example.com/video.ogv#t=30,35",
 *         "label" : "kissScene",
 *         "statusCode" : 200
 *         } 
 * } ]
 */

frameSize = image.getMediaProperty(["frameSize"]);

/** Resulting in:
 * [ { "FrameSize" : {
 *         "propertyName" : "framesize",
 *         "width" : 3072,
 *         "height" : 2304,
 *         "unit" : "pixels",		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

compression = video.getMediaProperty(["compression"]);

/** Resulting in:
 * [ { "Compression" : {
 *         "propertyName" : "compression",
 *         "compressionLabel" : "H.264/AVC",
 *         "compressionLink" : "urn:example-org:codingnames2010#ITU-H264",		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

duration = video.getMediaProperty(["duration"]);
		    
/** Resulting in:
 * [ { "Duration" : {
 *         "propertyName" : "duration",
 *         "duration" : 3600,		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

format = image.getMediaProperty(["format"]);

/** Resulting in:
 * [ { "Format" : {
 *         "propertyName" : "format",
 *         "formatLabel" : "image/jpeg",
 *         "formatLink" : "http://dbpedia.org/resource/JPEG",		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

samplingrate = audio.getMediaProperty(["samplingRate"]);

/** Resulting in:
 * [ { "SamplingRate" : {
 *         "propertyName" : "samplingRate",
 *         "samplingRate" : 44100,		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

framerate = video.getMediaProperty(["frameRate"]);

/** Resulting in:
 * [ { "FrameRate" : {
 *         "propertyName" : "frameRate",
 *         "frameRate" : 30,		    
 *         "statusCode" : 200
 *         } 
 * } ]
 */

bitrate = video.getMediaProperty(["averageBitRate"]);

/** Resulting in:
 * [ { "AverageBitRate" : {
 *         "propertyName" : "averageBitRate",
 *         "averageBitRate" : 45.06,		    
 *         "statusCode" : 200
 *         }
 * } ]
 */

numTracks = video.getMediaProperty(["numTracks"]);

/** Resulting in:
 * [ { "NumTracks" : {
 *         "propertyName" : "numTracks",
 *         "number" : 2,
 *         "typeString" : "audio",		    
 *         "statusCode" : 200
 *         }
 * } ]
 */

MetadataSource interface

MetadataSource interface is used to identify other metadata sources.

attribute DOMString metadataSource

An URI identifying the metadata source.

attribute DOMString sourceFormat

The name of the actual metadata format. It SHOULD use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification.

metadataSources = new MetadataSource("http://www.w3.org/2008/WebVideo/Annotations/drafts/metadata_formats/DC_example1.xml","dc");

API Status Codes

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.

Later versions of this document may include additional status codes.

Usage as JavaScript API

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.

			
//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
 *         }
 * },
 * { ...
 *  } ]
 */

Usage as Web Service

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
           }
  } ]