Timed Text Markup Language

Anatomy of a file

An XML document: a head that names styles and regions, and a body of paragraphs, one for each subtitle.

<tt xml:lang="en" …>
<head>styles, regions</head>
<body><div>
<p begin="00:00:23.000"
   end="00:00:24.500">
You're a jerk,<br/>Thom.</p>
</div></body>
</tt>

Times

TTML writes a time in more ways than any other subtitle format:

Styles

A style is a set of tts: attributes. Text takes them in order: from its region, then from the body, div, paragraph and span around it. Each element takes the styles it names (style="s1 s2", and the ones those name), then its own attributes.

Regions

A region is a box on the picture, placed by tts:origin and sized by tts:extent. Inside it, tts:displayAlign puts the text at the top, middle or bottom (before, center, after), and tts:textAlign to one side or in the centre.

<region xml:id="top"
        tts:origin="10% 10%"
        tts:extent="80% 80%"
        tts:displayAlign="before"/>

Subtitld works out where the text lands, whether the region is measured in percentages, pixels or cells, and takes the nearest of the nine places that SubRip's {\an1} to {\an9} name. When it writes a file, each place it uses is a region of that name: bottom, top, top-left…

Profiles

Most TTML is written to a profile: a subset of the language, with rules of its own. Subtitld reads each of them as TTML.

TTML in Subtitld

Opening a TTML file

Subtitld opens .ttml, .dfxp, .itt and .xml, and:

• reads TTML however it is written: in its namespace, in the old DFXP one, or with tt: before every element;
• reads every form of time, each counted from the div and body it is in;
• follows styles as TTML applies them, keeping italic, bold, underline, strikeout and any colour other than white;
• puts each subtitle where its region shows it;
• takes agents as speakers, ready for dubbing, and the file's xml:lang as the project's language;
• reads the encoding the file declares, and HTML's entities such as  .

A file that is not well-formed XML opens with a message giving the line and the column. A file that is not TTML at all says so.

Exporting TTML

Export, then Subtitles and TTML or DFXP, offers:

• TextThe original, a translation, or both, the translation below.
• Speaker namesLeft out, before the text (Thom: …), or as agents (ttm:agent), TTML's own way.
• FormattingKept, or removed.
• Shift timesEvery subtitle earlier or later by the same amount.
• LookWhite with a black outline, or as Subtitld's preview draws it: its font, colour and translucent box.

The file is TTML 1 in UTF-8. Times are written as 00:00:23.000, each place the subtitles sit as a region, formatting as spans, and line breaks as <br/>. Its xml:lang is the language of the text it holds. TTML and DFXP get the same file; only the extension differs.

TTML or WebVTT?

WebVTT for a <track> on a web page: browsers read it themselves. TTML for broadcasters, for streaming services that ask for it, and for players that read it, such as dash.js and Shaka Player. The WebVTT page has the rest.

Trivia