TTML1 documents hold only text. TTML2 lets a document carry or point to fonts, images, audio and other data: images for image-based subtitles, fonts to draw the text, and audio for described video. All of this is TTML2 only.
Elements
| Element | In | Attributes | Content | Meaning |
|---|---|---|---|---|
resources | head | xml | metadata*, then data, font, image and audio, any number | The store of resources that other elements refer to by fragment, as #id. |
data | resources, metadata, source | encoding, format, length, src, type, condition, xml | text (simple), or metadata* then chunk+ (chunked), or metadata* then source+ (sourced) | Binary or text data, written in the file in one of the encodings below. |
chunk | data | encoding, length, condition, xml | text | One piece of chunked data; the pieces are joined in order. |
source | audio, data, font, image | format, src, type, condition, xml | metadata*, then data? | One alternative source: an external URI, a fragment pointing at a data element in resources, or a data child. A source may not contain another. |
font | resources | family, range (a Unicode range), style (normal, italic, oblique), weight (normal, bold), src, type, condition, xml | metadata*, source* | A font, and the family name, style and weight it serves. Values left out are taken from the font itself. |
image | resources; or div (as a block), p and span (inline) | src, type, timing, region, style, animate, condition, the xlink: attributes, xml, any tts: attribute | metadata*, animation*, source* | A picture. In resources it is only defined, and its timing and region are ignored. |
audio | resources; or div, p, span | src, type, timing, clipBegin, clipEnd, style, animate, condition, xml, style attributes | metadata*, animation*, source* | A sound played while the element is active. clipBegin and clipEnd are offset times into the audio, by default its start and end. |
On audio, font, image and data,
either src or source children are used, not both. The audio
URI http://www.w3.org/ns/ttml/resource/#empty means silence, and
http://www.w3.org/ns/ttml/resource/#speech means the text is spoken by
speech synthesis where that is supported and enabled.
Data attributes
| Attribute | Values | Meaning |
|---|---|---|
encoding | base16, base32, base32hex, base64, base64url | How the bytes are written as text, from RFC 4648. Default base64. Not used on sourced data. |
length | whole number, 0 or more | The number of bytes after decoding. If it does not match, the data is treated as empty. |
type | a media type, such as image/png or font/woff2 | What the data is. Required for simple and chunked data, where application/octet-stream is used when nothing better fits. A processor must not guess against it. |
format | a name or absolute URI | A hint at the format when the media type is generic or missing. |
src | URI | Where the content is. A fragment, #id, must point at the matching element inside resources. |
Audio styles
Attributes in the tta: namespace, http://www.w3.org/ns/ttml#audio.
| Attribute | Values | Initial | Applies to | Inherited | Meaning |
|---|---|---|---|---|---|
tta:gain | number | 1 | audio, body, div, p, span | no | Volume multiplier, clamped to −1 to 1; a negative value also inverts the phase. |
tta:pan | number | 0 | audio, body, div, p, span | no | Stereo position, clamped to −1 (fully left) to 1 (fully right). |
tta:pitch | a pitch value | 0% | span | yes | Pitch change for synthesised speech. |
tta:speak | none, normal, fast, slow | none | span | yes | Whether the text is spoken by speech synthesis, and how fast. |
Worked example
<head>
<resources>
<image xml:id="logo">
<source>
<data type="image/png" encoding="base64">iVBORw0KGgoAAAANSUhEUgAA…</data>
</source>
</image>
<font family="Subtitles" weight="bold" src="fonts/subtitles-bold.woff2" type="font/woff2"/>
</resources>
</head>
<body>
<div begin="0s" end="5s">
<image src="#logo"/>
</div>
</body>resources, its bytes carried
in Base64 (the PNG signature 89 50 4E 47 0D 0A 1A 0A is written
iVBORw0KGgo), then shown for five seconds; and a bold font loaded
from a file beside the document.Not confirmed
The syntax of a tta:pitch value beyond its initial value,
0%, and the full meaning of the altText item, which IMSC
uses for a text alternative.