The Media Object Specification

Abstract

This specification defines the Media Object interface, which provides information about various types of media. The Media Object interface does not provide any information about the DOM properties associated with a file, but rather exposes information encoded in the native file format and provides information about the source and state of the file.

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 document is produced by the Web API WG (part of the Rich Web Clients Activity). This document has no formal standing within the W3C. Please send comments to public-webapi@w3.org, the public email list for issues related to Web APIs.

The patent policy for this document is the 5 February 2004 W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Web API Working Group's patent disclosure page. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as an Editor's 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.

Table of contents

• 1. Introduction
• • 1.1. Definitions
  • 1.2. Not in This Specification
  • 1.3. Conformance
• 2. MediaObject Interface
• • 2.1. type
  • 2.2. mimeType
  • 2.3. width
  • 2.4. height
  • 2.5. duration
  • 2.6. fileSize
  • 2.7. sourceUri
  • 2.8. metadata
  • 2.9. name
  • 2.10. title
  • 2.11. author
  • 2.12. createDate
  • 2.13. modifyDate
  • 2.14. vRes
  • 2.15. hRes
  • 2.16. bitDepth
  • 2.17. channels
  • 2.18. frameCount
  • 2.19. audioBitRate
  • 2.20. audioSampleRate
  • 2.21. audioSampleSize
  • 2.22. videoFrameRate
  • 2.23. videoDataRate
  • 2.24. videoSampleSize
  • 2.25. completed
  • 2.26. compression
  • 2.27. protected
  • 2.28. rights
  • 2.29. license
• 3. Examples of usage
• 4. Relationship to other specifications
• • 4.1. DOM Level 3 Core
• 5. Security Considerations

• A. IDL Definitions
• B. ECMAScript Language Binding
• C. Java Language Binding
• D. Change History
• E. References
• F. Acknowledgements

1. Introduction

An increasing amount of content on the Web is based on raster images, video, and audio. Concurrently, there is a strong common interest in supplying metadata for media content. Each piece of media has some kind of metadata, such as the height and width of a picture, the length of a video, or the artist and title of an audio file, but there is no standardized manner to access this information.

MediaObject is an interface that provides access to this information via script. Certain generalized information is exposed discretely, and other data can be accessed as a undifferentiate string that the author can parse.

The MediaObject interface is intended for use with non-textual media, but it may be suitable for use with certain mixed-media document formats such as PDF.

2. MediaObject Interface

This section is normative.

@@ISSUE: should we allow some metadata to be read-write, or only read? write permission would be useful for tagging, which is getting very popular

@@ISSUE: are there any considerations for <canvas> that should be taken into account? can this help inform that spec?

@@ISSUE: SVG should specify some way of extracting height and width on the root element for this interface... for percentages, absolute values could be derived by the referencing element's dimensions and/or the innerWidth/Height

@@ISSUE: should we allow someone to create a new instance of a MediaObject (similar to "var myImage = new Image()")? could this be useful for preloading? or should we force them to create an element and access it from there? should this be up to the host language?

The MediaObject interface is a set of properties and methods available on Element nodes which contain reference to external or encoded media. This includes, but is is not limited to raster images, and video and audio files or streams.

This interface should be implemented on all elements which provide referenced or embedded non-textual media. It may be implemented on elements which provide text-based media where appropriate (for example, PDF or SVG). The manner in which data and metadata is associated with a particular file can vary, from a wrapper that encloses the format, to native format information, to externally-defined data embedded in the file. How this information is extracted from the media file must be decided by each implementation for each MIME Type, and should be informed by mandated methods for that format.

Not all properties of this interface are applicable to all media types (e.g. audio media does not have a width or height). Additionally, not all properties that are applicable to a given media type may be available on a particular file of that type (e.g. while the 'author' property is available on most media types, the device or application that created the file may not have assigned a value to this property). If a media file does not provide information about a property, whether it is applicable to that media type or not, the User Agent must return null when that property is accessed via this interface, and must not throw any exceptions. Finally, a media file that may not be expected to have a particular property may nonetheless have a value for it (for example, while GIF files are generally considered to be a static raster format, they can have a duration, and less intuitively, an audio file could possess a width and height for unknown reasons); since the availability for a given datum on a media file may not match User Agent expectations, a User Agent must present all data available for a given media file.

Depending on the file format, the metadata may be available even if the file is not fully loaded (for instance, the metadata information may be in the header of the file). A User Agent must expose metadata as soon as it is available, regardless of the file's state of completeness.

Certain metadata have intrinsic values related to the format of the media, such as height or duration; these data must be read only. A User Agent must not allow an author to modify intrinsic values for the media file. Other metadata reflect extrinsic properties for the media file, such as the title, the author, or any keywords. A User Agent may allow an author to modify extrinsic (mutable) values for the media file.

@@ISSUE: how discrete/specific should we get with exposing properties?

2.1. type

('audio' | 'video' | 'raster' | 'vector')

2.2. mimeType

2.3. width

natural width in pixels

2.4. height

natural height in pixels

2.5. duration

(for video/audio)

2.6. fileSize

Size of the media in bytes

2.7. sourceUri

2.8. metadata

The metadata property must provide access to any metadata available for a media file, regardless of format. Accessing this property must return a string which contains the available metadata. Depending on this format, this metadata string may be a flat text file, XML, RDF, or even a binary encoding; how this metadata string is parsed and used is left to the author.

Metadata may be natively supported, or a separate format attached to the file. With mixed metadata available, not all metadata may agree [how to resolve?]. A User Agent may let the author of a document modify the contents of a metadata via script, unless the protected property of a file is file has a value of true, in which case any attempt to change the metadata content should throw an NO_MODIFICATION_ALLOWED_ERR exception.

2.1.1. Authoring guidelines

The responsibility for verifying the metadata format and content rests with the author of the script, as does confirming the consistency of the content. As a best practice, the author must not modify metadata in a way that violates the rights of the original creator of the file; supplemental metadata is preferred to removal or alteration of original metadata. Note that not all User Agents will permit modification of extrinsic metadata, so the author should not rely on this facility.

2.1.2. Intrinsic Metadata

The following list is being considered for individual property names. We need to find the proper tradeoff between simplicity and ease of implementation, and ease and convenience of authoring.

2.9. name

2.10. title

2.11. author

2.12. createDate

date media was created in ISO-8601 format

2.13. modifyDate

date media was last modified in ISO-8601 format

2.14. vRes

vertical resolution in dpi (dots per inch)

2.15. hRes

horizontal resolution in dpi (dots per inch)

2.16. bitDepth

2.17. channels

2.18. frameCount

2.19. audioBitRate

2.20. audioSampleRate

2.21. audioSampleSize

2.22. videoFrameRate

(frames/second) [avi]

2.23. videoDataRate

videoDataRate? [wmf]

2.24. videoSampleSize

2.25. completed

@@ISSUE: supply streaming info?

2.26. compression

2.27. protected

boolean value indicating whether or not media has rights or license restrictions

2.28. rights

2.29. license

3. Examples of usage

This section is informative.

This section illustrates several ECMAScript [ECMA262] examples using MediaObject.

3.1. Example of Acessing Metadata

The following code takes an element as a parameter, and returns the metadata associated with that element:

function getMetadata( el ) {

}

4. Relationship to other specifications

This section is informative.