From b3a4da4b97eadf80ac3c79d0f14e55bd6c8e6d26 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Padez?= <andre.padez@gmail.com>
Date: Mon, 27 Jul 2026 14:51:58 +0000
Subject: [PATCH] music indexer: index track lyrics (.lrc/.txt sidecars +
 embedded)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each track's lyrics are resolved and cached at cache/<rel>/lyrics/<file>.<lrc|txt>,
with the format recorded as `lyrics: 'lrc'|'txt'` on the meta.tracks entry.

Precedence: external "<base>.lrc" > external "<base>.txt" > embedded tag
(lyrics / lyrics-<lang> / unsyncedlyrics — ffprobe now reads all format tags).
Content that contains [mm:ss] lines is stored as lrc even from a .txt/embedded
source. Only track-matching sidecars affect the version signature (a stray
notes.txt is ignored). Lyrics dir is wiped+regenerated per rebuild; new
`lyricsIndexed` counter.

Served by GET /api/music/lyrics?path=<rel>&file=<track> (text/plain +
X-Lyrics-Format header, ETag=<v>, 304, 404 when none).

Verified end-to-end: external .lrc wins over embedded; embedded → plain txt;
unmatched .txt ignored. MUSIC_API.md documents the field + endpoint.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 MUSIC_API.md                         |  18 ++++-
 src/servers/sidecar/music/index.ts   |  20 +++++
 src/servers/sidecar/music/indexer.ts | 108 +++++++++++++++++++++++----
 3 files changed, 129 insertions(+), 17 deletions(-)

diff --git a/MUSIC_API.md b/MUSIC_API.md
index f45dc94a..eb941bd1 100644
--- a/MUSIC_API.md
+++ b/MUSIC_API.md
@@ -96,7 +96,8 @@ Returns the album's `meta.json`. Sends `ETag: <v>`; a request with `If-None-Matc
       "album": "Back in Black",
       "track": "1",
       "year": "1980",
-      "durationSec": 312
+      "durationSec": 312,
+      "lyrics": "lrc"                       // present if lyrics exist: "lrc" = synced, "txt" = plain (see §2.3.2)
     }
     // …
   ],
@@ -134,6 +135,19 @@ A compressed frame grab for a video (≤600px, same treatment as covers), taken
 the video's filename within `<rel>` (URL-encode it). Sends `ETag: <v>`; `If-None-Match: <v>` → `304`; `404`
 when the video has no poster. Only request it when that video's `meta.videos[]` entry has a `poster` field.
 
+#### 2.3.2 Lyrics
+
+```
+GET /api/music/lyrics?path=<rel>&file=<track filename>
+```
+Plain-text body of the track's lyrics; the `X-Lyrics-Format` header is `lrc` (synced, `[mm:ss.xx]`-timestamped)
+or `txt` (plain). Sends `ETag: <v>`; `If-None-Match: <v>` → `304`; `404` when the track has no lyrics. Only
+request it when that track's `meta.tracks[]` entry has a `lyrics` field (`"lrc"`/`"txt"`).
+
+Sources, in precedence order (indexed at build time): an external **`<track basename>.lrc`** > external
+**`<track basename>.txt`** > **embedded** lyrics in the audio tags (`lyrics` / `lyrics-<lang>` /
+`unsyncedlyrics`). A `.txt` (or embedded) whose text actually contains `[mm:ss]` lines is served as `lrc`.
+
 ### 2.4 Discography (artist album grouping)
 
 For artist folders (manifest entry with `"disco": true`), this returns a map of **album folder → release
@@ -184,7 +198,7 @@ GET  /api/music/reindex/status   → IndexStatus snapshot
   "running": true,
   "startedAt": 1785034701973, "finishedAt": null,
   "foldersScanned": 45, "albumsBuilt": 12, "albumsSkipped": 3,
-  "tracksIndexed": 320, "videosIndexed": 4, "coversSaved": 12, "postersSaved": 4, "discographies": 3,
+  "tracksIndexed": 320, "videosIndexed": 4, "coversSaved": 12, "postersSaved": 4, "lyricsIndexed": 45, "discographies": 3,
   "currentPath": "Albums/AC-DC/[1980] Back in Black",
   "error": null
 }
diff --git a/src/servers/sidecar/music/index.ts b/src/servers/sidecar/music/index.ts
index 79c34442..90917117 100644
--- a/src/servers/sidecar/music/index.ts
+++ b/src/servers/sidecar/music/index.ts
@@ -13,6 +13,7 @@ import {
   coverFilePath,
   discographyFilePath,
   posterFilePath,
+  lyricsFilePath,
   onIndexProgress,
   buildReport,
 } from './indexer';
@@ -38,6 +39,7 @@ const DATA_PATH = process.env.DATA_PATH ?? join(process.cwd(), 'data');
 //   GET  /meta?path=<rel>                  album meta.json (IndexMeta). ETag: <v>; If-None-Match → 304.
 //   GET  /cover?path=<rel>                 compressed cover.jpg.       ETag: <v>; If-None-Match → 304.
 //   GET  /poster?path=<rel>&file=<video>   compressed video poster (frame grab). ETag: <v>; 304. 404 if none.
+//   GET  /lyrics?path=<rel>&file=<track>   track lyrics text (X-Lyrics-Format: lrc|txt). ETag: <v>; 304. 404 if none.
 //   GET  /discography?path=<artist rel>    artist discography.json (only where manifest entry has
 //                                          disco:true) = { artist, albums: { "<[year] album folder>":
 //                                          "<Type>" } }, Type ∈ Studio/Live/Compilation/Single/EP/…
@@ -166,6 +168,24 @@ const server = Bun.serve({
       return new Response(Bun.file(posterPath), { headers: { 'Content-Type': 'image/jpeg', ...(v ? { ETag: v } : {}) } });
     }
 
+    // Track lyrics (external .lrc/.txt sidecar or embedded, cached during indexing). Try synced first.
+    if (url.pathname === '/lyrics') {
+      const rel = url.searchParams.get('path');
+      const file = url.searchParams.get('file');
+      if (rel === null || !file) return new Response('path and file are required', { status: 400 });
+      for (const fmt of ['lrc', 'txt'] as const) {
+        const p = lyricsFilePath(rel, file, fmt);
+        if (p && (await Bun.file(p).exists())) {
+          const v = await albumVersion(rel);
+          if (v && req.headers.get('if-none-match') === v) return new Response(null, { status: 304 });
+          return new Response(Bun.file(p), {
+            headers: { 'Content-Type': 'text/plain; charset=utf-8', 'X-Lyrics-Format': fmt, ...(v ? { ETag: v } : {}) },
+          });
+        }
+      }
+      return new Response('Not found', { status: 404 });
+    }
+
     if (url.pathname === '/meta' || url.pathname === '/cover' || url.pathname === '/discography') {
       const rel = url.searchParams.get('path');
       if (rel === null) return new Response('path is required', { status: 400 });
diff --git a/src/servers/sidecar/music/indexer.ts b/src/servers/sidecar/music/indexer.ts
index e0cd193f..63b7ad5f 100644
--- a/src/servers/sidecar/music/indexer.ts
+++ b/src/servers/sidecar/music/indexer.ts
@@ -9,10 +9,12 @@ import { homedir } from 'node:os';
 // (relative to the Music root):
 //
 //   DATA_PATH/music/cache/<rel>/meta.json   { path, cover?, tracks: [{ file, title, artist, albumArtist,
-//                                             album, track, year, durationSec }],
-//                                             videos?: [{ file, title, durationSec, width, height }] }
+//                                             album, track, year, durationSec, lyrics?:'lrc'|'txt' }],
+//                                             videos?: [{ file, title, durationSec, width, height, poster? }] }
 //                                             (phone IndexMeta schema)
 //   DATA_PATH/music/cache/<rel>/cover.jpg    compressed (<=600px, jpeg q5)
+//   DATA_PATH/music/cache/<rel>/posters/<videofile>.jpg   video frame-grab thumbnails
+//   DATA_PATH/music/cache/<rel>/lyrics/<trackfile>.<lrc|txt>   external-sidecar or embedded lyrics
 //
 // A manifest (cache root) carries a per-album version `v` = hash of the album's source signature (track
 // name+size+mtime, cover size+mtime). It drives BOTH incremental build (skip unchanged albums) and the
@@ -44,6 +46,7 @@ export type IndexTrack = {
   track?: string;
   year?: string;
   durationSec?: number;
+  lyrics?: 'lrc' | 'txt'; // available lyrics format ('lrc' = synced/timestamped); text via /lyrics. Absent = none.
 };
 export type IndexVideo = {
   file: string;
@@ -105,6 +108,7 @@ export type IndexStatus = {
   videosIndexed: number;
   coversSaved: number;
   postersSaved: number;
+  lyricsIndexed: number;
   discographies: number; // artist discography.json files written
   currentPath: string;
   error: string | null;
@@ -149,6 +153,7 @@ const status: IndexStatus = {
   videosIndexed: 0,
   coversSaved: 0,
   postersSaved: 0,
+  lyricsIndexed: 0,
   discographies: 0,
   currentPath: '',
   error: null,
@@ -240,7 +245,7 @@ async function mapPool<T, R>(items: T[], limit: number, fn: (item: T) => Promise
   return out;
 }
 
-async function ffprobeTrack(absPath: string, file: string): Promise<IndexTrack> {
+async function ffprobeTrack(absPath: string, file: string): Promise<{ track: IndexTrack; lyricsText?: string }> {
   try {
     const proc = Bun.spawn(
       [
@@ -249,8 +254,9 @@ async function ffprobeTrack(absPath: string, file: string): Promise<IndexTrack>
         'error',
         '-print_format',
         'json',
+        // All format tags — so embedded lyrics (key varies: lyrics, lyrics-<lang>, unsyncedlyrics) come through.
         '-show_entries',
-        'format=duration:format_tags=title,artist,album,album_artist,track,date',
+        'format=duration:format_tags',
         absPath,
       ],
       { stdout: 'pipe', stderr: 'ignore' },
@@ -264,18 +270,29 @@ async function ffprobeTrack(absPath: string, file: string): Promise<IndexTrack>
     for (const [k, val] of Object.entries(fmt.tags ?? {})) tags[k.toLowerCase()] = val;
     const durNum = fmt.duration ? Math.round(parseFloat(fmt.duration)) : undefined;
     const yearMatch = tags.date?.match(/\d{4}/);
+    // Embedded lyrics: USLT/foobar keys — `lyrics`, `lyrics-<lang>`, `unsyncedlyrics`.
+    let lyricsText: string | undefined;
+    for (const [k, val] of Object.entries(tags)) {
+      if (/^(lyrics|unsyncedlyrics)($|[-_])/.test(k) && val && val.trim()) {
+        lyricsText = val;
+        break;
+      }
+    }
     return {
-      file,
-      title: tags.title || undefined,
-      artist: tags.artist || undefined,
-      albumArtist: tags.album_artist || undefined,
-      album: tags.album || undefined,
-      track: tags.track || undefined,
-      year: yearMatch ? yearMatch[0] : undefined,
-      durationSec: Number.isFinite(durNum) ? durNum : undefined,
+      track: {
+        file,
+        title: tags.title || undefined,
+        artist: tags.artist || undefined,
+        albumArtist: tags.album_artist || tags.albumartist || undefined,
+        album: tags.album || undefined,
+        track: tags.track || undefined,
+        year: yearMatch ? yearMatch[0] : undefined,
+        durationSec: Number.isFinite(durNum) ? durNum : undefined,
+      },
+      lyricsText,
     };
   } catch {
-    return { file };
+    return { track: { file } };
   }
 }
 
@@ -370,6 +387,41 @@ async function generateVideoPoster(srcAbs: string, destAbs: string, durationSec?
   }
 }
 
+// ── Lyrics ──
+
+const LRC_TIMESTAMP_RE = /^\s*\[\d{1,2}:\d{2}(?:[.:]\d{1,3})?\]/m;
+const isLrc = (text: string): boolean => LRC_TIMESTAMP_RE.test(text);
+
+/**
+ * Resolve a track's lyrics and cache them at cache/<rel>/lyrics/<trackfile>.<lrc|txt>. Precedence:
+ * external "<base>.lrc" > external "<base>.txt" > embedded (from the audio tags). Returns the cached
+ * format, or null if none. `.txt`/embedded content that actually contains [mm:ss] lines is stored as .lrc.
+ */
+async function resolveTrackLyrics(
+  dirAbs: string,
+  lyricsDir: string,
+  trackFile: string,
+  folderFiles: Set<string>,
+  embedded: string | undefined,
+): Promise<'lrc' | 'txt' | null> {
+  const base = trackFile.replace(/\.[^.]+$/, '');
+  const write = async (fmt: 'lrc' | 'txt', text: string) => {
+    await mkdir(lyricsDir, { recursive: true });
+    await writeFile(join(lyricsDir, `${trackFile}.${fmt}`), text);
+    return fmt;
+  };
+  if (folderFiles.has(`${base}.lrc`)) {
+    const text = await readFile(join(dirAbs, `${base}.lrc`), 'utf8').catch(() => null);
+    if (text?.trim()) return write('lrc', text);
+  }
+  if (folderFiles.has(`${base}.txt`)) {
+    const text = await readFile(join(dirAbs, `${base}.txt`), 'utf8').catch(() => null);
+    if (text?.trim()) return write(isLrc(text) ? 'lrc' : 'txt', text);
+  }
+  if (embedded?.trim()) return write(isLrc(embedded) ? 'lrc' : 'txt', embedded);
+  return null;
+}
+
 // ── Build ──
 
 export async function buildMusicIndex(): Promise<IndexStatus> {
@@ -385,6 +437,7 @@ export async function buildMusicIndex(): Promise<IndexStatus> {
     videosIndexed: 0,
     coversSaved: 0,
   postersSaved: 0,
+  lyricsIndexed: 0,
     discographies: 0,
     currentPath: '',
     error: null,
@@ -420,7 +473,7 @@ export async function buildMusicIndex(): Promise<IndexStatus> {
       console.error(`[music] resync failed after ${r.elapsedSec}s: ${r.error}`);
     } else {
       console.log(
-        `[music] resync done — ${r.built} built, ${r.skipped} skipped, ${r.coversSaved} covers, ${r.tracksIndexed} tracks, ${r.videosIndexed} videos, ${r.foldersScanned} folders in ${r.elapsedSec}s`,
+        `[music] resync done — ${r.built} built, ${r.skipped} skipped, ${r.coversSaved} covers, ${r.tracksIndexed} tracks, ${r.videosIndexed} videos, ${status.lyricsIndexed} lyrics, ${r.foldersScanned} folders in ${r.elapsedSec}s`,
       );
     }
   }
@@ -484,6 +537,15 @@ async function walk(dirAbs: string, prev: Manifest, next: Manifest): Promise<voi
 
   const hasDisco = files.some((e) => e.name === DISCO_FILE);
 
+  // External lyrics sidecars (.lrc/.txt) that match a track's basename — matched to tracks in the build
+  // below. Only track-matching ones count (a stray notes.txt won't affect the version).
+  const fileSet = new Set(files.map((e) => e.name));
+  const audioBases = new Set(audio.map((n) => n.replace(/\.[^.]+$/, '')));
+  const lyricsSidecars = files.map((e) => e.name).filter((n) => {
+    const m = /^(.*)\.(lrc|txt)$/i.exec(n);
+    return m !== null && audioBases.has(m[1]!);
+  });
+
   if (audio.length || video.length || coverName || hasDisco) {
     // Source signature → version (includes _discography.md so regenerating it bumps v — isolated from
     // the album meta/cover of the tracks underneath).
@@ -496,6 +558,10 @@ async function walk(dirAbs: string, prev: Manifest, next: Manifest): Promise<voi
       const st = await stat(join(dirAbs, name)).catch(() => null);
       if (st) sigParts.push(`vid:${name}:${st.size}:${Math.round(st.mtimeMs)}`);
     }
+    for (const name of [...lyricsSidecars].sort()) {
+      const st = await stat(join(dirAbs, name)).catch(() => null);
+      if (st) sigParts.push(`lyr:${name}:${st.size}:${Math.round(st.mtimeMs)}`);
+    }
     if (coverName) {
       const st = await stat(join(dirAbs, coverName)).catch(() => null);
       if (st) sigParts.push(`cover:${coverName}:${st.size}:${Math.round(st.mtimeMs)}`);
@@ -529,8 +595,16 @@ async function walk(dirAbs: string, prev: Manifest, next: Manifest): Promise<voi
       }
 
       if (audio.length || video.length) {
+        // Regenerate lyrics cache from scratch (drop any orphaned by removed tracks/sidecars).
+        const lyricsDir = join(cacheDir, 'lyrics');
+        await rm(lyricsDir, { recursive: true, force: true }).catch(() => {});
         const tracks = await mapPool(audio, TRACK_CONCURRENCY, async (name) => {
-          const t = await ffprobeTrack(join(dirAbs, name), name);
+          const { track: t, lyricsText } = await ffprobeTrack(join(dirAbs, name), name);
+          const fmt = await resolveTrackLyrics(dirAbs, lyricsDir, name, fileSet, lyricsText);
+          if (fmt) {
+            t.lyrics = fmt;
+            status.lyricsIndexed += 1;
+          }
           status.tracksIndexed += 1;
           emitProgress();
           return t;
@@ -606,3 +680,7 @@ export function discographyFilePath(rel: string): string | null {
 export function posterFilePath(rel: string, file: string): string | null {
   return resolveCachePath(rel, join('posters', `${basename(file)}.jpg`));
 }
+/** A track's cached lyrics: cache/<rel>/lyrics/<file>.<lrc|txt>. `file` basename'd for path-safety. */
+export function lyricsFilePath(rel: string, file: string, fmt: 'lrc' | 'txt'): string | null {
+  return resolveCachePath(rel, join('lyrics', `${basename(file)}.${fmt}`));
+}