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.
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.
This section is non-normative.
This section describes common use cases for the TTML API Level 2.
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.
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.
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.
This specification relies upon the certain concepts and APIs defined in other specifications as follows:
Document
,
DocumentFragment
, and
Element
, and
and the exception
SyntaxError
.
[[!DOM4]]TextTrack
and
TextTrackCue
.
[[!HTML5]]RawTTMLCue
.
[[!TTML1API]]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.
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:
false
and the new value is true
, then set the current value to true
and
begin deferring rendering updates;true
and the new value is false
, then set the current value to false
and
asynchronously perform a rendering update.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:
content.contentType
is either "application/ttml+xml
" or "application/xml
".content.documentElement
is not null
.
content.documentElement.namespaceURI
is "http://www.w3.org/ns/ttml
".
content.documentElement.localName
is "tt
".
Otherwise, set the cue's content to a structured clone of content
.