Caption Format Reference
TTML File Format (.ttml)
TTML is XML, and it is the only common caption format that separates content from presentation the way a document format does. Styling and layout live in a head section and are referenced by the subtitles, which makes it powerful to author and awkward to convert.
What can a TTML file be converted to?
TTML converts to IMSC and DFXP as a profile change rather than a real conversion, and to WebVTT, SRT, SCC, MCC and EBU-STL as a genuine one. The difficulty is always the same: TTML's region and style model has more expressive range than any target except IMSC.
TTML at a glance
TTML is a W3C specification with a family of profiles built on top of it. Understanding which profile a file uses matters more than understanding TTML itself, because the profile decides what a validator will accept.
| Property | Value |
|---|---|
| Full name | Timed Text Markup Language |
| Extensions | .ttml, .xml, .dfxp |
| Specification | W3C TTML |
| File encoding | XML, normally UTF-8 |
| Structure | A head section holding styling and layout, and a body holding timed content |
| Timing | Clock time, offset time, or SMPTE timecode, depending on the declared time base |
| Frame rate | Declared in the file when the time base is SMPTE |
| Timing model | Explicit begin and end, or begin and duration |
| Positioning | Named regions defined as percentages of the frame |
| Styling | Named styles: colour, background, font family, size, alignment and more |
| Profiles | DFXP, SMPTE-TT, EBU-TT, EBU-TT-D and IMSC |
| Closed Caption Creator | Read and write |
For the anatomy of a TTML document and how the profiles differ, see TTML, DFXP and IMSC explained.
What TTML can and cannot carry
TTML can express nearly everything the other caption formats can, plus a good deal they cannot. In conversion that is a liability as much as an asset, because there is always something the target cannot hold.
| Capability | Supported | Notes |
|---|---|---|
| Dialogue text | Yes | Unicode, so every script is available |
| Explicit begin and end times | Yes | Or a begin plus a duration |
| Positioning | Yes | Named regions expressed as percentages of the frame |
| Multiple regions on screen | Yes | Independently positioned, simultaneously |
| Text colour and background | Yes | Arbitrary colours, with opacity |
| Font family and size | Yes | Requested by the file, honoured at the player's discretion |
| Italics, bold, underline | Yes | As style attributes rather than inline tags |
| Text alignment | Yes | Horizontal and vertical, per region |
| Multiple languages in one file | Yes | Through xml:lang on separate divisions |
| Ruby and vertical text | Partial | Available in TTML2 and IMSC 1.1, not in the original profiles |
| Frame-accurate timing | Yes | When the time base is SMPTE and a frame rate is declared |
| Bitmap subtitles | Partial | Only through the IMSC image profile |
Who asks for TTML files?
TTML is the format specifications are written in. It is rarely requested by name; a platform asks for one of its profiles instead.
- Streaming platforms and OTT services, almost always as an IMSC or platform-specific profile.
- European broadcasters moving from teletext to EBU-TT and EBU-TT-D.
- Archive and interchange, where TTML's expressiveness makes it a good master format.
- Localisation vendors delivering multi-language subtitle packages.
- Any workflow that needs positioning and styling to survive between tools.
For a specific delivery, check which profile is named. IMSC and DFXP are both TTML underneath, but a validator built for one will reject the other.
How do I open a TTML file?
TTML is XML, so any text editor shows the whole document and an XML-aware editor will fold and validate it. The subtitles are in the body; the reason they appear where they do is in the head.
Reading a TTML properly means reading both. A subtitle element carries a region reference and a style reference rather than the position and colour themselves, so the text alone tells you very little about how it will look on screen.
A caption editor is worth using once regions are involved, because judging a percentage-based layout against real picture is difficult from the markup alone.
Converting TTML to another format
Every conversion out of TTML is a question of how much of the head section the target can represent. The body converts easily; the styling and layout are where the decisions are.
| Convert TTML to | What survives | What to watch for |
|---|---|---|
| IMSC | Everything, usually | A profile change rather than a conversion. Features outside the target IMSC version have to be removed or rewritten. |
| DFXP | Everything, usually | Also a profile question. Confirm what the receiving platform validates against before assuming a rename is enough. |
| WebVTT | Text, approximate positioning, basic styling | Regions flatten into cue settings. Font and size requests have no direct equivalent and are dropped. |
| SRT | Text and line breaks | All styling and positioning is discarded, and simultaneous regions flatten into a single sequence. |
| SCC | Text, italics, approximate placement | Arbitrary colours reduce to seven, regions snap to a 32 by 15 grid, and the output must be 29.97 fps. |
| MCC | Text, styling, placement | More survives than in SCC because 708 carries a wider palette, and the frame rate is a choice rather than fixed. |
| EBU-STL | Text, colour, placement | Regions become teletext rows, colours reduce to the teletext palette, and a 25 fps base is required. |
Converting another format to TTML
Converting into TTML means authoring a head section that the source file never had. A converter will generate a default region and style set, and that default decides how the subtitles look.
| Convert to TTML from | What carries over | What the conversion has to decide |
|---|---|---|
| IMSC / DFXP | Everything | Which TTML profile to declare. The content rarely changes; the profile declaration does. |
| WebVTT | Text, positioning, basic styling | How cue settings become regions, and whether to carry CSS classes across as named styles. |
| SRT | Text and line breaks | A region and style model from scratch. The default region placement is the whole design. |
| SCC | Text, italics, placement | Whether to preserve the 608 grid as regions or normalise to a single bottom-centre region. |
| MCC | Text, styling, placement | Which caption service to read, and how to express 708 windows as regions. |
| EBU-STL | Text, colour, placement | Teletext rows become percentage regions, and the teletext palette becomes explicit colour values. |
| Transcript (DOCX, TXT, CSV) | Text | Everything. Timing, layout and styling all have to be created. |
Closed Caption Creator reads and writes every format in both tables. See the full file format support list, or the conversion API and CLI for batch workflows.
Where TTML conversions go wrong
TTML files fail in ways that produce a valid document containing invisible or mistimed subtitles, which is why validation alone is not enough.
- A time base that does not match the master. TTML can express time as media offsets, clock time or SMPTE timecode. Reading a SMPTE-based file as media offsets, or the reverse, shifts everything.
- A missing or unreferenced region. A subtitle that references a region the head does not define may be dropped silently by the player rather than falling back to a default.
- Profile mismatch on delivery. A technically valid TTML can still fail a platform validator that expects a specific profile with specific required attributes.
- Flattening simultaneous regions. Converting to SRT or WebVTT collapses independently positioned subtitles into one sequence, which can reorder dialogue that was never meant to be read in order.
The timing and positioning failures are covered in depth in TTML, DFXP and IMSC explained.
TTML conversion questions
Common questions about moving subtitles into and out of the TTML format.
Yes, with two significant reductions. TTML's arbitrary colours collapse to the seven CEA-608 colours, and percentage-based regions snap onto a 32 by 15 character grid. The output must also be 29.97 fps, so a file authored against a 25 or 23.976 fps master needs a conform first. Review placement against picture before delivery.
Because SRT has no positioning field at all. TTML places subtitles using named regions defined as percentages of the frame; SRT stores text and timing and nothing else. If several regions were on screen at once, they also flatten into a single sequence. Convert to WebVTT or IMSC when placement has to survive.
Some of it. Positioning survives approximately, as regions become percentage cue settings. Basic emphasis survives. Font family, font size and precise colour requests generally do not, because WebVTT expresses styling through CSS that many players ignore. Expect a readable result rather than a faithful one.
Read it from the file rather than assuming. When the time base is SMPTE, the frame rate is declared in the document and should be used as-is. When timing is expressed as media offsets or clock time, there is no frame rate in the file and it has to come from the master. Guessing here is the most common cause of drift.
Yes, using xml:lang on separate divisions within the body. This is unusual among caption formats and genuinely useful for archive and interchange. Most delivery specs still ask for one language per file, so a multi-language TTML is normally split on the way out rather than delivered as-is.
The two usual causes are timing and regions. If the time base or frame rate is interpreted differently from how the file was authored, every subtitle can land outside the media duration. If a subtitle references a region that is not defined in the head, some players drop it rather than falling back to a default. Check both before assuming the file is empty.
Author TTML, deliver everything else
Closed Caption Creator reads and writes TTML and its profiles with regions and styling intact, and generates SCC, MCC, EBU-STL, WebVTT and SRT from the same project.
Preview region placement against picture, conform frame rates properly, and QC before delivery.