TTML document structure

A TTML document is an XML document. This page covers the elements that make up its skeleton and its text, as defined by TTML1 (first published in 2010, third edition 2018) and TTML2 (2018). TTML2 keeps every TTML1 element and adds more; where something exists only in TTML2, the tables say so.

The file

The file is XML 1.0, normally UTF-8. There is no binary signature: a reader looks for a root element named tt in the TT namespace. The registered media type is application/ttml+xml. Files use .ttml, .dfxp (the old name of TTML1’s profiles) or plain .xml.

Prefix	Namespace	Holds
(default) `tt:`	`http://www.w3.org/ns/ttml`	The elements on this page, and `styling`, `layout`, `region`, `set` and the rest
`ttp:`	`http://www.w3.org/ns/ttml#parameter`	Timing, layout and profile parameters
`tts:`	`http://www.w3.org/ns/ttml#styling`	Style attributes
`ttm:`	`http://www.w3.org/ns/ttml#metadata`	Metadata elements and attributes
`tta:`	`http://www.w3.org/ns/ttml#audio`	TTML2 audio style attributes (Embedded content)
`isd:`	`http://www.w3.org/ns/ttml#isd`	TTML2: intermediate synchronic documents, a processed form that holds what is shown at one moment; not used in ordinary files

The prefixes are only conventions; what counts is the namespace each is bound to. Elements and attributes in other namespaces are allowed and are ignored by a processor that does not know them.

Element tree

tt
├── head
│   ├── metadata, ttm:* items
│   ├── ttp:profile                (profiles and features)
│   ├── resources                  (TTML2: data, font, image, audio)
│   ├── styling ── initial (TTML2), style
│   ├── layout ── region
│   └── animation ── animate, set  (TTML2)
└── body
    └── div  (nested div allowed)
        └── p
            ├── span  (nested span allowed)
            ├── br
            └── #text

The order inside head is fixed. Every element may start with metadata children, and timed elements may hold set or animate children.

Content elements

The attribute groups used below: xml is xml:id, xml:lang, xml:space and, in TTML2, xml:base; timing is begin, end, dur and timeContainer; tts, ttm and ttp are any attribute in those namespaces.

Element	Attributes	Content, in order	Notes
`tt`	xml (`xml:lang` required), `tts:extent`, ttp	`head`?, `body`?	The root. Parameters are written here and apply to the whole document.
`head`	xml	metadata, `ttp:profile`, `resources`? (TTML2), `styling`?, `layout`?, `animation`? (TTML2)	Nothing in it is shown.
`body`	xml, timing, `style`, `region`, `animate` (TTML2), `condition` (TTML2), tts, ttm	metadata, animation, `div`*	Its timing is the outermost timed span of the content.
`div`	as `body`	metadata, animation, an inline `region`? (TTML2), then `div`, `p` and, in TTML2, `image` and `audio`, any number	A block that groups paragraphs. Nested divs are a TTML feature (`#nested-div`).
`p`	as `body`	metadata, animation, an inline `region`? (TTML2), then text, `span`, `br` and, in TTML2, `image` and `audio`	One paragraph: normally one subtitle.
`span`	as `body`; in TTML2 also `xlink:href`, `xlink:show`, `xlink:title`, `xlink:role`, `xlink:arcrole`	metadata, animation, then text, `span`, `br` and, in TTML2, `image` and `audio`	A run of text with its own style or timing. With `xlink:href` it is a link.
`br`	xml, `style`, `condition` (TTML2), tts, ttm	metadata, animation (deprecated in TTML2)	A forced line break. It has no timing of its own.

The elements of the head have their own pages: styling, initial and style, layout and region, animation, animate and set, resources and what it holds, metadata and ttp:profile.

Content attributes

Attribute	Value	Meaning
`xml:id`	XML ID	Names the element so that `style`, `region`, `animate` and `ttm:actor` can refer to it.
`xml:lang`	BCP 47 language tag, or empty	The language of the text. Required on `tt`; an empty value means undeclared.
`xml:space`	`default` or `preserve`	How white space in the text is treated. With `default`, runs of spaces and line ends collapse to one space and are trimmed at line edges; with `preserve` they are kept, and a line end in the text is a line break. Default `default`.
`xml:base`	URI	TTML2: the base for relative URIs below this element.
`style`	IDREFS	The styles applied to this element, by `xml:id`. See Styling.
`region`	IDREF	The region the element is shown in. See Layout and regions.
`begin`, `end`, `dur`, `timeContainer`	time expression; `par` or `seq`	When the element is active. See Timing.
`animate`	IDREFS	TTML2: out-of-line animations applied to this element. See Animation.
`condition`	condition expression	TTML2: when it is false, the element and everything inside it are left out.
`xlink:href`	URI	TTML2, on `span` and `image`: the link target.
`xlink:show`	`new`, `replace`, `embed`, `other`, `none`	TTML2: how the target is shown, as in XLink 1.1. Default `new`.
`xlink:title`, `xlink:role`, `xlink:arcrole`	string; URI lists	TTML2: XLink 1.1 descriptions of the link.

Conditions (TTML2)

A condition is a small expression, true or false. It can use literals (true, false, decimal numbers, quoted strings), the operators below and three functions. A function name is followed directly by its bracket.

Operators, lowest precedence first	Kind
`\|\|` `&&`	Logical or, and
`==` `!=`	Equality
`<` `>` `<=` `>=`	Relational
`+` `-`	Additive
`*` `/` `%`	Multiplicative
`+` `-` `!`	Unary

Function	Result
`media("query")`	True when a CSS media query matches, such as `media('(min-aspect-ratio: 16/9)')`. A query the processor does not support is false.
`parameter("name")`	The value of a bound parameter, from the table below.
`supports("designator")`	True when the processor supports a feature or extension, such as `supports('#textShadow')`.

Bound parameter	Type	Meaning
`forced`	boolean	Whether the player is showing forced subtitles only. A document that uses it should carry a `usesForced` metadata item in its `head`.
`mediaAspectRatio`	number	The aspect ratio of the media the text goes with.
`mediaLanguage`	string	The main language of that media.
`userLanguage`	string	The user’s main language.

Worked example

<?xml version="1.0" encoding="UTF-8"?>
<tt xmlns="http://www.w3.org/ns/ttml"
    xmlns:ttp="http://www.w3.org/ns/ttml#parameter"
    xmlns:tts="http://www.w3.org/ns/ttml#styling"
    xmlns:ttm="http://www.w3.org/ns/ttml#metadata"
    xml:lang="en" ttp:timeBase="media">
  <head>
    <metadata><ttm:title>Episode 1</ttm:title></metadata>
    <styling>
      <style xml:id="s1" tts:color="white" tts:textAlign="center"/>
    </styling>
    <layout>
      <region xml:id="bottom" tts:origin="10% 80%" tts:extent="80% 15%"/>
    </layout>
  </head>
  <body region="bottom" style="s1">
    <div>
      <p begin="00:00:01.000" end="00:00:03.500">Where are we going?</p>
      <p begin="4s" dur="2.25s">Somewhere<br/><span tts:fontStyle="italic">we have never been.</span></p>
    </div>
  </body>
</tt>

Two subtitles shown in one region at the bottom of the picture. The second uses an offset time and a duration, and has two lines.