Files
otunes/packages/convex/client/lyrics.ts
T
joshuafhigginsandClaude Opus 5.5 Verified 719fbc4796 fix: fill line-timed lyrics as they play
Only word-timed lyrics had words to fill, so line-timed songs never
animated. Their lines now get words spread over them by length.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 01:21:52 -05:00

260 lines
8.0 KiB
TypeScript

/**
* Lyrics as tagged in the music files: plain text, LRC (`[mm:ss.xx]line`), or
* word-timed LRC (`<mm:ss.xx>word`). The server stores that text unchanged and
* clients parse it here, so a downloaded file's tag and the server copy read
* the same.
*/
export type LyricWord = {
/** Includes its trailing space, so a line's words join back into its text. */
text: string
start: number
end: number
}
export type LyricLine = {
text: string
/** Seconds; `null` for plain lyrics. */
start: number | null
/**
* The line's words as they are sung. Line-timed lyrics get estimated
* ones (see `estimateWords`); plain lyrics have none.
*/
words: LyricWord[] | null
}
export type Lyrics = {
/** How the source was timed, whatever `words` were estimated. */
synced: "none" | "line" | "word"
lines: LyricLine[]
}
const LINE_STAMP = /^\[(\d+):(\d+(?:[.:]\d+)?)\]/
const WORD_STAMP = /<(\d+):(\d+(?:[.:]\d+)?)>/g
const HAS_WORD_STAMP = /<\d+:\d+(?:[.:]\d+)?>/
const ID_TAG = /^\[[a-z]+:.*\]$/i
/** A rough singing pace, so a line-timed line's fill tracks its words. */
const ESTIMATED_SECONDS_PER_CHAR = 0.07
function seconds(minutes: string, rest: string) {
return Number(minutes) * 60 + Number(rest.replace(":", "."))
}
/** Splits `<t>word <t>word<t>` into words; the last stamp ends the last word. */
function parseWords(body: string): LyricWord[] {
const stamps = [...body.matchAll(WORD_STAMP)]
const words: LyricWord[] = []
for (let i = 0; i < stamps.length; i++) {
const stamp = stamps[i]
const textStart = stamp.index + stamp[0].length
const next = stamps[i + 1]
const text = body.slice(textStart, next?.index ?? body.length)
const start = seconds(stamp[1], stamp[2])
if (text.trim()) {
words.push({
text,
start,
end: next ? seconds(next[1], next[2]) : start,
})
}
}
return words
}
export function parseLyrics(raw: string): Lyrics | null {
const rows = raw.replace(/\r\n?/g, "\n").split("\n")
const timed = rows.some((row) => LINE_STAMP.test(row.trim()))
const wordTimed = rows.some((row) => HAS_WORD_STAMP.test(row))
if (!timed && !wordTimed) {
const lines = rows.map((row) => ({
text: row.trim(),
start: null,
words: null,
}))
// Blank rows between stanzas stay as spacing; ones at the ends go.
while (lines[0]?.text === "") lines.shift()
while (lines.at(-1)?.text === "") lines.pop()
return lines.length > 0 ? { synced: "none", lines } : null
}
const lines: LyricLine[] = []
for (const row of rows) {
let body = row.trim()
if (ID_TAG.test(body) && !LINE_STAMP.test(body)) continue
// A line may repeat under several stamps: `[00:12.00][01:30.00]Chorus`.
const starts: number[] = []
for (let match = LINE_STAMP.exec(body); match;) {
starts.push(seconds(match[1], match[2]))
body = body.slice(match[0].length)
match = LINE_STAMP.exec(body)
}
const words = wordTimed ? parseWords(body) : []
const text = (
words.length > 0 ? words.map((word) => word.text).join("") : body
).trim()
if (!text) continue
if (starts.length === 0 && words.length > 0) starts.push(words[0].start)
for (const start of starts) {
const shift = words.length > 0 ? start - words[0].start : 0
lines.push({
text,
start,
words:
words.length > 0
? words.map((word) => ({
...word,
start: word.start + shift,
end: word.end + shift,
}))
: null,
})
}
}
lines.sort((a, b) => a.start! - b.start!)
if (lines.length === 0) return null
const synced = lines.every((line) => line.words) ? "word" : "line"
if (synced === "line") estimateWords(lines)
return { synced, lines }
}
/**
* Gives timed lines without word timing words spread over them by length,
* at a singing pace but never past the next line, so they fill as they play.
*/
function estimateWords(lines: LyricLine[]) {
lines.forEach((line, index) => {
if (line.words || line.start === null) return
const next = lines[index + 1]?.start ?? Infinity
const duration = Math.min(
next - line.start,
line.text.length * ESTIMATED_SECONDS_PER_CHAR
)
const perChar = duration / line.text.length
let at = line.start
line.words = (line.text.match(/\S+\s*/g) ?? []).map((text) => {
const start = at
at += text.length * perChar
return { text, start, end: at }
})
})
}
/** The text without timestamps, one line per row, for search and snippets. */
export function plainLyrics(lyrics: Lyrics) {
return lyrics.lines.map((line) => line.text).join("\n")
}
/** How well a tag's lyrics are timed, to keep the best of a song's files. */
export function lyricsRank(raw: string | null) {
const synced = raw ? parseLyrics(raw)?.synced : undefined
return synced === "word" ? 3 : synced === "line" ? 2 : synced ? 1 : 0
}
/**
* The line playing at `time` (the last one started), or -1 before the first.
* Plain lyrics never have one.
*/
export function activeLineIndex(lyrics: Lyrics, time: number) {
let active = -1
for (let i = 0; i < lyrics.lines.length; i++) {
const start = lyrics.lines[i].start
if (start === null || start > time) break
active = i
}
return active
}
/** When the highlighted line or word next changes after `time`, if ever. */
export function nextLyricsChange(lyrics: Lyrics, time: number) {
let next = Infinity
for (const line of lyrics.lines) {
if (line.start !== null && line.start > time) {
next = Math.min(next, line.start)
break
}
for (const word of line.words ?? []) {
if (word.start > time) {
next = Math.min(next, word.start)
break
}
}
}
return next
}
/**
* While audio plays on from `time` seconds, calls `onChange` with the playback
* time whenever the highlighted line or word changes. Players report progress
* only a few times a second, which is too coarse for word timing. Returns a
* function that stops it.
*/
export function followLyrics(
lyrics: Lyrics,
time: number,
onChange: (time: number) => void
) {
const startedAt = Date.now() - time * 1000
let timer: ReturnType<typeof setTimeout> | undefined
const schedule = (from: number) => {
const next = nextLyricsChange(lyrics, from)
if (!Number.isFinite(next)) return
timer = setTimeout(
() => {
const now = (Date.now() - startedAt) / 1000
onChange(now)
schedule(now)
},
(next - from) * 1000
)
}
if (lyrics.synced !== "none") schedule(time)
return () => clearTimeout(timer)
}
/** Lowercase words of a search, for matching lyrics the way the search index does. */
function searchTerms(query: string): string[] {
return query.toLowerCase().match(/[\p{L}\p{N}']+/gu) ?? []
}
const SNIPPET_LEAD = 24
export type LyricsMatch = {
/** The matched line, trimmed to start near the match. */
snippet: string
/** Whether the line holds the query as typed, not just its words. */
exact: boolean
}
/**
* Where a search matched the lyrics: a line holding the query as typed, or
* else a line holding every word of it (the last may be a prefix, as when
* typing). Null when no single line does.
*/
export function matchLyrics(plain: string, query: string): LyricsMatch | null {
const needle = query.trim().toLowerCase()
const terms = searchTerms(needle)
const last = terms.at(-1)
if (!needle || last === undefined) return null
let loose: string | null = null
for (const line of plain.split("\n")) {
const column = line.toLowerCase().indexOf(needle)
if (column !== -1) {
const snippet =
column > SNIPPET_LEAD
? `…${line.slice(column - SNIPPET_LEAD).trimStart()}`
: line.trim()
return { snippet, exact: true }
}
if (loose === null) {
const words = searchTerms(line)
const hasAll =
terms.slice(0, -1).every((term) => words.includes(term)) &&
words.some((word) => word.startsWith(last))
if (hasAll) loose = line.trim()
}
}
return loose === null ? null : { snippet: loose, exact: false }
}