Related: #402 (Lyrics Acquisition). This spec is the list-stage presentation.

Problem Statement

AMLL’s word-timed lyrics only help me if the stage can show them. OpenKara already highlights words and already has a list lyrics panel I know how to use. I do not want the whole stage replaced by an Apple Music page. I also do not want OpenKara to change license just to borrow a player. When the lyrics file already carries romanization, I want that romanization on the switch I already use. I do not want a second translation line or a new control.

Solution

Keep the OpenKara list lyrics stage. Keep karaoke fill, spring follow, audience view, AirPlay, offset, font size, and the romanize toggle. When lyrics include Supplied Romanization, that text is what the toggle shows. Word-timed tokens from Lyrics Acquisition light up through the fill that already exists. OpenKara stays Apache-2.0. Official AMLL player packages are not dependencies.

User Stories

1. As a singer, I want the lyrics list I already know, so that adding word-timed lyrics does not change how I find the next line.
2. As a singer, I want the active word to fill as I sing, so that word-timed lyrics feel like karaoke rather than a line flip.
3. As a singer, I want background vocal tokens to stay on the existing secondary line, so that harmony does not steal the main line.
4. As a singer of Japanese or other non-Latin lyrics, I want AMLL’s romanization on the existing romanize toggle, so that I can read pronunciation without a new control.
5. As a singer, I want complete Supplied Romanization to skip the local romanizer, so that a hand-tuned reading is not overwritten by a machine guess.
6. As a singer, I want incomplete Supplied Romanization to keep the supplied lines and only fill the gaps locally, so that a half-complete TTML file is still better than nothing.
7. As a singer who changes catalog language, I want complete Supplied Romanization to stay, so that a language refresh does not clobber official readings.
8. As a singer of Latin-script songs, I want the romanize toggle to stay quiet when nothing needs romanizing, so that the overlay does not invent noise.
9. As a singer, I do not want a translation line under every lyric, so that the stage stays readable at karaoke size.
10. As a singer, I want left and centered alignment to keep working, so that my current layout preference survives word-timed lyrics.
11. As a singer, I want font size steps to keep working on word-timed lines, so that a hall display stays legible.
12. As a singer, I want clicking a line to seek, so that I can jump without touching the timeline.
13. As a singer who scrolls the list, I want follow to pause and then resume, so that I can look ahead without fighting the engine.
14. As a singer who prefers reduced motion, I want follow to jump instead of springing, so that the stage stays calm.
15. As an audience member on the fullscreen stage, I want the same winning lines at audience type size, so that I am not on a second lyric engine.
16. As an audience member, I want unsynced plain text to keep paging, so that speeches and unsynced songs do not break.
17. As a singer using AirPlay, I want the same lines and romanization to reach the remote screen, so that the TV matches the desk.
18. As a singer, I want offset and edit controls to stay where they are, so that I can still fix timing and wording.
19. As a catalog owner, I want sidecar or manual TTML to show Supplied Romanization even when AMLL was never searched, so that a file I wrote is enough.
20. As a singer, I want x-translation text to stay out of the sung line, so that a Chinese gloss does not become the lyric I am supposed to sing.
21. As a singer, I want ruby to stay out of Supplied Romanization, so that furigana does not replace the romanize overlay.
22. As a singer, I want background-line romanization ignored for now, so that a harmony x-roman does not attach to the main overlay.
23. As a singer, I want inline romanization to beat a sidecar transliteration for the same line, so that the closer annotation wins.
24. As a singer, I want mixed Line/Word TTML to restore word spans inside a Word child, so that a file with a line-timed wrapper can still karaoke.
25. As a maintainer, I want OpenKara to stay Apache-2.0, so that we can keep shipping under the current license.
26. As a maintainer, I want any PR that adds an AGPL AMLL npm package to be rejected, so that a convenience import cannot relicense the app.
27. As a maintainer, I want an ADR that says we implement karaoke presentation ourselves, so that the next engineer does not “just add LyricPlayer.”
28. As a singer, I do not want Apple Music center-lock, blur of past lines, or hidden past lines in this change, so that the stage does not become a new product surface.
29. As a singer, I do not want interlude dots or per-line duet flip in this change, so that v1 stays the list I already use.
30. As a singer, I do not want a Pixi or mesh-gradient album background behind lyrics, so that playback stays light and on-brand.
31. As a singer, I want existing karaoke fill to keep working on sidecar LYS and enhanced LRC, so that AMLL is not the only path to word highlight.
32. As a singer, I want companion romanization split of paired LRC lines to keep working, so that today’s Latin companion files do not regress.
33. As a singer on a remote audience, I want romanize visibility to stay in sync, so that turning the overlay on at the desk updates the hall.
34. As a keyboard user, I want line seek to remain a real button with a name, so that the panel stays accessible.
35. As a singer, I want empty and loading states to stay the current copy, so that a miss still tells me to add lyrics rather than showing a foreign player chrome.

Implementation Decisions

• The lyrics stage stays the OpenKara list. Do not mount AMLL LyricPlayer, React bindings, Vue bindings, or the full prebuilt player. Do not copy that source.
• OpenKara stays Apache-2.0. Record ADR 0028: do not depend on AGPL AMLL player or parser packages; consume the HTTP API and the published TTML format only. License review rejects those dependencies.
• Karaoke-relevant AMLL behavior is implemented in the existing fill and line model. Word fade stays the current karaoke fill. Background vocals stay bg_words. Do not rewrite scroll; the current lyrics engine (spring follow, user-scroll pause, reduced motion) stays.
• Add optional per-line roman on the lyric line type, same null style as section, always serialized. This is the IPC shape for Supplied Romanization. AirPlay ignores the field the same way it ignores section.
• TTML extraction: collect x-roman that is not inside background or translation; collect iTunes transliteration sidecar text by line key, prefer a Latn language, concatenate descendant text without inventing spaces; inline roman wins over sidecar; ignore x-translation for display; ignore ruby as Supplied Romanization; ignore x-roman inside background vocals in this spec.
• Timing flags: a Word value on a div must clear both the div line-timing flag and the current line-timing flag, or every child p snaps back to Line and drops word spans. A Word value on a p clears only that line.
• Overlay seed maps over the kept lines (line.roman first, then any companion romanization). Do not map the companion array alone; for AMLL/TTML that array is empty and would drop supplied text.
• When every line that needs romanization has Supplied Romanization, skip the local romanizer, including on a catalog-language refresh. When some lines are missing it, merge line.roman over the local result so supplied text cannot be overwritten.
• No translation line. No Apple Music center-active layout, blur, hide-past-lines, interlude dots, or duet right-align in this spec. Those are a later product surface and need their own ADR plus the interaction profile.
• This spec does not change Lyrics Acquisition order. It consumes whatever payload Lyrics Acquisition already returns.

Testing Decisions

A good test asserts what the singer sees from a lyrics payload: which overlay strings appear, whether the local romanizer ran, whether word tokens still fill, and whether companion LRC split is unchanged. Do not assert CSS class names or AMLL package internals. Do not add a second player test harness.

Primary seam: the lyrics session after a payload that already contains roman and words. This is the existing session seam used for companion romanization and the romanize toggle. Assert complete supplied skips the romanizer; incomplete supplied plus an empty companion array still shows the supplied lines after toggle; a language refresh does not clobber complete supplied.

Parser seam (already exists for TTML): given TTML fixtures, the parsed lines carry roman and words under the extraction rules above, and translation/ruby/background-roman stay out of those fields.

Do not add a visual snapshot seam for an AMLL player. Existing lyric-line and karaoke-fill tests remain the check that word tokens still highlight.

Prior art: lyrics-session romanize tests, companion-romanization tests, TTML parser tests, lyric-line tests, IPC contract field tests.

Out of Scope

• Lyrics Acquisition, AMLL HTTP, matching, Word-timed Upgrade, and the probe column (companion spec).
• Relicensing OpenKara.
• Any [@applemusic-like-lyrics](/applemusic-like-lyrics) dependency or a copied player.
• Translation display, Apple Music layout, interlude dots, duet alignment, Pixi backgrounds.
• New lyrics commands, new settings, or new panel chrome.

Further Notes

Companion spec: AMLL as the first online source in Lyrics Acquisition, with Word-timed Upgrade of cached online line-timed lyrics. That spec is what creates most word-timed payloads. This spec is what makes those payloads singable on the stage we already have.

Domain terms: Supplied Romanization, Word-timed Lyrics, Line-timed Lyrics. Do not write “official romanization,” “TTML roman,” or “AMLL lyrics” for the overlay.