TTML format (.ttml, .dfxp)
TTML (Timed Text Markup Language) is the W3C XML standard for timed
text — subtitles and captions — also distributed as .dfxp. A TTML
document carries its captions inside a <body>/<div>/<p> hierarchy
in the http://www.w3.org/ns/ttml namespace, with timing and
positioning expressed as attributes (begin, end, dur, region,
textAlign).
The reader walks the <p> hierarchy and emits one translatable block
per non-empty <p>. The timing and positioning attributes are kept on
the block's properties and written back unchanged. Inline styling such
as <span> is unwrapped into the block's text; <br/> handling is
controlled by escapeBR. This mirrors Okapi's TTML filter, with the
native default of one block per <p>.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
cjkCharsPerLine | integer | 0 | Maximum number of characters per line for CJK languages. Set to 0 to disable. |
escapeBR | boolean | true | When true, <br/> elements are removed and text is joined with spaces; when false, <br/> is preserved as literal text. |
maxCharsPerLine | integer | 0 | Maximum number of characters per line in output. Set to 0 to disable. |
maxLinesPerCaption | integer | 0 | Maximum number of lines per caption in output. Set to 0 to disable. |
mergeAdjacentCaptions | boolean | false | Merge adjacent <p> elements ending with trailing punctuation into one block. |
splitWords | boolean | false | Split words so that they don't go over the character limit per line. |
Configure these parameters interactively and copy the YAML on the Format Reference.
Examples
Keep in-caption line breaks
Preserve <br/> as literal text so the translator can see line breaks.
escapeBR: false
Merge sentence-spanning captions
Combine adjacent captions that continue a sentence into one block.
mergeAdjacentCaptions: true
Processing notes
One block is emitted per non-empty
<p>; timing and positioning attributes (begin, end, dur, region, textAlign) are preserved on block properties.Inline styling such as
<span>is unwrapped into the block's source text.
Limitations
The output line-wrapping parameters (maxCharsPerLine, maxLinesPerCaption, cjkCharsPerLine, splitWords) are accepted for parity with Okapi but are not yet enforced by the native writer; caption text is written as supplied.
← Back to the Format Reference