Metadata describes the document and its text without changing how it looks. It lives in
metadata elements, which may be the first children of almost any element,
and in the ttm: namespace, http://www.w3.org/ns/ttml#metadata.
Elements from other namespaces may also sit inside metadata.
Metadata elements
| Element | Attributes | Content | Meaning |
|---|---|---|---|
metadata | xml, condition (TTML2), any ttm: attribute | any ttm: elements, data (TTML2), and elements from other namespaces | A container for metadata about its parent element. |
ttm:title | xml | text | A human-readable title for the parent element; in head, for the document. |
ttm:desc | xml | text | A human-readable description of the parent element. |
ttm:copyright | xml | text | A copyright notice. A notice for the whole document belongs in head. |
ttm:agent | xml:id, type (required) | ttm:name*, ttm:actor? | A person, character or other party that text can be attributed to. It counts only in head or in a metadata child of head. |
ttm:name | type (required) | text | A name of the agent. |
ttm:actor | agent (required, IDREF) | empty | For an agent of type character: the agent who plays it. |
ttm:item | name | a value | TTML2: a named item of metadata. Names that TTML2 defines have no prefix; others should carry one. |
TTML2 adds xml:base and condition to each of these.
Agent and name types
ttm:agent type | Meaning |
|---|---|
person | A real person |
character | A character in the story; should have a ttm:actor |
group | A group of people |
organization | An organisation |
other | Anything else |
ttm:name type | Meaning |
|---|---|
full | The full name |
family | Family name |
given | Given name |
alias | Another name the agent is known by |
other | Any other kind of name |
ttm:item name | Meaning |
|---|---|
usesForced | Placed in head: the document uses the forced parameter in its conditions, so it holds forced subtitles. |
altText | A text alternative, such as for an image. IMSC deprecates its own ittm:altText in favour of it. |
Metadata attributes
| Attribute | On | Value | Meaning |
|---|---|---|---|
ttm:agent | the content elements body, div, p, span, br; in TTML2 also image and audio | IDREFS | The agents the content belongs to, such as who is speaking. |
ttm:role | as ttm:agent, and in TTML2 region | one or more of the role values below, separated by spaces | What kind of content it is. |
| Role | Content |
|---|---|
action | An action |
caption | A caption |
description | A description |
dialog | Dialogue |
expletive | An expletive |
kinesic | Body language or gesture |
lyrics | Song lyrics |
music | Music |
narration | Narration |
quality | A quality of the sound, such as how something is said |
reproduction | A reproduction |
sound | A sound effect |
source | The source of the content |
suppressed | Suppressed content |
thought | A thought |
title | A title |
transcription | A transcription |
x-name | A private role, such as x-example-org-custom-role. Other names without x- are reserved. |
The specification gives the role names only; the descriptions above are their plain meanings.
Worked example
<head>
<metadata>
<ttm:title>Episode 1</ttm:title>
<ttm:copyright>© 2026 Example Films</ttm:copyright>
<ttm:agent xml:id="anna" type="character">
<ttm:name type="given">Anna</ttm:name>
<ttm:actor agent="actor1"/>
</ttm:agent>
<ttm:agent xml:id="actor1" type="person">
<ttm:name type="full">Jane Smith</ttm:name>
</ttm:agent>
</metadata>
</head>
…
<p ttm:agent="anna" ttm:role="dialog">Where are we going?</p>
<p ttm:role="sound">[engine starts]</p>