musicdl-catalog-sync-suite/Music_Server/docs/superpowers/plans/2026-05-01-music-server-lyrics-inline-implementation.md

Music_Server Inline Lyrics Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make Music_Server include local .lrc content as rawLrc in distributed song items and keep the MusicFree plugins passing that field through.

Architecture: Extend catalog track queries to expose the best local file locator, resolve a sibling .lrc under LOCAL_LIBRARY_ROOT, and inject the text into the existing song payload builder. Update both served plugin assets so their mapMusicItem() output preserves rawLrc.

Tech Stack: Python 3.11, FastAPI, sqlite3, unittest, plain JavaScript plugin assets.

---

Task 1: Add failing backend and plugin tests

Files:

• Modify: tests/test_mf_catalog_routes.py

• Modify: tests/test_plugin_routes.py

• Add route assertions that expect rawLrc when a same-name .lrc exists beside a local audio file.

• Add route assertions that verify requests still succeed without LOCAL_LIBRARY_ROOT.

• Add plugin asset assertions that both served JS assets contain rawLrc mapping code.

• Run only the new/updated tests and confirm they fail for the expected missing-lyrics behavior.

Task 2: Implement inline lyric loading

Files:

• Modify: src/music_server/services/catalog_reader.py

• Modify: src/music_server/routes/mf_catalog.py

• Extend track row queries to expose the preferred active local_fs locator for each song.

• Add a helper that safely resolves a sibling .lrc under LOCAL_LIBRARY_ROOT and reads it as text.

• Inject rawLrc into _to_music_item() only when a lyric file is present.

• Re-run the focused backend tests and confirm they pass.

Task 3: Preserve lyrics in plugin assets

Files:

• Modify: src/music_server/plugin_assets/music_server.js

• Modify: src/music_server/plugin_assets/music_server_lan.js

• Test: tests/test_plugin_routes.py

• Update mapMusicItem() in both plugin assets to copy rawLrc from the server payload.

• Re-run the plugin asset tests and confirm they pass.

Task 4: Verify the feature end to end in repo tests

Files:

• Modify: none

• Run the focused unittest command for test_mf_catalog_routes and test_plugin_routes.

• If those pass, run test_catalog_reader.py as a regression check for reader query changes.

• Record any deployment-only follow-up separately; do not expand scope in code.