This document defines a Level 2 API for exposing parsed and formatted Timed Text Markup Language (TTML) content to Web Applications.

This document is an editor's draft that has no official standing.

Introduction

This section is non-normative.

This document defines a Level 2 API for exposing parsed and formatted Timed Text Markup Language (TTML) content to Web Applications. The parsed form of TTML is exposed as a DOM representation of a TTML intermediate synchronic document. The formatted form of TTML is exposed as an HTML document fragment that encodes a renderable representation of the parsed form.

Use Cases

This section is non-normative.

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

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.

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.

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.

Definitions

Terminology

[TBS]
To Be Supplied.

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

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

Dependencies

API Definitions

TTMLCue Interface

attribute boolean deferUpdates

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:

  1. if the current value is the same as the new value, then return;
  2. if the current value is false and the new value is true, then set the current value to true and begin deferring rendering updates;
  3. 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.
[SameObject] readonly attribute Document ttml
Obtain a reference to a live copy of an XML document that represents the current content of the cue.
DocumentFragment 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.

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.