The club isn't the best place to find a lover
` - Line element Each `
` represents a line of lyrics:
- `begin` - Start time of the line
- `end` - End time of the line
### `` - Word element
Each `` within a line represents a word:
- `begin` - Start time of the word
- `end` - End time of the word
- Text content is the word itself (including trailing spaces)
## Important: whitespace handling
**Do not format or pretty-print the TTML response.**
The response uses whitespace between `` elements to represent spaces between syllables/words. This whitespace is not enclosed in tags. If you format the XML (for example with a pretty-printer), you lose these spaces and break the syllable sync.
Keep the original string exactly as received. When parsing, use the raw `textContent` of each span, which includes the intended whitespace.
## Time format
Times can appear in two formats:
- `HH:MM:SS.mmm` - e.g., `00:01:30.500` = 90.5 seconds
- `M:SS.mmm` - e.g., `1:16.656` = 76.656 seconds
Your parser should handle both. The JavaScript example below does.
## Parsing example (JavaScript)
[`@braccato/parsers`](https://docs.betterlyrics.org/braccato/parsers) is the parser Better Lyrics uses for these responses. It handles background vocals, agents, transliterations and whitespace for you. The example below shows how to do it by hand.
```javascript
function parseTTML(ttmlString) {
const parser = new DOMParser();
const doc = parser.parseFromString(ttmlString, 'text/xml');
const lines = [];
doc.querySelectorAll('p').forEach(p => {
const agent = p.getAttribute('ttm:agent'); // Agent ID as defined in metadata (v1, v2, v1000, etc.)
const words = [];
// Recursively collect spans, tracking background vocal context
function collectSpans(element, isBackground = false) {
element.childNodes.forEach(node => {
if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'span') {
const isBg = isBackground || node.getAttribute('ttm:role') === 'x-bg';
const begin = node.getAttribute('begin');
if (begin) {
// This is a timed span (word)
words.push({
text: node.textContent,
begin: parseTime(begin),
end: parseTime(node.getAttribute('end')),
isBackground: isBg
});
} else {
// This is a wrapper span, recurse into it
collectSpans(node, isBg);
}
}
});
}
collectSpans(p);
lines.push({
begin: parseTime(p.getAttribute('begin')),
end: parseTime(p.getAttribute('end')),
agent,
words
});
});
return lines;
}
function parseTime(timeStr) {
// Handles "HH:MM:SS.mmm", "M:SS.mmm", "SS.mmm"
const parts = timeStr.split(':');
let seconds = 0;
if (parts.length === 3) {
seconds = parseInt(parts[0]) * 3600 +
parseInt(parts[1]) * 60 +
parseFloat(parts[2]);
} else if (parts.length === 2) {
seconds = parseInt(parts[0]) * 60 +
parseFloat(parts[1]);
} else {
seconds = parseFloat(parts[0]);
}
return Math.round(seconds * 1000); // Return milliseconds
}
```
## RTL language support
For right-to-left languages (Arabic, Hebrew, Persian, etc.), the TTML document includes language attributes:
```xml
...
```
Check the `xml:lang` attribute to determine text direction. Common RTL language codes: `ar`, `he`, `fa`, `ur`.
## Multiple speakers
Songs with multiple vocalists use the `ttm:agent` attribute on ` ` elements to identify which speaker is singing each line:
```xml
First
vocalist
Second
vocalist
Lead lyrics
background vocals