API for Media Resources 1.0

1.1 Formats in scope

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

1.2 Formats out of scope

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

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

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

interface MediaResource {
    short         getSupportedModes ();
    MediaResource createMediaResource (DOMString mediaResource, optional MetadataSource[] metadataSources, optional short mode);
};

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);

}

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

interface AsyncMediaResource : MediaResource {
    void getMediaProperty (DOMString[] propertyNames, PropertyCallback successCallback, ErrorCallback errorCallback, optional DOMString fragment, optional DOMString sourceFormat, optional DOMString language);
    void getOriginalMetadata (DOMString sourceFormat, MetadataCallback successCallback, ErrorCallback errorCallback);
};

interface PropertyCallback {
    void handleEvent (MediaAnnotation[] mediaAnnotations);
};

interface MetadataCallback {
    void handleEvent (DOMString[] metadata);
};

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

*/

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

interface SyncMediaResource : MediaResource {
    MediaAnnotation[] getMediaProperty (DOMString[] propertyNames, optional DOMString fragment, optional DOMString sourceFormat, optional DOMString language);
    DOMString[]       getOriginalMetadata (DOMString sourceFormat);
};

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

*/

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

interface MediaAnnotation {
    attribute DOMString propertyName;
    attribute DOMString value;
    attribute DOMString language;
    attribute DOMString sourceFormat;
    attribute DOMString fragmentIdentifier;
    attribute DOMString mappingType;
    attribute short     statusCode;
};

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

*
}
]

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

interface Identifier : MediaAnnotation {
    attribute DOMString identifierLink;
};

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

*/

interface Title : MediaAnnotation {
    attribute DOMString titleLabel;
    attribute DOMString typeLink;
    attribute DOMString typeLabel;
};

title = song.getMediaProperty(["title"]);
		    

                    

/** Resulting in:
 * [ { "Title" : {
 *         "propertyName" : "title",
 *         "titleLabel" : "Artificial Horizon" ,
 *         "typeLink" : "http://www.ebu.ch/metadata/cs/ebu_ObjectTypeCodeCS.xml#21",
 *         "typeLabel" : "Album title",
 *         "statusCode" : 200
 *         }
 * } ]

*/

interface Language : MediaAnnotation {
    attribute DOMString languageLink;
    attribute DOMString languageLabel;
};

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

        

/** Resulting in:
 * [ { "Language" : {
 *         "propertyName" : "language",
 *         "languageLabel" : "en-us",                    
 *         "statusCode" : 200
 *         }
 * } ]

*/

interface Locator : MediaAnnotation {
    attribute DOMString locatorLink;
};

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

*/

interface Contributor : MediaAnnotation {
    attribute DOMString contributorLink;
    attribute DOMString contributorLabel;
    attribute DOMString roleLink;
    attribute DOMString roleLabel;
};

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

*/

interface Creator : MediaAnnotation {
    attribute DOMString creatorLink;
    attribute DOMString creatorLabel;
    attribute DOMString roleLink;
    attribute DOMString roleLabel;
};

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

*/

interface MADate : MediaAnnotation {
    attribute DOMString date;
    attribute DOMString typeLink;
    attribute DOMString typeLabel;
};

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

*/

interface Location : MediaAnnotation {
    attribute DOMString locationLink;
    attribute DOMString locationLabel;
    attribute double    longitude;
    attribute double    latitude;
    attribute double    altitude;
    attribute DOMString coordinateSystemLabel;
    attribute DOMString coordinateSystemLink;
};

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

*/

interface Description : MediaAnnotation {
    attribute DOMString descriptionLabel;
};

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

*/

interface Keyword : MediaAnnotation {
    attribute DOMString keywordLabel;
    attribute DOMString keywordLink;
};

keyword = image.getMediaProperty(["keyword"]);
/** Resulting in:
 * [ { "Keyword" : {
 *         "propertyName" : "keyword",
 *         "keywordLabel" : "meeting with people from outside the organisation",
 *         "keywordLink" : "http://sw.opencyc.org/2008/06/10/concept/en/MeetingWithOrganizationalOutsiders",                    
 *         "statusCode" : 200
 *         }
 * }, 
 * { "Keyword" : {
 *         "propertyName" : "keyword",
 *         "keywordLabel" : "standardisation",
 *         "keywordLink" : "http://purl.org/vocabularies/princeton/wn30/synset-standardization-noun-1",                    
 *         "statusCode" : 200
 *         } 
 * } ]

*/

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

*/

interface Rating : MediaAnnotation {
    attribute double    ratingValue;
    attribute DOMString ratingSystemLabel;
    attribute DOMString ratingSystemLink;
    attribute double    minimum;
    attribute double    maximum;
};

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

*/

interface Relation : MediaAnnotation {
    attribute DOMString targetLink;
    attribute DOMString targetLabel;
    attribute DOMString typeLink;
    attribute DOMString typeLabel;
};

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

*/

interface Collection : MediaAnnotation {
    attribute DOMString collectionLink;
    attribute DOMString collectionLabel;
};

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

*/

interface Copyright : MediaAnnotation {
    attribute DOMString copyrightLabel;
    attribute DOMString holderLabel;
    attribute DOMString holderLink;
};

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

*/

interface Policy : MediaAnnotation {
    attribute DOMString statementLink;
    attribute DOMString statementLabel;
    attribute DOMString typeLink;
    attribute DOMString typeLabel;
};

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

*/

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

*/

interface TargetAudience : MediaAnnotation {
    attribute DOMString audienceLink;
    attribute DOMString audienceLabel;
    attribute DOMString classificationSystemLink;
    attribute DOMString classificationSystemLabel;
};

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

*/

interface Fragment : MediaAnnotation {
    attribute DOMString identifier;
    attribute DOMString roleLink;
    attribute DOMString roleLabel;
};

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

*/

interface NamedFragment : MediaAnnotation {
    attribute DOMString identifier;
    attribute DOMString label;
};

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

*/

interface FrameSize : MediaAnnotation {
    attribute double    width;
    attribute double    height;
    attribute DOMString unit;
};

frameSize = image.getMediaProperty(["frameSize"]);
/** Resulting in:
 * [ { "FrameSize" : {
 *         "propertyName" : "framesize",
 *         "width" : 3072,
 *         "height" : 2304,
 *         "unit" : "pixels",                    
 *         "statusCode" : 200
 *         } 
 * } ]

*/

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

*/

interface Duration : MediaAnnotation {
    attribute double duration;
};

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

                    

/** Resulting in:
 * [ { "Duration" : {
 *         "propertyName" : "duration",
 *         "duration" : 3600,                    
 *         "statusCode" : 200
 *         } 
 * } ]

*/

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

*/

interface SamplingRate : MediaAnnotation {
    attribute double samplingRate;
};

samplingrate = audio.getMediaProperty(["samplingRate"]);
/** Resulting in:
 * [ { "SamplingRate" : {
 *         "propertyName" : "samplingRate",
 *         "samplingRate" : 44100,                    
 *         "statusCode" : 200
 *         } 
 * } ]

*/

interface FrameRate : MediaAnnotation {
    attribute double frameRate;
};

framerate = video.getMediaProperty(["frameRate"]);
/** Resulting in:
 * [ { "FrameRate" : {
 *         "propertyName" : "frameRate",
 *         "frameRate" : 30,                    
 *         "statusCode" : 200
 *         } 
 * } ]

*/

interface AverageBitRate : MediaAnnotation {
    attribute double averageBitRate;
};

bitrate = video.getMediaProperty(["averageBitRate"]);
/** Resulting in:
 * [ { "AverageBitRate" : {
 *         "propertyName" : "averageBitRate",
 *         "averageBitRate" : 45.06,                    
 *         "statusCode" : 200
 *         }
 * } ]

*/

interface NumTracks : MediaAnnotation {
    attribute short     number;
    attribute DOMString typeString;
};

numTracks = video.getMediaProperty(["numTracks"]);
/** Resulting in:
 * [ { "NumTracks" : {
 *         "propertyName" : "numTracks",
 *         "number" : 2,
 *         "typeString" : "audio",                    
 *         "statusCode" : 200
 *         }
 * } ]

*/

4.6 MetadataSource interface

MetadataSource interface is used to identify other metadata sources.

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

metadataSources

=


new


MetadataSource


(


"http://www.w3.org/2008/WebVideo/Annotations/drafts/metadata_formats/DC_example1.xml"

,


"dc"


);

4.7 API Status Codes

This section introduces a set of status codes for the defined API to indicate the system behavior. It uses a subset As described in section 4.4 , the status code is returned as one of the HTML/1.1 [ HTTP11 ] attributes of the MediaAnnotation object returned by a method call to the API. These status codes for general information (e.g., bad request), but also system specific 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 used on the HTML/1.1 [ HTTP11 ] status codes categories. API level, and applied to either client side or server side implementations.

Later versions of this document may include additional status codes or 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). codes.

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

Example 1: Return the name of the director of the movie "Apocalypse now".

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

*/

Example 2: Retrieve the title of the second song from the album "Joshua Tree" by U2.

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

*/

Example 3: Return the genre of the movie "Apocalypse Now".

genre = movie.getMediaProperty(["genre"], "", "", "en-us"); 
/** Resulting in: 
 * [ { "Genre" : {
 *         "propertyName" : "genre",
 *         "value" : "Action",
 *         ...,                    
 *         "statusCode" = 200
 *         }
 * },
 * { "Genre" : {
 *         "propertyName" : "genre",
 *         "value" : "Drama",
 *         ...,                    
 *         "statusCode" = 200
 *         }
 * },
 * { ...
 *  } ]

*/

5.2 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",
            "http://purl.org/vocabularies/princeton/wn30/synset-standardization-noun-1
    "
    
            "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
             }
    
    }
    
    
    ]