Overview of TTML for Lyrics

Provide lyrics for songs in an album by delivering documents called lyrics files. Lyrics files are formatted according to the TTML format, with extensions for features specific to the Apple implementation. Each document contains the lyrics for one song. For each <track> tag in the metadata.xml file, specify the lyrics file using the <lyrics_file> tag. See Basic Music Album Metadata Example for information on how to deliver the lyrics file.

Note: You cannot deliver lyrics for music videos.

Lyrics files can specify line-by-line lyrics or beat-by-beat lyrics:

For annotations on the XML formats, see Lyrics Example Annotations.

Note: You can still send lyrics in plain text format using the <lyrics> tag, however, sending lyrics in HTML format is being deprecated.

The following sections briefly describe the standard TTML content elements for lyrics. Throughout this chapter, the symbol Apple extension symbol indicates an Apple implementation or recommendation.

Lyrics Structure

The basic structure of a song is based on the standard TTML content elements.

Lyrics Content

TTML Element

Use

Song

<body>

The <body> element block encloses the tags used to deliver the lyrics.

Paragraphs

<div>

A <div> block encloses the tags used to deliver the lyrics for one paragraph (or line).

Apple extension symbol In the <div> block, use the itunes:song-part attribute to identify its compositional purpose in the song. See Apple Extension for Lyrics below.

Lines

<p>

A <p> tag encloses each line in the lyrics.

Apple extension symbol Do not use line breaks (<br>). Instead, use <p> tags to delimit lines.

  • In the <p> tag, use the ttm:agent attribute to indicate which artist is performing the line. See Agent below.

  • In the <p> tag, add being and end attributes to apply line-by-line timing to lines. See Timing below.

Word or Phrase

<span>

A <span> tag is used within a <p> tag to apply special conditions to a word or phrase.

  • In the <span> tag, add the ttm:agent attribute to indicate which artist is performing the word or phrase. See Agent below.

  • In the <span> tag, add being and end attributes to apply beat-by-beat timing to a word or phrase. See Timing below.

Apple Extension for Lyrics

Apple extension symbol Song Parts: To distinguish between song parts, add the itunes:song-part attribute to a <div> block to note its compositional purpose in the song.

Example: <div itunes:song-part="Chorus">

You can use any value you want for the itunes:song-part attribute, but Apple recommends the following values:

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

Agent

Add the ttm:agent attribute to any <p> and <span> element to indicate which artist is performing the contents.

Timing

Optionally add timing to the lyrics so that the lyrics can be synchronized to the timing of the words sung by the singers, like the display of lyrics in a sing-along.

A time value is expressed as a Synchronized Multimedia Integration Language (SMIL) full or partial clock-value:

(Hours ":")? Minutes ":" Seconds ("." Fraction up to 3 digits)?

Specifying hours and fractions of seconds is optional (as indicated by the ?).

Rules for timing

Text and Whitespace

White space in the document is processed according to rules defined by [XML 1.0], §2.10, White Space Handling.

Apple extension symbol Apple strongly recommends that you adhere to the xml:space="default" rules and refrain from specifying XML whitespace handling attributes.