TTML API Level 1

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 an editor's draft that has no official standing.

This document was published by the Timed Text Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-tt@w3.org (subscribe, archives). All comments are welcome.

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.

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.

2. Use Cases

This section is non-normative.

This section describes common use cases for the TTML API Level 1.

2.1 Web Application Rendering of Raw In-band TTML Content

Some HTML user agents do not parse or render TTML content that is embedded in a media resource and potentially exposed to Web applications as a media-resource-specific text track (i.e., in-band text track). In such cases, it is possible for a Web application to parse and render this content by making use of client-side script provided the TTML content is exposed by some well defined API.

2.2 Web Application Use of Metadata in Raw In-band TTML Content

Authors of TTML content may include a variety of arbitrary metadata that provide additional layers of information about that content. For example, the ttp:agent attribute may be used to specify the agent(s) involved in the performance (production) of content (such as 'James Bond', 'Doctor No', etc.), and the ttp:role attribute may be used to specify the role(s) of content (such as action, dialog, music, etc.), and so forth. In such cases, it is possible for a Web application to parse and utilize this metadata by making use of client-side script provided the TTML content containing the metadata is exposed by some well defined API.

An example of utilizing this metadata would be providing a client script generated user interface to search for TTML content associated with particular agents or roles, or automatically provide links from content so marked to other Web content or explanatory material.

3. Definitions

3.1 Terminology

[raw TTML content]: An unparsed form of TTML content suitable for representation as a string data type.

3.2 External Definitions

This specification relies upon the certain concepts and APIs defined in other specifications as follows:

DOM: The concept throw, and the exception SyntaxError.
HTML: The concepts interactive browsers, media-resource-specific text track, non-interactive browsers, and user agent, Web application, and the interface TextTrackCue. [HTML5]
TTML: The concepts TTML content, TTML intermediate synchronic document, and TTML media time. [TTML1]
WebIDL: The generic semantics that apply to IDL specifications. [WEBIDL]

4. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

An HTML user agent that claims to support any profile of [TTML1], or any subsequent version thereof, MUST implement support for the TTML Level 1 API defined herein, and, if it exposes TTML content to Web applications in any fashion, then it also MUST expose that content to Web applications using this API.

Note

The above conformance requirement is not intended to proscribe exposing TTML content to a Web application using an alternative mechanism to that defined herein. That is, TTML content may be exposed to a Web application in multiple ways, provided one of those ways is the mechanism defined here.

5. API Definitions

5.1 RawTTMLCue Interface

Issue 1

Need to cite definitions of well-formed and UTF-16 encoded XML serialization.

[Constructor(double startTime, double endTime, DOMString text)]
interface RawTTMLCue : TextTrackCue {
                attribute DOMString text;
};

5.1.1 Attributes

text of type DOMString,: Access text representation of cue. Upon read, returns UTF-16 encoded XML serialization of the TTML intermediate synchronic document associated with cue. Upon write, if specified value is a well-formed UTF-16 encoded XML serialization of a TTML intermediate synchronic document, then the content of the cue is set to the new value; otherwise, throw a SyntaxError exception.

5.1.2 Constructors

RawTTMLCue

Parameter	Type	Nullable	Optional	Description
startTime	`double`	✘	✘	A TTML media time relative cue starting time, as further defined by `startTime` [HTML5].
endTime	`double`	✘	✘	A TTML media time relative cue ending time, as further defined by `endTime` [HTML5].
text	`DOMString`	✘	✘	A non-empty string representing a well-formed UTF-16 encoded XML serialization of a TTML intermediate synchronic document.

If the endTime parameter is less than startTime, then set the cue's end time to startTime.

Note

The value of the text parameter may be an empty string, in which case the constructed cue object represents a cue with no content.

TTML API Level 1

W3C Editor's Draft 19 November 2013

Abstract