W3C

API for Media Resource 1.0

W3C Working Draft @@ April 2009

This version:
http://www.w3.org/TR/2009/WD-mediaont-api-1.0-200904@@
Latest version:
http://www.w3.org/TR/mediaont-api-1.0
Editor:
@@@, @@@@

Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This specification defines a client-side API to access metadata information related to media resources on the Web. The purpose of the API is to provide the simple API for developers to easily access the information independent of metadata formats. This API is based on the ontology that is a description of relations between existing formats to support cross-community data integration of information.

Status of this Document

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 First Public 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.

Please send comments about this document to public-media-annotation@w3.org mailing list (public archive).

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.

Table of Contents

1 Introduction
    1.1 Purpose of this specification
    1.2 Formats in scope
    1.3 Formats out of scope
2 API Description
    2.1 API for Descriptive Properties
        2.1.1 Identification Properties Interface
        2.1.2 Creation Properties Interface
        2.1.3 Content description Properties Interface
        2.1.4 Relational Properties Interface
        2.1.5 Rights Properties Interface
        2.1.6 Distribution Properties Interface
        2.1.7 Fragments Properties Interface
    2.2 API for Technical Properties
    2.3 API for Iterating operation
3 Data type description
4 Examples of how to use the API

Appendices

A References
B Acknowledgements (Non-Normative)

1 Introduction

This section is informative.

Editorial note 
This part will be elaborated in the perspectives of reason why we want to provide an API and an explanation on who should use/implement it.

This specification defines a client-side API to access metadata information related to media resources on the Web. The purpose of the API is to provide the simple API for developers to easily access the information independent of metadata formats. This API is based on the ontology that is a description of relations between existing formats to support cross-community data integration of information.

1.1 Purpose of this specification

This specification defines an ontology and a client-side API for cross-community data integration of information related to media objects on the Web. The purpose of the ontology and the API is to help circumventing the profileration of video metadata formats by providing partial mappings between the existing formats.

The ontology and API differ in their area of application: The API provides methods for client side processing. The ontology is a description of relations between existing formats, which is used in the API for data integration.

The properties defined in the ontology focus on usage scenarios related to video on the web. Nevertheless they also take formats into account which are not specific to video, but which are of importance for video. An example of this is information from Dublin Core Dublin Core.

This specification does not aim on defining new properties for media objects. As a result, there is no detailed description of properties, but mainly references to definitions in existing formats.

1.2 Formats in scope

In this specification the following formats related to media objects on the Web have been taken into account .

Note:

This specification is based on a review of existing formats and the properties they provide. This review does not aim to be complete, and this specification does not aim to cover all properties defined in these formats. The choice of properties is motivated by their wide usage.

1.3 Formats out of scope

The following formats have been decided to be out of scope for this specification.

2 API Description

Editorial note 
This part will be elaborated with a precise description of the actual methods in the API, (so these are the methods that can be found in the Strawman API design and note), described using web IDL. This section needs to define and explain all aspects of those methods (parameters and return values).

2.1 API for Descriptive Properties

2.1.1 Identification Properties Interface

String ma_getIdentifier();

String ma_getTitle();

String ma_getLanguage();

String ma_getLocator();

RESULT ma_setIdentifier(String id);

RESULT ma_setTitle(String title);

RESULT ma_setLanguage(String lang);

RESULT ma_setLocator(String loc);

2.1.2 Creation Properties Interface

List<String> ma_getContributor();

List<String> ma_getCreator();

Date ma_getCreateDate();

String ma_getLocation();

RESULT ma_setContributor(List<String>contributor);

RESULT ma_setCreator(List<String> creator);

RESULT ma_setCreateDate(Date createDate);

RESULT ma_setLocation(String loc);

2.1.3 Content description Properties Interface

String ma_getDescription();

List<String> ma_getKeyword();

String ma_getGenre();

String ma_getRating();

RESULT ma_setDescription(String desc);

RESULT ma_setKeyword(List<String>keyword);

RESULT ma_setGenre(String genre);

RESULT ma_setRating(String rating);

2.1.4 Relational Properties Interface

String ma_getRelation();

ma_getCollection();

RESULT ma_setRelation(String relation);

RESULT ma_setCollection(String collection);

2.1.5 Rights Properties Interface

String ma_getCopyright();

String ma_getLicense();

RESULT ma_setCopyright(String copyright);

RESULT ma_setLicense(String license);

2.1.6 Distribution Properties Interface

List<String> ma_getPublisher();

String ma_getTargetAudience();

RESULT ma_setPublisher(List<String> publisher);

RESULT ma_setTargetAudience(String targetaudi);

2.1.7 Fragments Properties Interface

List<String> ma_getFragments();

List<String> ma_getamedFragments();

RESULT ma_getFragments(List<String> frags);

RESULT ma_getnamedFragments(List<String> namedfrags);

2.2 API for Technical Properties

Dimension ma_getFrameSize();

int ma_getCompression();

int ma_getDuration();

String ma_getFormat();

int ma_getSamplingrate();

int ma_getFramerate();

int ma_getBitrate();

int ma_getNumTracks();

RESULT ma_setFrameSize(Dimension framesize);

RESULT ma_getCompression(int compression);

RESULT ma_getDuration(int duration);

RESULT ma_getFormat(String format);

RESULT ma_getSamplingrate(int samplingrate);

RESULT ma_getFramerate(int framerate);

RESULT ma_getBitrate(int bitrate);

RESULT ma_getNumTracks(int numtracks);

2.3 API for Iterating operation

Editorial note 
This part will be covered later in the perspectives of what kind API for iterating operation is helpful to application developers .

3 Data type description

This section is normative.

Editorial note 
Here we discuss for each property in the ontology what the specific return values are. (for example if we call the GetStructuredValue method for property ma:creator, what would be the structure and content of the result (so in fact a kind of Javadoc style)). The examples that were added to the summary table are an obvious starting point and should also be repeated in this section to clarify what is meant.

4 Examples of how to use the API

Editorial note 
Here I think we should discuss actual (working) implementations that implement this API

A References

[Dublin Core]
DCMI Metadata Terms. January 2008. Available at http://dublincore.org/documents/2008/01/14/dcmi-terms/ . The latest version of DCMI Metadata Terms is available at http://dublincore.org/documents/dcmi-terms/ .
[EXIF2.2]
EXIF 2.2. Specification by JEITA, April 2002. Available at http://www.exif.org/Exif2-2.PDF .
[HTML 5]
Hickson, I., and D. Hyatt. HTML 5. A vocabulary and associated APIs for HTML and XHTML. W3C Working Draft, June 2008. Available at http://www.w3.org/TR/2008/WD-html5-20080610/ . The latest version of HTML 5 is available at http://www.w3.org/TR/html5/ .
[MWG Guidelines Image]
Guidelines for handling image metadata, version 1.0.. Metadata Working Group, September 2008. Available at http://www.metadataworkinggroup.com/pdf/mwg_guidance.pdf .
[ID3]
ID3 tag version 2.3.0. February 1999. Available at http://www.id3.org/id3v2.3.0 .
[IPTC]
IPTC Standard Photo Metadata 2008. IPTC Core Specification Version 1.1, IPTC Extension Specification Version 1.0, Document Revision 2, June 2008. Available at http://www.iptc.org/std/photometadata/2008/specification/IPTC-PhotoMetadata-2008.pdf
[Media RSS]
Yahoo! Media RSS Module - RSS 2.0 Module. March 2008. Available at http://search.yahoo.com/mrss .
[MPEG 7]
MPGE 7 tbd.
[MPEG 21]
MPGE 21 tbd.
[RFC 3986]
Berners-Lee, T., R. Fielding, L. Masinter. Uniform Resource Identifier (URI): Generic Syntax. RFC 3986, January 2005. Available at http://www.ietf.org/rfc/rfc3986.txt
[RFC 3987]
Dürst, M. and M. Suignard. Internationalized Resource Identifiers (IRIs). RFC 3987, January 2005. Available at http://www.ietf.org/rfc/rfc3987.txt.
[XML Schema 2]
Biron, P. V. and A. Malhotra. XML Schema Part 2: Datatypes Second Edition. W3C Recommendation, October 2004. Available at http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/ . The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2/ .
[XMP]
XMP Specification Part 2 - Standard Schemas. Adobe, 2008. Available at http://www.adobe.com/devnet/xmp/pdfs/XMPSpecificationPart2.pdf .
[YouTube Data API Protocol]
YouTube Data API Protocol. April 2008. Available at http://code.google.com/intl/en/apis/youtube/2.0/reference.html .

B Acknowledgements (Non-Normative)

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

Members of the Working Group are (at the time of writing, and by alphabetical order): Werner Bailer (K-Space), Tobias Bürger (University of Innsbruck), Eric Carlson (Apple, Inc.), Pierre-Antoine Champin ((public) Invited expert), Jaime Delgado (Universitat Politècnica de Catalunya), Jean-Pierre EVAIN ((public) Invited expert), Ralf Klamma ((public) Invited expert), WonSuk Lee (Electronics and Telecommunications Research Institute (ETRI)), Véronique Malaisé (Vrije Universiteit), Erik Mannens (IBBT), Hui Miao (Samsung Electronics Co., Ltd.), Thierry Michel (W3C/ERCIM), Frank Nack (University of Amsterdam), Soohong Daniel Park (Samsung Electronics Co., Ltd.), Silvia Pfeiffer (W3C Invited Experts), Chris Poppe (IBBT), Víctor Rodríguez (Universitat Politècnica de Catalunya), Felix Sasaki (Potsdam University of Applied Sciences), David Singer (Apple, Inc.), Joakim Söderberg (ERICSSON), Thai Wey Then (Apple, Inc.), Ruben Tous (Universitat Politècnica de Catalunya), Raphaël Troncy (CWI), Vassilis Tzouvaras (K-Space), Davy Van Deursen (IBBT).

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