Multi-Agent Lyrics and Duets

Assign lines to different vocalists using ttm:agent. Covers duets, features, group vocals, and overlapping lines.

Most songs have one vocalist. Some have two, three, or more. Duets, group vocals, features, and call-and-response parts all need a way to mark who is singing which line. TTML handles this with agents.

What an agent is

An agent is a named participant in the song. Each agent has an xml:id, a type, and an optional ttm:name. Every lyric line can reference one agent using the ttm:agent attribute.

<ttm:agent xml:id="v1" type="person">
  <ttm:name>Lead vocalist</ttm:name>
</ttm:agent>
<ttm:agent xml:id="v2" type="person">
  <ttm:name>Featured artist</ttm:name>
</ttm:agent>

Declare agents in the <metadata> block inside <head>. Reference them from lines in the <body>.

Agent types

The type attribute describes what kind of entity is singing:

person: a named individual (most common)
group: a band or choir singing together
character: a fictional character in a narrative song
organization: an institutional voice
other: fallback for anything else

Assigning lines

Each line gets one agent. The attribute lives on the <p> element:

<p begin="00:00:12.000" end="00:00:15.000" ttm:agent="v1">
  Lead singer takes this line
</p>
<p begin="00:00:15.000" end="00:00:18.000" ttm:agent="v2">
  Featured artist responds
</p>

You can alternate agents line by line. Apple Music uses the agent to position the line visually, typically with different singers' lines rendering on different sides of the screen.

Duets with overlapping lines

If two singers sing at the same time on different lines, keep them in separate <p> elements with overlapping timing:

<p begin="00:00:12.000" end="00:00:15.000" ttm:agent="v1">
  First vocalist's part
</p>
<p begin="00:00:12.500" end="00:00:15.200" ttm:agent="v2">
  Second vocalist at the same time
</p>

If they sing the same line together, assign the line to a group agent instead of splitting.

Group vocals

For choruses where everyone sings together, declare a group agent and use it for the group parts:

<ttm:agent xml:id="v1" type="person">
  <ttm:name>Lead</ttm:name>
</ttm:agent>
<ttm:agent xml:id="v2" type="person">
  <ttm:name>Feature</ttm:name>
</ttm:agent>
<ttm:agent xml:id="group" type="group">
  <ttm:name>Both</ttm:name>
</ttm:agent>

Then tag chorus lines with ttm:agent="group". Verses stay tagged with the individual agents.

Agents and background vocals

Background vocals use ttm:role="x-bg", not a separate agent. The background span inherits the paragraph's agent. If the background part is sung by a different person than the main line, you have a design choice: put it on a separate <p> with the correct agent, or accept the inheritance.

In practice, most platforms render background vocals as secondary content regardless of agent, so agent attribution for x-bg content is rarely visible.

Authoring agents in CallEditor

The settings modal has an agent editor. Add one agent per vocalist on the song, give each a clear name, and pick the right type. In the edit view, every line has an agent dropdown.

Tag agents before you sync. Retagging a hundred lines after the fact is slow; tagging them during the initial text pass costs nothing.

Ready to try it?