Text is drawn inside rectangular regions placed on the root container, the area of the picture that the subtitles cover. Each region has a position, a size and its own styles, and the text assigned to it flows inside it.
Layout elements
| Element | In | Attributes | Content |
|---|---|---|---|
layout | head | xml | metadata*, region* |
region | layout; in TTML2 also div and p (inline) | xml:id (required out of line), begin, end, dur, timeContainer, style, animate (TTML2), condition (TTML2), ttm:role (TTML2), any tts: attribute | metadata*, animation*, style* |
A region’s timing says when it exists; outside that interval nothing in it is shown.
An inline region (TTML2) belongs to the div or p it sits in,
and its timing attributes are ignored. The style attributes that matter most for a
region are tts:origin and tts:extent (or, in TTML2,
tts:position), tts:writingMode,
tts:displayAlign, tts:padding,
tts:backgroundColor, tts:showBackground,
tts:overflow and tts:zIndex; see
Styling.
Which region text goes to
A content element is assigned to a region by these rules, in order:
- If it has a
regionattribute (and, in TTML2, that region is not excluded by a condition), it goes to that region. - Otherwise, if an ancestor has one, it goes to the nearest such ancestor’s region.
- Otherwise, if a descendant names a region, the element goes there too, carrying that descendant.
- Otherwise, if the document defines no regions at all, it goes to the default region.
- Otherwise it is not shown.
To fill a region, a processor copies body and removes every element
that is not active, is empty (except br and animation elements), or is
not assigned to that region, working from the leaves up. Removing an element removes
everything inside it. So if body names one region, a paragraph inside it
that names another is removed with its parent and never shown.
The default region is an anonymous region the size of the root container that lasts
for the whole document. It exists only when layout holds no
region, which is why a document without layout still shows its text.
When a region is shown, its content is the part of body that is active
and assigned to it, laid out as blocks (each div and p) and
lines, in document order. Regions with a higher tts:zIndex are drawn on
top.
Layout parameters
| Attribute | Value | Default | Meaning |
|---|---|---|---|
tts:extent on tt | auto, contain (TTML2), or two pixel lengths | auto | The size of the root container. auto leaves it to the player, normally the video picture. |
ttp:cellResolution | columns rows, both above 0 | 32 15 | Divides the root container into a grid of cells, the unit of c lengths. |
ttp:pixelAspectRatio | numerator denominator, both above 0 | square pixels | The shape of a pixel. TTML2 deprecates it unless tts:extent on tt is in pixels. |
ttp:displayAspectRatio | numerator denominator, both above 0 | that of the display | TTML2: the aspect ratio of the root container. |
Worked example
<layout>
<region xml:id="top" tts:origin="10% 5%" tts:extent="80% 20%"
tts:displayAlign="before" tts:showBackground="whenActive"/>
<region xml:id="bottom" tts:origin="10% 75%" tts:extent="80% 20%"
tts:displayAlign="after">
<style tts:backgroundColor="#00000080"/>
</region>
</layout>
…
<body>
<div>
<p begin="1s" end="3s" region="bottom">Where are we going?</p>
<p begin="1s" end="3s" region="top">[engine starts]</p>
</div>
</body>body and div name none, so by rule 3
they belong to both and carry each paragraph to its own region.