This document defines a Level 1 API for exposing raw 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 1 API for exposing raw Timed Text Markup Language (TTML) content to Web applications. It is expected that a Level 2 API will be defined that builds upon this API in order to expose parsed Timed Text Markup Language (TTML) content to Web applications.

Use Cases

This section is non-normative.

This section describes common use cases for the TTML API Level 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.

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.

Definitions

Terminology

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

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

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.

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.

API Definitions

RawTTMLCue Interface

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

attribute DOMString text
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.

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.

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