Lyrics Example Annotations

The symbol Apple extension symbol in the annotations indicates an Apple-specific implementation or recommendation.

The reference numbers (for example, §7.2.2) refer to the section in the TTML specification in which the element is explained.

<?xml version="1.0" encoding="UTF-8"?>

XML Declaration (required)

The character encoding of your document must be defined.

Apple accepts only UTF-8 encoding as it efficiently encodes non-Roman characters.

Important: The TTML file must not contain a byte-order mark (BOM).

<tt xmlns="http://www.w3.org/ns/ttml"

  xmlns:tts="http://www.w3.org/ns/ttml#styling"

  xmlns:itunes="http://itunes.apple.com/lyric-ttml-extensions"

  xmlns:ttm="http://www.w3.org/ns/ttml#metadata"

Document Container §7.1.1 (required)

The tt element begins the iTunes Timed Text (iTT) document container.

The xmlns (for XML namespace) attribute is required and is needed for schema validation. It is used to declare the namespace (and associated schema) to which the tags in the XML are expected to conform. The namespace must be http://www.w3.org/ns/ttml.

Apple extension symbol Supply the XML Namespace to allow the use of Apple extensions: http://itunes.apple.com/lyric-ttml-extensions. Note that this example uses the prefix itunes (in the prefix xmlns:itunes), however using itunes is not required; you can use any prefix.

xml:lang="en-US">

Language §7.2.2 (required)

This is the same format that is described for use in the locale attribute in the Language Codes, and indicates the language and optional dialect used in the lyrics.

Head Element

<head>

Head §7.1.2 (required)

Begins the head element, which specifies document metadata, such as title, and other document-specific information, such as the artists performing.

Note:Apple extension symbol Any styling and layout elements included in the Head element are ignored by Apple processing.

<metadata>

Metadata §8.1.1 (required)

Begins the metadata block.

  <ttm:title>City of Stars</ttm:title>

Title §12.1.2 (required)

Supplies the title of the song for the lyrics you are delivering.

<ttm:agent type="person" xml:id="v1">

Agent §12.1.5 (optional)

The ttm:agent element is used to indicate all the artists who perform vocal parts of the lyrics. Later in the TTML document when you supply the lyrics, you can indicate which artist is performing a line or words by supplying the value provided with the xml:id attribute. See the annotations for the <p> and <span> elements for how to use the ttm:agent and xml:id attributes.

For example, if multiple agents are identified, the Apple Music Duet feature shows lyrics on opposite sides of the screen.

The attributes supplied with the ttm:agent element include the type and the xml:id.

The type attribute indicates the type of performer:

  • Use "person" for lines sung by individual vocalist

  • Use "group" for lines sung by multiple vocalists

  • Use "other" for other cases

The xml:id attribute supplies the reference ID used to refer to the artist.

Apple extension symbol The ttm:agent attribute can be specified only at one element in the hierarchy. For example, if you specify ttm:agent in a parent element (div), you cannot specify ttm:agent in a child element (p).

<ttm:name type="full">Ryan Gosling</ttm:name>

Name §12.1.6 (optional)

The ttm:name attribute supplies the name and name type of the performer.

The type attribute is required. The value must be "full".

</ttm:agent>

Ends the ttm:agent block.

</metadata>

Ends the metadata block.

Body Element

<body dur="02:29.720">

Body §7.1.3 (required)

Begins the body element, which is used to determine the lyrics and their timings. The <body> element is required, but the dur attribute is optional.

<div begin="00:09.327" end="00:44.651" itunes:song-part="Verse">

Div §7.1.4 (required)

Begins the section within the document where you enter the actual text of the lyrics and the timing.

Each paragraph is represented by a <div> element. The lyrics document can include multiple consecutive <div> elements.

Apple extension symbol Because paragraphs are identified with <div> tags, do not use <p></br></p> to indicate blank lines.

Apple extension symbol Add the optional itunes:song-part attribute to a <div> element to note its compositional purpose in the song. Apple recommends the following values:

  • Verse

  • Chorus

  • PreChorus

  • Bridge

  • Intro

  • Outro

  • Refrain

  • Instrumental

The div blocks in the annotated examples contain the following paragraph tags (<p>). The example paragraphs are explained in the rows that follow.

Note: Currently, song parts are not displayed to the users.

Line-by-line timing example

<p begin="00:09.327" end="00:12.109" ttm:agent="v1">City of stars</p>

<p begin="00:12.426" end="00:15.906" ttm:agent="v1">Are you shining just for me?</p>

<p begin="00:18.972" end="00:21.753" ttm:agent="v1">City of stars</p>

<p begin="00:22.024" end="00:25.552" ttm:agent="v1">There's so much that I can't see</p>

<p begin="00:28.052" end="00:30.752" ttm:agent="v1">Who knows?</p>

<p begin="00:31.373" end="00:37.357" ttm:agent="v1">I felt it from the first embrace I shared with you</p>

<p begin="00:37.803" end="00:41.859" ttm:agent="v2">That now our dreams</p>

<p begin="00:41.957" end="00:44.651" ttm:agent="v2">May finally come true</p>

Example Paragraph §7.1.5

Each <p> tag defines a period of time in which the lyrics in the line are sung.

Timing (optional):

For line-by-line timing, add the timing attributes (begin and end) to the <p> tag.

  • The begin attribute indicates the start time of the line of the lyrics

  • The end attribute indicates when that line ends

For time value details and rules, see Timing.

Agent:

When the lyrics are sung by different artists, you can specify which artist sings the line using the ttm:agent attribute. Each artist can be referenced by the reference ID (xml:id) you assigned in the Agent element (ttm:agent) within the Head element (see annotation above). When using the agent attribute, the following timing rules apply:

  • Timed elements for different agents can overlap.

  • Timing intervals for a single agent must not overlap.

Beat-by-beat timing example

<p begin="02:38.994" end="02:43.927" ttm:agent="v1">

<span ttm:role="x-bg">

<span begin="02:38.994" end="02:39.413">(I'm</span>

<span begin="02:39.413" end="02:40.178">dancing,</span>

<span begin="02:40.178" end="02:40.562">I'm</span>

<span begin="02:40.562" end="02:41.978">dancing)</span>

</span>

<span begin="02:40.407" end="02:41.325">Dancing</span>

<span begin="02:41.325" end="02:41.671">with</span>

<span begin="02:41.671" end="02:41.941">a</span>

<span begin="02:41.941" end="02:42.860">strang</span>

<span begin="02:42.860" end="02:43.927">er</span>

</p>

<p begin="02:43.690" end="02:48.133" ttm:agent="v2">

<span ttm:role="x-bg">

<span begin="02:43.690" end="02:44.039">(I'm</span>

<span begin="02:44.039" end="02:44.874">dancing,</span>

<span begin="02:44.874" end="02:45.191">I'm</span>

<span begin="02:45.191" end="02:46.495">dancing)</span>

</span>

<span begin="02:45.163" end="02:46.061">Dancing</span>

<span begin="02:46.061" end="02:46.411">with</span>

<span begin="02:46.411" end="02:46.747">a</span>

<span begin="02:46.747" end="02:47.558">strang</span>

<span begin="02:47.558" end="02:48.133">er</span>

</p>

Paragraph §7.1.5

Each <p> tag defines a period of time in which the lyrics in the line are sung.

Span §7.1.6

Use the <span> elements to specify beat-by-beat timing and to inset background vocals.

Timing (required for beat-by-beat timing):

Add timing attributes to the <span> elements within a <p> tag. To apply beat-by-beat timing to the entire song, all lines (<p> tags) must have <span> elements with timing attributes.

  • The begin attribute indicates the start time of the <span> element

  • The end attribute indicates when that <span> element ends

There’s no requirement to use <span> elements on word breaks.

Role §12.2.2

The <span> elements can use the ttm:role="x-bg" attribute to inset background vocals.

Place the <span ttm:role="x-bg"> tag either first or last in the <p> tag:

  • If the background vocal starts before the main vocals come in, place the <span ttm:role="x-bg"> tag first, in front of the main vocals <span> tag.

  • Otherwise, place the <span ttm:role="x-bg"> tag last in the <p> tag.

  </div>

 </body>

</tt>