@braccato/parsers

Lyrics format parsers for TTML, LRC, SRT, QRC, and plain text, with automatic format detection. Produces the Lyric[] array that @braccato/core renders.

The parsers guide shows how to parse the response from each Better Lyrics API provider.

Install

npm i @braccato/parsers

Usage

import { detectParser } from "@braccato/parsers";

const parser = detectParser(inputText);
const lyrics = parser.parse(inputText, durationMs);

Or use a specific parser directly:

import { TTMLParser, LRCParser, SRTParser, QRCParser, PlainParser } from "@braccato/parsers";

const lyrics = TTMLParser.parse(ttmlString);

Parser Interface

All parsers implement:

interface LyricParser {
  parse(input: string, duration?: number): Lyric[];
  metadata(input: string): LyricMetadata;
  detect(input: string): boolean;
}

metadata reads what the file says about the song rather than its lines, which today is who wrote it. songwriters is empty when the file credits nobody:

const { songwriters } = detectParser(inputText).metadata(inputText); // ["Max Martin", "Savan Kotecha"]

Names that LRC and QRC hold as free text are split on /, 、, ， and ,. Every format drops duplicates and keeps the order the file gives.

detectParser tries each format in priority order: TTML, LRC, SRT, QRC, Plain. The same rules are exported on their own as detectFormat from the dependency-free @braccato/parsers/format subpath, which returns "ttml" | "lrc" | "srt" | "qrc" | "plain" without loading the XML parser.

TTMLParser.parse ignores its duration argument, because a TTML document states its own duration on <body dur>. Pass a duration through parseTTMLContent instead when the document omits it.

Format specifics

TTML

parseTTMLContent returns the parsed lines along with whether the document is word synced and the language it declares:

import { parseTTMLContent } from "@braccato/parsers";

const { lyrics, isWordSynced, language } = parseTTMLContent(ttmlString, {
  songDurationMs: 214000, // only used when <body> carries no dur
  instrumentalGapMs: 5000, // silence longer than this becomes an instrumental line
});

Instrumental lines are inserted whether or not the document states a duration. This changed in 0.2.0: 0.1.x only inserted them for a document whose <body> carried a dur, and the implementation this package was rewritten from does not gate them, so the gate is gone. A document with no dur now gains an intro instrumental when its first line starts more than instrumentalGapMs in, and one between any two lines separated by more than that. The outro is the exception, since nothing states where the song ends: pass songDurationMs to get it.

It reads syllable timing, ttm:role="x-bg" background vocals, ttm:agent (mapped to stable vocalist slots v1, v2, and v1000 for a group), explicit flags from either explicit or AMLL's obscene, itunes:key, translations and transliterations. Namespace prefixes that a document uses without declaring are recovered rather than rejected, and times may be clock values or offset times such as 432.25s, 5m or 250ms.

LRC

LRCParser.parse runs a set of timing fixers suited to Musixmatch word by word lyrics. For a source whose timings are already clean, use parseLRC, which returns the document exactly as stated:

import { parseLRC, lrcFixers } from "@braccato/parsers";

const lyrics = parseLRC(lrcText, durationMs, {
  instrumentalGapMs: 5000, // silence longer than this becomes an instrumental line
});
lrcFixers(lyrics); // optional, mutates in place

Instrumental lines follow the same rule as TTML. A blank timed line, or one holding only music notes, is not a lyric: it ends the line before it, and the silence it leaves becomes an instrumental line when it runs longer than instrumentalGapMs. Blank lines in a row make one break. In enhanced LRC, a timestamp with nothing after it closes the last word and the line, so the silence after it counts without a blank line. An intro is added when the first line starts after the threshold. An outro needs the last line to state where it ends, through a closing timestamp or a trailing blank line, because a plain last line runs to the end of the song.

QRC

QRCParser.parse accepts either the <QrcInfos> envelope QQ Music returns or a bare QRC body. Pass song metadata through parseQRC to drop the opening lines that only echo the title or artist:

import { parseQRC } from "@braccato/parsers";

const lyrics = parseQRC(qrcXml, durationMs, { title: "Song", artist: "Artist" });

Singer prefixes (Name: at the head of a line) become agents and are stripped from the text, sticking to the following lines until the next one appears. Credit lines are dropped.

See the full documentation for type definitions.