Add a web player lyrics panel with active-line highlighting and click-to-seek

New GET /player/lyrics/{id} (auth-required) returns the best available
stored structuredLyrics entry for a song — preferring a synced one —
as plain JSON lines with a start time only where the source actually
has one.

The player bar gains a lyrics toggle; the panel fetches lyrics on
every song change, renders each line, and — only for lines that
actually carry a startMs — makes them clickable (seeks + plays) and
highlights the currently active line as playback progresses. Plain
(unsynced) lyrics render as static text with no fabricated timing or
highlighting.

Note: verified via Go template parsing/rendering and the new handler
tests, plus a JS syntax check; not manually exercised in a browser in
this session.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014r98AtcBbevpscWLsfwVvv

internal/web/lyrics_handler.go

@@ -0,0 +1,50 @@
+package web
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"git.noroutes.net/NoRoutes/vibetunes/internal/database"
+)
+
+type lyricsLineJSON struct {
+	Text    string `json:"text"`
+	StartMs *int   `json:"startMs,omitempty"`
+}
+
+type lyricsResponseJSON struct {
+	Synced bool             `json:"synced"`
+	Lines  []lyricsLineJSON `json:"lines"`
+}
+
+// handleLyrics serves the web player's lyrics panel: the best available
+// stored structuredLyrics entry for a song, as line text plus a start
+// time when the source actually has one. Prefers a synced entry over
+// an unsynced one so the panel can highlight/click-to-seek whenever
+// that data exists, but never fabricates timing for an unsynced entry.
+func (h *Web) handleLyrics(w http.ResponseWriter, r *http.Request) {
+	songID := r.PathValue("id")
+	entries, err := database.GetSongStructuredLyrics(h.DB, songID)
+	if err != nil {
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+
+	var best *database.StructuredLyricsRow
+	for i := range entries {
+		if best == nil || (entries[i].Synced && !best.Synced) {
+			best = &entries[i]
+		}
+	}
+
+	out := lyricsResponseJSON{Lines: []lyricsLineJSON{}}
+	if best != nil {
+		out.Synced = best.Synced
+		for _, l := range best.Lines {
+			out.Lines = append(out.Lines, lyricsLineJSON{Text: l.Text, StartMs: l.StartMs})
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(out)
+}

internal/web/lyrics_handler_test.go

@@ -0,0 +1,101 @@
+package web
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"git.noroutes.net/NoRoutes/vibetunes/internal/database"
+)
+
+func TestLyricsHandlerPrefersSyncedEntry(t *testing.T) {
+	h, db := newTestWeb(t)
+	srv := httptest.NewServer(h.NewRouter())
+	defer srv.Close()
+	jar := map[string]*http.Cookie{}
+	doSetup(t, srv, jar, t.TempDir())
+
+	folder, err := database.CreateMusicFolder(db, "Music", "/music", "music")
+	if err != nil {
+		t.Fatal(err)
+	}
+	mf, err := database.CreateMediaFile(db, folder.ID, filepath.Join("a.mp3"), 100, 0, "h", "mp3", "song", 10, 128, 44100, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	song, err := database.UpsertSong(db, database.UpsertSongInput{MediaFileID: mf.ID, Title: "Song"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := database.InsertLyrics(db, song.ID, "embedded", "xxx", false, []database.LyricsLineInput{{Text: "Plain line"}}); err != nil {
+		t.Fatal(err)
+	}
+	start := 1500
+	if _, err := database.InsertLyrics(db, song.ID, "external", "en", true, []database.LyricsLineInput{{StartMs: &start, Text: "Synced line"}}); err != nil {
+		t.Fatal(err)
+	}
+
+	resp := doRequest(t, srv, jar, http.MethodGet, "/player/lyrics/"+song.ID, nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	var out lyricsResponseJSON
+	if err := json.Unmarshal(body, &out); err != nil {
+		t.Fatalf("invalid JSON: %v\n%s", err, body)
+	}
+	if !out.Synced {
+		t.Errorf("expected the synced entry to be preferred, got synced=false: %+v", out)
+	}
+	if len(out.Lines) != 1 || out.Lines[0].Text != "Synced line" {
+		t.Fatalf("lines = %+v", out.Lines)
+	}
+	if out.Lines[0].StartMs == nil || *out.Lines[0].StartMs != 1500 {
+		t.Errorf("StartMs = %v, want 1500", out.Lines[0].StartMs)
+	}
+}
+
+func TestLyricsHandlerNoLyricsReturnsEmpty(t *testing.T) {
+	h, db := newTestWeb(t)
+	srv := httptest.NewServer(h.NewRouter())
+	defer srv.Close()
+	jar := map[string]*http.Cookie{}
+	doSetup(t, srv, jar, t.TempDir())
+
+	folder, err := database.CreateMusicFolder(db, "Music", "/music", "music")
+	if err != nil {
+		t.Fatal(err)
+	}
+	mf, err := database.CreateMediaFile(db, folder.ID, "b.mp3", 100, 0, "h2", "mp3", "song", 10, 128, 44100, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	song, err := database.UpsertSong(db, database.UpsertSongInput{MediaFileID: mf.ID, Title: "No Lyrics"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	resp := doRequest(t, srv, jar, http.MethodGet, "/player/lyrics/"+song.ID, nil)
+	body, _ := io.ReadAll(resp.Body)
+	var out lyricsResponseJSON
+	if err := json.Unmarshal(body, &out); err != nil {
+		t.Fatalf("invalid JSON: %v\n%s", err, body)
+	}
+	if len(out.Lines) != 0 {
+		t.Errorf("expected no lines, got %+v", out.Lines)
+	}
+}
+
+func TestLyricsHandlerRequiresAuth(t *testing.T) {
+	h, _ := newTestWeb(t)
+	srv := httptest.NewServer(h.NewRouter())
+	defer srv.Close()
+	jar := map[string]*http.Cookie{}
+	resp := doRequest(t, srv, jar, http.MethodGet, "/player/lyrics/sg_whatever", nil)
+	if resp.StatusCode == http.StatusOK {
+		t.Fatal("expected unauthenticated request to be rejected/redirected, got 200")
+	}
+}

internal/web/router.go

@@ -69,6 +69,7 @@ func (h *Web) NewRouter() http.Handler {
 	mux.HandleFunc("POST /settings/sessions/{id}/revoke", h.requireUser(h.handleSessionRevoke))
 
 	mux.HandleFunc("GET /stream/{id}", h.requireUser(h.handleStream))
+	mux.HandleFunc("GET /player/lyrics/{id}", h.requireUser(h.handleLyrics))
 	mux.HandleFunc("GET /cover-art/{id}", h.requireUser(h.handleCoverArt))
 
 	mux.HandleFunc("GET /admin", h.requireAdmin(h.handleAdminRoot))