TTML to JSON Schema

To ensure that basic closed captions can be rendered on the TV across many partner devices, Yahoo supports simplified TTML. The following JSON schema outlines the schema structure that the built-in interpreter understands. Not adhering to this schema will result in failure to render closed captions.

Rendering constraints on partner devices require the following simplifications to TTML:

  • The paragraph node must be flattened, including only a string. The renderer does not support nested paragraph nodes.
  • Styles are not supported in a cascading style format.
  • Any styles associated with nested span tags that are included within a paragraph tag are ignored.

TTML Format Requirements

The following list outlines the format requirements of the supported schema:

  • "tt" — The root must be a "tt" Object.
  • "frameRate" — The "tt" Object must provide a "frameRate" field if and only if a frame rate time expression is provided in the paragraph entries.
  • "tt.head.styling.style" — This "style" field can be an Object for a single style entry or an array when multiple styles are provided.
  • "tt.head.layout.region" — This "region" field can be an Object for a single region entry or an array when multiple regions are provided.
  • "content" — Each paragraph Object must provide a "content" field. The contents of a paragraph entry must be flattened. The interpretor does not support nested paragraph entries and displays the "content" field as a string. This string may contain "<br>" tags that are replaced by line-feeds during rendering.
  • "begin" and "end" — Each paragraph Object must provide "begin" and "end" fields as time expressions. The time expression can be in Milliseconds (HH:MM:SS:MS) or Frame Rate Time (HH:MM:SS:FR).
  • "extent" — Each paragraph can provide an "extent" field to determine how much screen space is consumed by this container. Accepted values are expressed as "width% height%". If a value is not provided, the default value is "80% center". Currently the width is ignored.
  • "origin" — Each paragraph can provide an "origin" field to determine where this container is placed. Accepted values are expressed as "horizontal% vertical%". If a value is not provided, the default value is "center bottom".
  • "style" — Each paragraph can provide an "style" field to look up in "tt.head.styling.style".
  • "region" — Each paragraph can provide a "region" field to look up in "tt.head.layout.region".

TTML Time Expressions

Each paragraph Object must provide a "begin" and an "end" field to determine when to show and hide the closed captions content. The time expression can be in Milliseconds (HH:MM:SS:MSS) or Frame Rate Time (HH:MM:SS:FR). Note that if a frame rate time expression is provided, the document must provide a "tt.frameRate" property. Below are examples of both approaches:

TTML to JSON Schema

For a complete list of required fields refer to the JSON schema below:

Captions Data JSON Example

The following is an example of the transformation of TTML to JSON for rendering on the TV. Items that are enclosed in square brackets "[optional item]" are considered optional.

Table of Contents