TTML API Level 2

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

2.1 User Agent Rendering of Parsed TTML Content

When a text track is in the showing mode and the text track's list of cues includes an instance of TTMLCue, then a user agent attempts to render the cue using the HTML document fragment associated with the cue.

2.2 Web Application Rendering of Parsed TTML Content

When a text track is not in the showing mode and the text track's list of cues includes an instance of TTMLCue, then a Web Application may render the cue, for example, by making direct use of the cue's parsed form or by using the cue's formatted HTML form.

2.3 Web Application Use of Parsed TTML Content Metadata

When a text track is not in the showing mode and the text track's list of cues includes an instance of TTMLCue, then a Web Application may access parsed TTML metadata contained in the TTML DOM representation exposed by the cue.

3. Definitions

3.1 Terminology

[TBS]: To Be Supplied.

3.2 External Definitions

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

DOM: The concepts throw, and XML document, the interfaces Document, DocumentFragment, and Element, and and the exception SyntaxError. [DOM4]
HTML: The concepts interactive browsers, media-resource-specific text track, non-interactive browsers, and structured clone, showing mode, text track, text track's list of cues, and user agent, and the interfaces TextTrack and TextTrackCue. [HTML5]
TTML: The concepts TTML content, TTML intermediate synchronic document, and TTML media time. [TTML1]
TTML API Level 1: The interface RawTTMLCue. [TTML1API]
WebIDL: The generic semantics that apply to IDL specifications. [WEBIDL]

6. API Definitions

6.1 TTMLCue Interface

[Constructor(double startTime, double endTime, Document? content)]
interface TTMLCue : RawTTMLCue {
                attribute boolean  deferUpdates;
    [SameObject]
    readonly    attribute Document ttml;
    DocumentFragment getCueAsHTML ();
};

6.1.1 Attributes

deferUpdates of type boolean,

Access deferred update flag of cue.

Upon read, return true if rendering updates are being deferred; otherwise, return false. Upon write, perform the following ordered steps:

if the current value is the same as the new value, then return;
if the current value is false and the new value is true, then set the current value to true and begin deferring rendering updates;
if the current value is true and the new value is false, then set the current value to false and asynchronously perform a rendering update.

ttml of type Document, readonly

Obtain a reference to a live copy of an XML document that represents the current content of the cue.

6.1.2 Methods

getCueAsHTML: Obtain a reference to a (non-live) structured clone of the HTML rendition that represents the content of the cue at the time of the immediately preceding completed rendering update.
No parameters.
Return type: DocumentFragment

6.1.3 Constructors

TTMLCue

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].
content	`Document`	✔	✘	A `Document` representing a TTML intermediate synchronic document.

If the startTime argument is less than zero, then throw a SyntaxError exception.

If the endTime argument is less than zero, then throw a SyntaxError exception. If the endTime argument is less than startTime, then set the cue's end time to startTime.

If the content argument is null, then the constructed cue object represents a cue with no content. Otherwise, if any of the following constraints are not true, then throw a SyntaxError exception:

The value of content.contentType is either "application/ttml+xml" or "application/xml".
The value of content.documentElement is not null.
The value of content.documentElement.namespaceURI is "http://www.w3.org/ns/ttml".
The value of content.documentElement.localName is "tt".

Otherwise, set the cue's content to a structured clone of content.

TTML API Level 2

W3C Editor's Draft 19 November 2013

Abstract

Status of This Document

Table of Contents

1. Introduction