nixamp 0.41.2 → 0.43.0

package/src/lyrics.ts

@@ -0,0 +1,161 @@
+/**
+ * The words of the song on the air, for a station's page.
+ *
+ * Two places they come from, in this order:
+ *  1. the file itself: an ID3 USLT frame (ffprobe calls it `lyrics-eng`, or
+ *     `lyrics-<description>-<lang>`), a Vorbis/APE `LYRICS` or
+ *     `UNSYNCEDLYRICS` tag. Suno writes the words it sang into USLT, so our
+ *     own catalog carries them already;
+ *  2. nichedb.dev's lyrics, asked by artist and title, which is where a file
+ *     without the tag gets them (and where ours are published back to:
+ *     lyrics-publish.ts).
+ * Each answer is kept: the tags with the file (by size and time, TagReader),
+ * nichedb's for ten minutes, misses included, so a station of tracks nobody
+ * has words for asks once per track per ten minutes and never waits long.
+ */
+
+export interface Lyrics {
+  title: string;
+  artist: string;
+  text: string;
+  /** "embedded" (the file's own tag) or "nichedb" (or what nichedb said its source was). */
+  source: string;
+  /** ISO 639-1 where we know the mapping, else what the tag said; "" when unsaid. */
+  language: string;
+}
+
+export const NICHEDB_LYRICS = "https://nichedb.dev";
+const MAX_TEXT = 20_000;
+
+/** ID3 / ISO 639-2 codes for the languages we are likely to meet, as 639-1. */
+const LANGS: Record<string, string> = {
+  eng: "en", deu: "de", ger: "de", fra: "fr", fre: "fr", spa: "es", ita: "it", por: "pt", nld: "nl", dut: "nl",
+  swe: "sv", nor: "no", nob: "nb", dan: "da", isl: "is", ice: "is", fin: "fi", jpn: "ja", kor: "ko", zho: "zh",
+  chi: "zh", rus: "ru", pol: "pl", ukr: "uk", tur: "tr", ara: "ar", heb: "he", hin: "hi", ces: "cs", cze: "cs",
+  ell: "el", gre: "el", hun: "hu", ron: "ro", rum: "ro", lat: "la", gle: "ga", cym: "cy", wel: "cy",
+};
+
+function language(code: string): string {
+  const lower = code.toLowerCase();
+  if (lower === "" || lower === "xxx" || lower === "und" || lower === "zxx") return "";
+  return LANGS[lower] ?? lower;
+}
+
+/** Text as it may be shown: newlines kept, control characters gone, trimmed, capped. */
+export function cleanLyrics(text: string): string {
+  return text
+    .replace(/\r\n?/g, "\n")
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim()
+    .slice(0, MAX_TEXT);
+}
+
+/** The words a file's own tags carry (lower-cased names, as TagReader gives them), or null. */
+export function lyricsFromTags(tags: Record<string, string>): { text: string; language: string } | null {
+  let best: { text: string; language: string } | null = null;
+  for (const [name, value] of Object.entries(tags)) {
+    let lang = "";
+    if (name === "lyrics" || name === "unsyncedlyrics" || name === "unsynced lyrics" || name === "unsynced_lyrics" || name === "uslt") {
+      lang = "";
+    } else if (name.startsWith("lyrics-") || name.startsWith("lyrics_")) {
+      // lyrics-eng, or lyrics-<description>-eng: the language is the last part.
+      const last = name.slice("lyrics-".length).split(/[-_]/).pop() ?? "";
+      lang = /^[a-z]{3}$/.test(last) ? last : "";
+    } else {
+      continue;
+    }
+    const text = cleanLyrics(value);
+    if (text === "") continue;
+    // The longest wins: a short descriptor-only frame is not the song.
+    if (!best || text.length > best.text.length) best = { text, language: language(lang) };
+  }
+  return best;
+}
+
+type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
+
+export interface LyricsFinderOptions {
+  /** The file's tags (TagReader.read). */
+  tags: (file: string) => Promise<Record<string, string>>;
+  /** What the library knows when the file has no tag for it. */
+  known?: (file: string) => { title: string; artist: string } | null;
+  /** nichedb's address; NIXAMP_LYRICS_URL, else nichedb.dev. "" turns the lookup off. */
+  base?: string;
+  fetcher?: Fetcher;
+  /** How long nichedb's answer (or its silence) is kept. */
+  ttlMs?: number;
+  timeoutMs?: number;
+  now?: () => number;
+}
+
+/** Finds a file's words, from its tags, else from nichedb. */
+export class LyricsFinder {
+  private remote = new Map<string, { at: number; lyrics: Lyrics | null }>();
+  private asking = new Map<string, Promise<Lyrics | null>>();
+  private readonly base: string;
+  private readonly fetcher: Fetcher;
+  private readonly ttl: number;
+  private readonly timeout: number;
+  private readonly now: () => number;
+
+  constructor(private readonly options: LyricsFinderOptions) {
+    this.base = (options.base ?? process.env["NIXAMP_LYRICS_URL"] ?? NICHEDB_LYRICS).replace(/\/+$/, "");
+    this.fetcher = options.fetcher ?? ((url, init) => fetch(url, init));
+    this.ttl = options.ttlMs ?? 10 * 60_000;
+    this.timeout = options.timeoutMs ?? 4_000;
+    this.now = options.now ?? Date.now;
+  }
+
+  /** The file's words, or null. Never throws; never waits on nichedb longer than the timeout. */
+  async find(file: string): Promise<Lyrics | null> {
+    let tags: Record<string, string> = {};
+    try { tags = await this.options.tags(file); } catch { tags = {}; }
+    const known = this.options.known?.(file) ?? null;
+    const title = tags["title"] || known?.title || "";
+    const artist = tags["artist"] || tags["album_artist"] || known?.artist || "";
+    const own = lyricsFromTags(tags);
+    if (own) return { title, artist, text: own.text, source: "embedded", language: own.language };
+    if (!title || !artist || !this.base) return null;
+    return this.lookup(artist, title);
+  }
+
+  /** What nichedb has for this artist and title, kept for ten minutes. */
+  lookup(artist: string, title: string): Promise<Lyrics | null> {
+    const key = `${artist.toLowerCase()}\n${title.toLowerCase()}`;
+    const hit = this.remote.get(key);
+    if (hit && this.now() - hit.at < this.ttl) return Promise.resolve(hit.lyrics);
+    const pending = this.asking.get(key);
+    if (pending) return pending;
+    const asked = this.ask(artist, title).then((lyrics) => {
+      if (this.remote.size > 2000) this.remote.clear();
+      this.remote.set(key, { at: this.now(), lyrics });
+      return lyrics;
+    }).finally(() => this.asking.delete(key));
+    this.asking.set(key, asked);
+    return asked;
+  }
+
+  private async ask(artist: string, title: string): Promise<Lyrics | null> {
+    const url = `${this.base}/api/v1/lyrics?artist=${encodeURIComponent(artist)}&title=${encodeURIComponent(title)}`;
+    try {
+      const response = await this.fetcher(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(this.timeout) });
+      if (!response.ok) return null;
+      const body = await response.json() as { lyrics?: Record<string, unknown> };
+      const found = body?.lyrics;
+      const text = typeof found?.["text"] === "string" ? cleanLyrics(found["text"]) : "";
+      if (!text) return null;
+      const string = (name: string): string => (typeof found?.[name] === "string" ? String(found[name]) : "");
+      return {
+        title: string("title") || title,
+        artist: string("artist") || artist,
+        text,
+        source: "nichedb",
+        language: string("language"),
+      };
+    } catch {
+      return null;
+    }
+  }
+}

package/src/server.ts

@@ -81,7 +81,10 @@ import { handleAiRoutes, isPublicSharePath } from "./ai-routes.ts";
 import { AiRadio } from "./ai-radio.ts";
 import { ListenerShares } from "./listener-shares.ts";
 import { HolderStore, TagReader, factsFor } from "./track-facts.ts";
-import { SUPPORT_CSP, SUPPORT_PAGE, Support, SupportError, supportHoldersFrom } from "./support.ts";
+import { SUPPORT_CSP, SUPPORT_PAGE, Support, SupportError, SupportSubscriptions, supportHoldersFrom } from "./support.ts";
+import { LyricsFinder } from "./lyrics.ts";
+import { LyricsPublisher } from "./lyrics-publish.ts";
+import { aiKey } from "./ai-keys.ts";
 import { STATION_APP_CSP, STATION_PAGE, STATION_PAGE_CSP, STATION_PAGE_HTML } from "./station-page.ts";
 import { GUIDE_CSP, guideHosts, guidePeers, peerBase, PeerGuides, renderGuide, type GuideEntry } from "./station-guide.ts";
 import { StationRunner } from "./station-runner.ts";
@@ -1742,6 +1745,10 @@ export interface HandlerOptions {
     facts?: (station: Station, file: string) => Promise<import("./track-facts.ts").TrackFacts>;
     /** The cover picture inside a file, for the now-playing card. */
     cover?: (file: string) => Promise<{ bytes: Buffer; type: string } | null>;
+    /** The words of a file on the air, from its tags or nichedb. */
+    lyrics?: (station: Station, file: string) => Promise<import("./lyrics.ts").Lyrics | null>;
+    /** Our own songs' words, published back to nichedb. */
+    lyricsPublisher?: import("./lyrics-publish.ts").LyricsPublisher;
     /** Copyright holders, matched to tracks by artist or station. */
     holders?: import("./track-facts.ts").HolderStore;
     /** Proxies (by address) whose X-Forwarded-For is believed, for per-sharer limits. */
@@ -1924,6 +1931,8 @@ export interface HandlerOptions {
   translationPasses?: TranslationPasses;
   /** Payments to copyright holders nixamp.com collects for (support.ts). */
   support?: Support;
+  /** Monthly support, run by nixamp.com (support.ts). */
+  supportSubscriptions?: SupportSubscriptions;
   /** Signing secret of nixamp's CoinPay business, for /api/v1/webhooks/coinpay. */
   coinpayWebhookSecret?: string;
   sharedTranslations?: SharedTranslations;
@@ -2698,7 +2707,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       // What is on, as MCP, for anybody.
       path !== "/mcp/public" &&
       // Supporting a copyright holder is for anybody listening.
-      !/^\/support\/[a-z0-9-]{1,40}$/.test(path) && !/^\/api\/v1\/support\/[a-z0-9-]{1,40}$/.test(path) &&
+      !/^\/support\/[a-z0-9-]{1,40}$/.test(path) && path !== "/support/cancel" && !/^\/api\/v1\/support\/[a-z0-9-]{1,40}$/.test(path) &&
       // A station's short link, which sends the browser to wherever it plays.
       !/^\/watch\/[a-z0-9]{10}$/.test(path) &&
       !STATION_PAGE.test(path) &&
@@ -2765,6 +2774,22 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
      * in the directory). It sends the browser to the station's own page, on
      * the server that plays it. Nothing private or unlisted is ever found.
      */
+    /* A monthly support's cancel link, from any of its emails. */
+    if (path === "/support/cancel" && options.supportSubscriptions && (request.method === "GET" || request.method === "HEAD")) {
+      let words: string;
+      try {
+        const done = await options.supportSubscriptions.cancel(url.searchParams.get("s") ?? "", url.searchParams.get("t") ?? "");
+        const name = options.support?.holder(done.holder)?.name ?? done.holder;
+        words = `Your monthly support for ${name} is cancelled. No more payment links will be sent.`;
+      } catch (error) {
+        words = error instanceof SupportError ? error.message : "That did not work; try the link again.";
+      }
+      const safe = words.replace(/[&<>"']/g, (one) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[one]!);
+      response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'", "referrer-policy": "no-referrer" });
+      response.end(request.method === "HEAD" ? undefined : `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Support · nixamp</title><body style="margin:0;background:#080c09;color:#e8efe9;font:16px/1.5 system-ui,sans-serif"><main style="max-width:520px;margin:0 auto;padding:48px 16px"><h1 style="font-size:1.4rem">Monthly support</h1><p>${safe}</p><p><a style="color:#3ddc84" href="https://nixamp.com/guide">Back to the stations</a></p></main></body>`);
+      return;
+    }
+
     /* Support a copyright holder: the page, the coins, and a CoinPay checkout. */
     const supportPage = /^\/support\/([a-z0-9-]{1,40})$/.exec(path);
     if (supportPage && options.support && (request.method === "GET" || request.method === "HEAD")) {
@@ -2798,7 +2823,12 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
           }
           let body: Record<string, unknown> = {};
           try { body = JSON.parse(await readBody(request)) as Record<string, unknown>; } catch { body = {}; }
-          json(response, 200, await support.checkout({ ...body, holder: holder.id }));
+          if (body["monthly"] === true) {
+            if (!options.supportSubscriptions) throw new SupportError("Monthly support is not set up here.", 503, "unavailable");
+            json(response, 200, await options.supportSubscriptions.start({ ...body, holder: holder.id }));
+          } else {
+            json(response, 200, await support.checkout({ ...body, holder: holder.id }));
+          }
           return;
         }
         json(response, 405, { error: "GET or POST", code: "method_not_allowed" });
@@ -2975,6 +3005,8 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
         ...(options.stations.auto ? { auto: options.stations.auto } : {}),
         ...(options.stations.facts ? { facts: options.stations.facts } : {}),
         ...(options.stations.cover ? { cover: options.stations.cover } : {}),
+        ...(options.stations.lyrics ? { lyrics: options.stations.lyrics } : {}),
+        ...(options.stations.lyricsPublisher ? { lyricsPublisher: options.stations.lyricsPublisher } : {}),
         ...(options.stations.peers ? { peers: () => options.stations!.peers!.entries() } : {}),
         throttle: () => {
           const verdict = guard.check(`stations:${control.account || callerOf(request.headers, request.socket.remoteAddress, behindProxy)}`, STATION_CONTROL_LIMIT);
@@ -7083,6 +7115,27 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     covers.set(file, { key, picture });
     return picture;
   };
+  // The words of what is on: the file's own tag, else nichedb.dev's.
+  const lyricsFinder = new LyricsFinder({ tags: (file) => tagReader.read(file), known: (file) => trackFor(engine, file) });
+  stations.lyrics = (_station, file) => lyricsFinder.find(file);
+  // Our own songs' words, back to nichedb, when a key is set: on any station
+  // change, after a library scan, and once at start.
+  const lyricsPublisher = new LyricsPublisher({
+    file: LyricsPublisher.fileFor(stateDir(), options.port),
+    key: () => aiKey("NIXAMP_LYRICS_KEY"),
+    stations: () => stationStore.list(),
+    tags: (file) => tagReader.read(file),
+    known: (file) => trackFor(engine, file),
+    log: (line) => console.log(line),
+  });
+  stations.lyricsPublisher = lyricsPublisher;
+  stationStore.onSaved = () => lyricsPublisher.soon();
+  const scannedBefore = libraryIndex.onScanned;
+  libraryIndex.onScanned = (report) => {
+    scannedBefore?.(report);
+    lyricsPublisher.soon();
+  };
+  lyricsPublisher.soon();
   stations.facts = async (station, file) => {
     const share = listenerShares.atFile(file);
     const composed = aiRadio.trackAt(file);
@@ -7090,8 +7143,10 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     let stamp = "";
     try { stamp = String(Math.round(statSync(file).mtimeMs)); } catch { stamp = ""; }
     const art = picture ? `/api/v1/stations/${station.id}/art?t=${encodeURIComponent(station.listenToken)}&f=${sha("sha1").update(file + stamp).digest("hex").slice(0, 12)}` : "";
+    const words = await lyricsFinder.find(file).catch(() => null);
     return factsFor({
       art,
+      ...(words ? { lyrics: `/api/v1/stations/${station.id}/lyrics?t=${encodeURIComponent(station.listenToken)}&f=${sha("sha1").update(file + stamp).digest("hex").slice(0, 12)}` } : {}),
       station, file,
       tags: await tagReader.read(file),
       known: trackFor(engine, file),
@@ -7234,6 +7289,15 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     ? new TranslationPasses({ db: pool, key: coinpayKeyFrom(), site: nixampSite }) : undefined;
   // Payments to the copyright holders nixamp.com collects for, on its own CoinPay business.
   const supportPayments = accounts ? new Support({ key: coinpayKeyFrom(), site: nixampSite, holders: supportHoldersFrom() }) : undefined;
+  // Monthly support: each month a new CoinPay payment and its link by email.
+  const supportMonthly = supportPayments && supportPayments.enabled && pool ? new SupportSubscriptions({
+    db: pool as unknown as import("./support.ts").Db,
+    support: supportPayments,
+    mail: process.env["RESEND_API_KEY"] ? { apiKey: process.env["RESEND_API_KEY"], from: process.env["NIXAMP_MAIL_FROM"] ?? "nixamp <notifications@nixamp.com>" } : null,
+    site: nixampSite,
+    log: (line) => console.log(line),
+  }) : undefined;
+  supportMonthly?.startSchedule();
   if (translationPasses) void translationPasses.access().catch(() => console.error("nixamp: translation checkout could not warm; it will retry on demand"));
   const liveVoice = accounts && process.env["NIXAMP_DUBBING"] !== "off" ? new LiveVoice({
     ...(pool ? { db: pool } : {}),
@@ -7787,6 +7851,7 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     ...(liveVoice ? { liveVoice } : {}),
     ...(translationPasses ? { translationPasses } : {}),
     ...(supportPayments ? { support: supportPayments } : {}),
+    ...(supportMonthly ? { supportSubscriptions: supportMonthly } : {}),
     ...(process.env["COINPAY_WEBHOOK_SECRET"] ? { coinpayWebhookSecret: process.env["COINPAY_WEBHOOK_SECRET"] } : {}),
     ...(sharedTranslations ? { sharedTranslations } : {}),
     ...(translator ? { translator } : {}),

package/src/station-cli.ts

@@ -253,6 +253,8 @@ export async function station(argv: string[]): Promise<number> {
         return await aiCommand(argv.slice(1), call, show, json);
       case "shares":
         return await sharesCommand(argv.slice(1), call, show);
+      case "lyrics":
+        return await lyricsCommand(argv.slice(1), call, show, json);
       case "holder":
       case "holders": {
         const sub = argv[1] ?? "list";
@@ -389,6 +391,44 @@ async function aiCommand(argv: string[], call: Call, show: Show, json: boolean):
   }
 }
 
+/** `nixamp station lyrics ...`: our own songs' words, published back to nichedb.dev. */
+async function lyricsCommand(argv: string[], call: Call, show: Show, json: boolean): Promise<number> {
+  const [sub, id] = argv;
+  switch (sub) {
+    case undefined:
+    case "status":
+      return show(await call("GET", "/api/v1/stations/lyrics"), (body) => {
+        const stations = (body["stations"] as Record<string, unknown>[] | undefined) ?? [];
+        const last = body["last"] as { at: number; reports: Array<Record<string, unknown>> } | null;
+        return [
+          `key        ${body["key"] ? "set" : "- (nixamp station lyrics key, the value on stdin)"}`,
+          `target     ${String(body["target"])}`,
+          `published  ${String(body["published"])} files${body["running"] ? "; publishing now" : ""}`,
+          ...(last ? [`last run   ${new Date(last.at).toISOString()}: ${last.reports.map((one) => `${String(one["station"])} +${String(one["published"])}`).join(", ") || "nothing eligible"}`] : []),
+          ...(body["lastError"] ? [`problem    ${String(body["lastError"])}`] : []),
+          "",
+          ...stations.map((one) => `  ${String(one["id"])}  ${one["eligible"] ? "publishes" : "no       "} ${String(one["published"]).padStart(4)}/${String(one["files"]).padEnd(5)} ${String(one["name"])}${one["eligible"] ? "" : `  (${String(one["why"])})`}`),
+        ].join("\n");
+      });
+    case "publish": {
+      if (!id || id.startsWith("--")) { console.error("nixamp station lyrics publish needs a station id"); return 2; }
+      if (!json) console.log("Publishing; a second between songs…");
+      return show(await call("POST", `/api/v1/stations/lyrics/${id}/publish`, {}), (body) => {
+        const report = body["report"] as Record<string, unknown>;
+        return `${String(report["published"])} published, ${String(report["unchanged"])} already there, ${String(report["without"])} without words, ${String(report["failed"])} failed${report["stopped"] ? `\nstopped: ${String(report["stopped"])}` : ""}`;
+      });
+    }
+    case "key": {
+      const value = argv.includes("--clear") ? "" : await readStdin();
+      return show(await call("POST", "/api/v1/stations/ai/keys", { name: "NIXAMP_LYRICS_KEY", value }), (answer) =>
+        `nichedb lyrics key ${((answer["keys"] ?? {}) as Record<string, boolean>)["NIXAMP_LYRICS_KEY"] ? "set" : "cleared"}.`);
+    }
+    default:
+      console.error(`nixamp station lyrics: no command "${sub}".\n\n${USAGE}`);
+      return 2;
+  }
+}
+
 /** `nixamp station shares ...` */
 async function sharesCommand(argv: string[], call: Call, show: Show): Promise<number> {
   const [sub, id] = argv;

package/src/station-page.ts

@@ -14,7 +14,7 @@ import { createHash } from "node:crypto";
 const STYLE = `
 :root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b;--warn:#9a6700;--off:#8c2f39}
 @media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f;--warn:#e3b341;--off:#f0838f}}
-*{box-sizing:border-box}html,body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+*{box-sizing:border-box}[hidden]{display:none!important}html,body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
 main{max-width:560px;margin:0 auto;padding:48px 16px}
 .card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}
 h1{font-size:1.6rem;line-height:1.2;margin:0 0 4px}
@@ -30,6 +30,13 @@ button:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid var(-
 label{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.9rem}
 input[type=range]{width:120px;accent-color:var(--accent)}
 .small{margin-top:20px;font-size:.85rem;color:var(--muted)}.small a{color:inherit}
+.lyrics{margin:20px 0 0;border-top:1px solid var(--line);padding-top:12px}
+.lyrics summary{cursor:pointer;font-weight:600;min-height:24px}
+.lyrics .for{font-weight:400;color:var(--muted);font-size:.9rem}
+.words{margin-top:10px;line-height:1.6}
+.words p{margin:0 0 1em;white-space:pre-wrap;overflow-wrap:anywhere}
+.words p.sec{margin:1.2em 0 .3em;font-size:.75rem;letter-spacing:.06em;text-transform:uppercase;color:var(--muted)}
+.words p.sec:first-child{margin-top:0}
 .screen{display:block;width:100%;aspect-ratio:16/9;background:#000;border-radius:10px;margin:12px 0}
 .sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
 @media (prefers-reduced-motion:no-preference){.live::before{animation:pulse 2s ease-in-out infinite}}
@@ -90,13 +97,37 @@ const SCRIPT = `
     if (!wanted || audio.paused || audio.buffered.length === 0) return 0;
     return Math.max(0, Math.min(30, audio.buffered.end(audio.buffered.length - 1) - audio.currentTime));
   };
+  // The words of what is on, line by line; "[Verse 1]" as a small header. Text only, never HTML.
+  let words = null;
+  const lyrics = async () => {
+    try {
+      const r = await fetch(api + "/lyrics" + q, { cache: "no-store" });
+      const got = r.ok ? (await r.json()).lyrics : null;
+      const key = got ? got.title + "\\n" + got.text : "";
+      if (key === words) return;
+      words = key;
+      $("#lyrics").hidden = !got;
+      if (!got) return;
+      const out = [];
+      let stanza = [];
+      const flush = () => { if (stanza.length) { const p = document.createElement("p"); p.textContent = stanza.join("\\n"); out.push(p); stanza = []; } };
+      for (const line of got.text.split("\\n")) {
+        if (/^\\s*\\[[^\\]]{1,160}\\]\\s*$/.test(line)) { flush(); const h = document.createElement("p"); h.className = "sec"; h.textContent = line.trim().slice(1, -1); out.push(h); }
+        else if (line.trim() === "") flush();
+        else stanza.push(line);
+      }
+      flush();
+      $("#words").replaceChildren(...out);
+      $("#lyrics-for").textContent = got.title ? " · " + got.title : "";
+    } catch {}
+  };
   const listen = () => {
     if (!window.EventSource) return;
     const events = new EventSource(api + "/events" + q);
-    events.addEventListener("hello", (e) => { live = true; title(JSON.parse(e.data)); });
+    events.addEventListener("hello", (e) => { live = true; title(JSON.parse(e.data)); lyrics(); });
     events.addEventListener("now", (e) => {
       const s = JSON.parse(e.data);
-      setTimeout(() => { title(s); say(s.nowPlaying ? "Now playing " + (s.nowPlaying.title || "") : ""); }, ahead() * 1000);
+      setTimeout(() => { title(s); lyrics(); say(s.nowPlaying ? "Now playing " + (s.nowPlaying.title || "") : ""); }, ahead() * 1000);
     });
     events.addEventListener("state", () => poll());
     events.onerror = () => { live = false; };
@@ -122,7 +153,9 @@ const SCRIPT = `
   wire();
   $("#play").addEventListener("click", () => { if (wanted) { stop(); say("Stopped"); } else { wanted = true; retry = 0; button(); join(); say("Playing"); } });
   $("#volume").addEventListener("input", (e) => { audio.volume = Number(e.target.value); });
+  if (window.matchMedia && matchMedia("(max-width: 640px)").matches) $("#lyrics-box").open = false;
   poll();
+  lyrics();
   listen();
   setInterval(poll, 5000);
 })();
@@ -152,6 +185,9 @@ const PAGE = `<!doctype html>
       <button id="play" type="button" aria-pressed="false" disabled>Play</button>
       <label>Volume <input id="volume" type="range" min="0" max="1" step="0.05" value="1"></label>
     </div>
+    <section id="lyrics" class="lyrics" aria-label="Lyrics" hidden>
+      <details id="lyrics-box" open><summary>Lyrics<span id="lyrics-for" class="for"></span></summary><div id="words" class="words"></div></details>
+    </section>
     <p class="small"><a id="m3u" href="#">Open in another player (.m3u)</a> · Pausing here does not pause the station.</p>
   </div>
   <p class="small">Played by <a href="https://nixamp.com">nixamp</a>.</p>

package/src/station-routes.ts

@@ -17,12 +17,14 @@ import type { Channels } from "./channels.ts";
 import type { StationRunner } from "./station-runner.ts";
 import { alertsFor, type Limits, type StationUsage } from "./station-metering.ts";
 import { aiFromTags, type TrackFacts } from "./track-facts.ts";
+import type { Lyrics } from "./lyrics.ts";
+import type { PublishReport } from "./lyrics-publish.ts";
 import {
   StationError, channelOf, tokensMatch, type OwnerStation, type PublicStation, type Station, type StationStore,
 } from "./stations.ts";
 
 /** The three things a station's link opens. */
-const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u|events|now|art)$/;
+const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u|events|now|art|lyrics)$/;
 
 /** Whether this path is one a station's own link may open, without the server's key. */
 export function isStationListenPath(path: string): boolean {
@@ -64,6 +66,10 @@ export interface StationContext {
   facts?: (station: Station, file: string) => Promise<TrackFacts>;
   /** The cover picture inside a file (JPEG/PNG bytes), or null. */
   cover?: (file: string) => Promise<{ bytes: Buffer; type: string } | null>;
+  /** The words of a file, from its tags or nichedb; null when none are known. */
+  lyrics?: (station: Station, file: string) => Promise<Lyrics | null>;
+  /** Our own songs' words, published back to nichedb (lyrics-publish.ts). */
+  lyricsPublisher?: { status: () => unknown; publish: (station: Station) => Promise<PublishReport> };
   /** Auto stations: run a sync with these settings (and keep them), or read them. */
   auto?: { sync: (input: Record<string, unknown>) => Promise<unknown>; setting: () => unknown };
   /** The public stations other servers list (guide peers); absent when there are none. */
@@ -272,6 +278,16 @@ export async function handleStations(
       response.end(method === "HEAD" ? undefined : picture.bytes);
       return true;
     }
+    if (what === "lyrics") {
+      const file = ctx.runner.observed(station.id) === "live" || ctx.runner.observed(station.id) === "recovering" ? nowPlayingFile(ctx, station) : "";
+      const lyrics = file && ctx.lyrics ? await ctx.lyrics(station, file).catch(() => null) : null;
+      if (!lyrics) {
+        ctx.json(response, 404, { error: "no lyrics for what is playing", code: "not_found" });
+        return true;
+      }
+      ctx.json(response, 200, { lyrics: { title: lyrics.title, artist: lyrics.artist, text: lyrics.text, source: lyrics.source, language: lyrics.language } });
+      return true;
+    }
     if (what === "now") {
       const file = ctx.runner.observed(station.id) === "live" || ctx.runner.observed(station.id) === "recovering" ? nowPlayingFile(ctx, station) : "";
       ctx.json(response, 200, { station: station.id, facts: file && ctx.facts ? await ctx.facts(station, file).catch(() => null) : null });
@@ -419,6 +435,35 @@ export async function handleStations(
       return true;
     }
 
+    if (path === "/api/v1/stations/lyrics") {
+      if (!ctx.lyricsPublisher) {
+        ctx.json(response, 404, { error: "lyrics publishing is not available here", code: "not_found" });
+        return true;
+      }
+      if (method !== "GET") {
+        ctx.json(response, 405, { error: "GET", code: "method_not_allowed" });
+        return true;
+      }
+      ctx.json(response, 200, ctx.lyricsPublisher.status());
+      return true;
+    }
+    const publishLyrics = /^\/api\/v1\/stations\/lyrics\/([a-z0-9]{10})\/publish$/.exec(path);
+    if (publishLyrics) {
+      const target = ctx.store.get(publishLyrics[1]!);
+      if (!ctx.lyricsPublisher || !target) {
+        ctx.json(response, 404, { error: "no such station", code: "not_found" });
+        return true;
+      }
+      if (method !== "POST") {
+        ctx.json(response, 405, { error: "POST", code: "method_not_allowed" });
+        return true;
+      }
+      const report = await ctx.lyricsPublisher.publish(target);
+      const refused = report.stopped.startsWith("not published") ? "not_eligible" : report.stopped.startsWith("no key") ? "no_key" : "";
+      ctx.json(response, refused ? 409 : 200, refused ? { error: report.stopped, code: refused, report } : { report });
+      return true;
+    }
+
     const match = /^\/api\/v1\/stations\/([a-z0-9]{10})(?:\/([a-z-]+))?$/.exec(path);
     if (!match) {
       ctx.json(response, 404, { error: "no such station", code: "not_found" });

package/src/station-usage.ts

@@ -41,6 +41,11 @@ export const USAGE = `nixamp station — make a collection into a station
   nixamp station shares approve|reject|delete SHARE
   nixamp station shares trust ADDRESS [--remove]   believe this proxy's X-Forwarded-For
 
+  Lyrics (shown on the station page from each file's own tag, else nichedb.dev; ours published back):
+  nixamp station lyrics                      the key, what was published, which stations may publish
+  nixamp station lyrics publish ID           publish a station's words now (public, listed, basis owned only)
+  nixamp station lyrics key                  nichedb's key (NIXAMP_LYRICS_KEY), from stdin (--clear forgets it)
+
   Copyright holders (the now-playing card: who holds a track's copyright, and how to support them):
   nixamp station holder list
   nixamp station holder set NAME [--artist ARTIST]... [--station ID]... [--support https://...] [--label Subscribe] [--license TEXT]

package/src/stations.ts

@@ -192,8 +192,12 @@ export class StationStore {
     return join(stateDir, `stations-${port}.json`);
   }
 
+  /** Told after every change is written (lyrics publishing listens). */
+  onSaved: (() => void) | null = null;
+
   private save(): void {
     this.io.write(this.file, `${JSON.stringify({ version: 1, stations: [...this.stations.values()] }, null, 2)}\n`);
+    try { this.onSaved?.(); } catch { /* a listener's trouble is not the store's */ }
   }
 
   list(): Station[] {