TTML DOM

Editor: Sean Hayes.
Date: 13 June 2013.

Abstract

TTML DOM defines a platform-neutral model and API for manipulating TTML documents and their serialization into cue lists.

DOM

The Document Object Model (DOM) is a representation — a model — of a document and its content. [DOM]

Implementations that support programmatic acces to TTML using these API's must support DOM, because this API is defined in terms of the DOM, and some of the features are defined as extensions to the DOM interfaces. [DOM]

In particular, the following features are defined in the DOM specification: [DOM]

Attr interface
DocumentFragment interface
DOMException interface
Element interface
Node interface
NodeList interface
ProcessingInstruction interface
Text interface
HTMLCollection interface

Documents

Every TTML document in a TTML capable HTML 5 UA that is classed as a Presentation Processor is represented by a TTML Track Object. This builds on interfaces defined in the [DOM]

In addition

A Transformation Processor MAY support the metadata object model

A Presentation Processor MAY support the metadata object model

A Transformation Processor MAY support the profile object model

A Presentation Processor MUST support the profile object model

A Presentation Processor MUST support the Cue Object model

API

TTMLTextTrack Object

TTMLTextTrack

[Constructor(DOMString title, optional TTMLParameters parameters)]
interface TTMLTextTrack : TextTrack {
    attribute DOMString title;
    attribute DOMString extent;
    attribute DOMString lang;
    
    readonly TTMLParamters parameters;
    
    attribute TTMLBodyElement? body;
    readonly attribute TTMLCollection styles;
    readonly attribute TTMLCollection regions;
    readonly attribute TTMLCollection profiles;
    readonly attribute TTMLHeadElement? head;
    
    void appendTo(HTMLMediaElement elem);
    
    Document getTrackAsXml();
    void setTrackFromXml(Document xml);
    
    void populateCues();
    Document serialiseCuesAsXml();
    
    void appendCue(double startTime, double endTime, optional TTMLCueRegionElement content);
};

The following example indicates how to populate a TTMLTextTrack from TTML received as XML.

Example:

  var xhr = new XMLHttpRequest();
  //...
  // create a new track
  var ttml = new TTMLTexttrack("ex1", { } );

  var parser = new DOMParser();
  var doc = parser.parseFromString(xhr.responseText, 'text/xml');
  ttml.setTrackFromXml(doc);

  ttml.appendTo( document.getElementsByName("theVideo") );

The following example indicates how to populate a TTMLTextTrack by constructing cues directly

Example:

  // create a new track
  var ttml = new TTMLTexttrack("ex1", { } );
  var xml = ttml.getTrackAsXml();

  // make a new cue content element
  var cueBody = xml.createElementNS( ttmlNamespace, "region");
  // populate cueBody here...
  ttml.appendCue(cueBody);

  ttml.appendTo( document.getElementsByName("theVideo");

appendTo

The AppendTo(HTMLMediaElement element) method of TTMLTextTrack objects, when invoked, must run the following steps:

1. The text track list of cues is associated with the TTML rules for updating the text track rendering.

2. Add the new text track to element's list of text tracks.

3. Queue a task to fire a trusted event with the name addtrack, that does not bubble and is not cancelable, and that uses the TrackEvent interface, with the track attribute initialized to this TTMLTextTrack object, at element's textTracks attribute's TextTrackList object.

populateCues

The void populateCues(); method of TTMLTextTrack objects, when invoked, must run the following steps:

1. Clear the text track list of cues.

2. Run the rules for calculating cues using the xml document as would be returned by getTrackAsXml.

getTrackAsXml

1. Either returns a valid TTML document rooted at a tt element in the ttml namespace corresponding to this track.

or throw an TTMLNotValidException.

The returned value is a 'Live' DOM, that is changes made to it affect the relevant attributes on the TTMLTextTrack object. Similarly changes made to attributes and dictionary entries on the TTMLTextTrack will change the returned DOM.

However the set of cues is not affected by changes made to the live DOM until the populateCues() method is called, and adding or removing cues through addCue()/deleteCue() will not affect the DOM.

setTrackFromXml

1. Parse the Document ttml and populate the readonly attributes, the parameter dictionary, as well as title, extent and lang.

2. Run populateCues();

serialiseCuesAsXml

1. Either returns a valid TTML document rooted at a tt element in the ttml namespace corresponding to the current list of cues.

or throw an TTMLNotValidException.

The returned value is not a 'Live' DOM, it is a serialisation generated from the current list of serialised cues.

It is possible to use this value to set the live DOM as in the following example, but note that this will replace all of the cues in the cue list

Example:

  // create a new track
  var ttml = new TTMLTexttrack("ex1", { } );
  var xml = ttml.getTrackAsXml();

  while(moreCueContentAvailable()) {
	  // make a new cue content element
	  var cueBody = xml.createElementNS( ttmlNamespace, "region");
	  // populate cueBody here...
	  ttml.appendCue(cueBody);
  }

  var xml = ttml.serialiseCuesAsXml();
  ttml.setTrackFromXml(xml);

  ttml.appendTo( document.getElementsByName("theVideo");

Parameters

The TTMLParameters object models the parameters that may be set on a TTML document instance.

dictionary TTMLParamters {
    // parameters TBD if we want to have more approriate types here.
    attribute DOMString cellResolution;
    attribute DOMString clockMode;
    attribute DOMString dropMode;
    attribute DOMString frameRate;
    attribute DOMString frameRateMultiplier;
    attribute DOMString markerMode;
    attribute DOMString pixelAspectRatio;
    attribute DOMString profile;
    attribute DOMString subFrameRate;
    attribute DOMString tickRate;
    attribute DOMString timeBase;
};

TTMLTextTrackCue

The TTMLTextTrackCue element represents a serialised view of the TTML document at a defined time period.

TTMLTextTrackCue

interface TTMLTextTrackCue : TextTrackCue {
    TTMLRegionElement? getCueAsXml();
    DocumentFragment? getCueAsHtml();
    HTMLMediaElement? getCueAsAudio();
};

getCueAsXml

Returns an XML Element for the cue content. This Element is not 'Live' however and changes made to it will not affect the presentation of the cue if presented. A User Agent may return null for this method; for example if it implements a native TTML renderer and does not use the See rules for rendering TTML as HTML.

See rules for rendering TTML as HTML

getCueAsHtml

Returns an DocumentFragment for the cue content. This DocumentFragment is not 'Live' however and changes made to it will not affect the presentation of the cue if it is presented. A User Agent may return null for this method; for example if it implements a native TTML renderer and does not use the See rules for rendering TTML as HTML

See rules for rendering TTML as HTML

getCueAsAudio

Returns an Audio object containing a spoken rendering of the text in the cue. Note UA that do not support TTS must return NULL

See rules for rendering TTML as Description

TTMLCollection

interface TTMLCollection : HTMLCollection {

};

TTMLElement

interface TTMLElement : Element {

    attribute DOMString lang;

};

TTMLTimedElement

interface TTMLTimedElement : TTMLElement {

    attribute DOMString begin;                        // define a type for <timeExpression>
    attribute DOMString dur;                          // define a type for <timeExpression>
    attribute DOMString end;                          // define a type for <timeExpression>
    attribute DOMString timeContainer;                // define an enum for (par|seq)

    readonly attribute TTMLStyleElement? style;       // inline styles on the element
    readonly attribute TTMLRegionElement? region;     // referenced region
 
    // note can use Node.setAttribute("region", someAttribute);
};

TTMLStyledElement

    // models an element that can carry style children - do we need this, or just use DOM creation?
interface TTMLStyledElement {

    TTMLStyleElement? addStyle(DOMString name);
    void deleteStyle(DOMString name);

}

TTMLHeadElement

interface TTMLHeadElement : TTMLElement {
    TTMLRegionElement? addRegion(DOMString name);
    void deleteRegion(DOMString name);

    TTMLHeadElement implements TTMLStyledElement

};

TTMLRegionElement

interface TTMLRegionElement : TTMLTimedElement {
    TTMLRegionElement implements TTMLStyledElement
};

TTMLBodyElement

interface TTMLBodyElement: TTMLTimedElement {
 
};

TTMLDivElement

interface TTMLDivElement: TTMLTimedElement {
};

TTMLPElement

interface TTMLPElement: TTMLTimedElement {
};

TTMLSpanElement

interface TTMLSpanElement: TTMLTimedElement {
};

TTMLBrElement

interface TTMLBrElement: TTMLTimedElement {
};

TTMLSetElement

interface TTMLSetElement : TTMLTimedElement {

};

TTMLStyleElement

    // use get/setAttribute here to access individual styles
interface TTMLStyleElement : TTMLElement {
    readonly attribute CSSStyleSheet style;              // creates a CSS version of the style attributes on this element where origin-clear is clear.
};

Profile Objects

TBD

Metadata Objects

TBD

Cue Objects

The following objects are used in a serialised cue list derived from a TTML Track Object.

TTMLCueRegionElement

 interface TTMLCueRegionElement : Element {
     /// TBD

};

TTMLCueBodyElement

 interface TTMLCueBodyElement : Element {
     /// TBD

};

TTMLCueDivElement

 interface TTMLCueBodyElement : Element {
     /// TBD

};

TTMLCuePElement

 interface TTMLCuePElement : Element {
     /// TBD

};

TTMLCueSpanElement

 interface TTMLCueSpanElement : Element {
     /// TBD

};

TTMLCueBrElement

 interface TTMLCueBrElement : Element {
     /// TBD

};

TTMLCueMetadataElement

 interface TTMLCueMetadataElement : Element {
     /// TBD

};

TTMLCueAnonymousTextElement

 interface TTMLCueAnonymousTextElement : Text {
     /// TBD

};

References

[DOM] Document Object Model (DOM) Level 3 Core Specification, Arnaud Le Hors, Philippe Le Hégaret, Lauren Wood et al.. W3C.