nixamp 0.42.0 → 0.43.1

package/dist/ai-keys.d.ts

@@ -1,4 +1,4 @@
-export declare const AI_KEY_NAMES: readonly ["ELEVENLABS_API_KEY", "GEMINI_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "NIXAMP_OPENAI_URL", "NIXAMP_OPENAI_MODEL"];
+export declare const AI_KEY_NAMES: readonly ["ELEVENLABS_API_KEY", "GEMINI_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "NIXAMP_OPENAI_URL", "NIXAMP_OPENAI_MODEL", "NIXAMP_LYRICS_KEY"];
 export type AiKeyName = (typeof AI_KEY_NAMES)[number];
 export declare function aiKeysFile(): string;
 /** The key, from the environment or ai.json; "" when neither has it. */

package/dist/ai-keys.js

@@ -13,6 +13,8 @@ export const AI_KEY_NAMES = [
     "ELEVENLABS_API_KEY", "GEMINI_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY",
     // Any OpenAI-compatible endpoint in OpenAI's place (Cloudflare Workers AI, Ollama, ...) and its model.
     "NIXAMP_OPENAI_URL", "NIXAMP_OPENAI_MODEL",
+    // nichedb.dev's key for publishing our own songs' words (lyrics-publish.ts).
+    "NIXAMP_LYRICS_KEY",
 ];
 export function aiKeysFile() {
     return join(stateDir(), "ai.json");

package/dist/lyrics-publish.d.ts

@@ -0,0 +1,56 @@
+import type { Station } from "./stations.ts";
+type Fetcher = (url: string, init?: RequestInit) => Promise<Response>;
+/** Whether a station's lyrics may be published: owned, public and listed. */
+export declare function mayPublishLyrics(station: Pick<Station, "visibility" | "listed" | "rights">): boolean;
+/** Why not, in words, or "" when it may. */
+export declare function whyNotPublish(station: Pick<Station, "visibility" | "listed" | "rights">): string;
+export interface PublishReport {
+    station: string;
+    published: number;
+    unchanged: number;
+    /** Files with no words in their tags, or no artist or title to file them under. */
+    without: number;
+    failed: number;
+    stopped: string;
+}
+export interface LyricsPublisherOptions {
+    file: string;
+    /** The key nichedb takes, read each run (it may be set while the server runs); "" when unset. */
+    key: () => string;
+    stations: () => Station[];
+    tags: (file: string) => Promise<Record<string, string>>;
+    known?: (file: string) => {
+        title: string;
+        artist: string;
+        album: string;
+    } | null;
+    base?: string;
+    fetcher?: Fetcher;
+    /** Between two posts. */
+    gapMs?: number;
+    /** After a change, before a run (changes come in bursts). */
+    debounceMs?: number;
+    log?: (line: string) => void;
+}
+export declare class LyricsPublisher {
+    private readonly options;
+    private sent;
+    private running;
+    private timer;
+    private last;
+    private lastError;
+    private readonly base;
+    private readonly fetcher;
+    constructor(options: LyricsPublisherOptions);
+    static fileFor(stateDir: string, port: number): string;
+    private save;
+    /** Something changed (a station, the library): publish what is new, shortly. Nothing without a key. */
+    soon(): void;
+    status(): Record<string, unknown>;
+    /** Every eligible station, one after another; a run already going is joined, not doubled. */
+    publishAll(): Promise<PublishReport[]>;
+    /** One station, now. Refused (stopped says why) when it may not be published or there is no key. */
+    publish(station: Station): Promise<PublishReport>;
+    private publishOne;
+}
+export {};

package/dist/lyrics-publish.js

@@ -0,0 +1,194 @@
+/**
+ * Our own songs' words, published back to nichedb.dev.
+ *
+ * A station whose owner declared the music theirs (basis "owned") and put it
+ * on the public guide (public and listed) is music we may publish the words
+ * of. For each of its files whose own tags carry lyrics (lyrics.ts), the
+ * words go to nichedb's POST /api/v1/lyrics with the key the owner set
+ * (NIXAMP_LYRICS_KEY, or `nixamp station lyrics key` into ai.json), once per
+ * text: what was sent is remembered by a hash of the words, so a file is sent
+ * again only when its words change. One at a time, a second apart, and a
+ * refusal of the key (401/403) or a 429 stops the run.
+ *
+ * Nothing is published without a key, and nothing for a station that is not
+ * owned, whatever else is true of it.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { lyricsFromTags, NICHEDB_LYRICS } from "./lyrics.js";
+/** Whether a station's lyrics may be published: owned, public and listed. */
+export function mayPublishLyrics(station) {
+    return station.rights?.basis === "owned" && station.visibility === "public" && station.listed === true;
+}
+/** Why not, in words, or "" when it may. */
+export function whyNotPublish(station) {
+    if (station.rights?.basis !== "owned")
+        return "its music is not declared owned (nixamp station publish ID --basis owned)";
+    if (station.visibility !== "public")
+        return "it is not public";
+    if (!station.listed)
+        return "it is not listed on the guide";
+    return "";
+}
+export class LyricsPublisher {
+    options;
+    sent = {};
+    running = null;
+    timer = null;
+    last = null;
+    lastError = "";
+    base;
+    fetcher;
+    constructor(options) {
+        this.options = options;
+        this.base = (options.base ?? process.env["NIXAMP_LYRICS_URL"] ?? NICHEDB_LYRICS).replace(/\/+$/, "");
+        this.fetcher = options.fetcher ?? ((url, init) => fetch(url, init));
+        try {
+            const parsed = JSON.parse(readFileSync(options.file, "utf8"));
+            this.sent = parsed.sent ?? {};
+        }
+        catch {
+            this.sent = {};
+        }
+    }
+    static fileFor(stateDir, port) {
+        return join(stateDir, `lyrics-published-${port}.json`);
+    }
+    save() {
+        mkdirSync(dirname(this.options.file), { recursive: true });
+        const temporary = `${this.options.file}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify({ version: 1, sent: this.sent }, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, this.options.file);
+    }
+    /** Something changed (a station, the library): publish what is new, shortly. Nothing without a key. */
+    soon() {
+        // A run is already due: changes in a burst ride on it (a busy store saves often).
+        if (!this.options.key() || this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.publishAll().catch(() => undefined);
+        }, this.options.debounceMs ?? 30_000);
+        this.timer.unref?.();
+    }
+    status() {
+        const eligible = this.options.stations().filter(mayPublishLyrics);
+        return {
+            key: this.options.key() !== "",
+            target: this.base,
+            published: Object.keys(this.sent).length,
+            running: this.running !== null,
+            last: this.last,
+            lastError: this.lastError,
+            stations: this.options.stations().map((one) => ({
+                id: one.id,
+                name: one.name,
+                eligible: mayPublishLyrics(one),
+                why: whyNotPublish(one),
+                files: one.items.length,
+                published: one.items.filter((file) => this.sent[file]).length,
+            })),
+            eligible: eligible.length,
+        };
+    }
+    /** Every eligible station, one after another; a run already going is joined, not doubled. */
+    publishAll() {
+        if (this.running)
+            return this.running;
+        this.running = (async () => {
+            const reports = [];
+            for (const station of this.options.stations().filter(mayPublishLyrics)) {
+                const report = await this.publishOne(station);
+                reports.push(report);
+                if (report.stopped)
+                    break;
+            }
+            this.last = { at: Date.now(), reports };
+            const sent = reports.reduce((sum, one) => sum + one.published, 0);
+            if (sent > 0)
+                this.options.log?.(`  lyrics: published ${sent} to ${this.base}.`);
+            return reports;
+        })().finally(() => { this.running = null; });
+        return this.running;
+    }
+    /** One station, now. Refused (stopped says why) when it may not be published or there is no key. */
+    async publish(station) {
+        if (this.running)
+            await this.running.catch(() => undefined);
+        return this.publishOne(station);
+    }
+    async publishOne(station) {
+        const report = { station: station.id, published: 0, unchanged: 0, without: 0, failed: 0, stopped: "" };
+        const why = whyNotPublish(station);
+        if (why) {
+            report.stopped = `not published: ${why}`;
+            return report;
+        }
+        const key = this.options.key();
+        if (!key) {
+            report.stopped = "no key: set NIXAMP_LYRICS_KEY or `nixamp station lyrics key`";
+            return report;
+        }
+        if (!this.base) {
+            report.stopped = "no target: NIXAMP_LYRICS_URL is empty";
+            return report;
+        }
+        let first = true;
+        for (const file of station.items) {
+            let tags = {};
+            try {
+                tags = await this.options.tags(file);
+            }
+            catch {
+                tags = {};
+            }
+            const words = lyricsFromTags(tags);
+            const known = this.options.known?.(file) ?? null;
+            const title = tags["title"] || known?.title || "";
+            const artist = tags["artist"] || tags["album_artist"] || known?.artist || "";
+            const album = tags["album"] || known?.album || "";
+            if (!words || !title || !artist) {
+                report.without += 1;
+                continue;
+            }
+            const hash = createHash("sha256").update(`${artist}\n${title}\n${words.text}`).digest("hex");
+            if (this.sent[file]?.hash === hash) {
+                report.unchanged += 1;
+                continue;
+            }
+            if (!first)
+                await new Promise((done) => setTimeout(done, this.options.gapMs ?? 1_000));
+            first = false;
+            let response;
+            try {
+                response = await this.fetcher(`${this.base}/api/v1/lyrics`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json", accept: "application/json", authorization: `Bearer ${key}` },
+                    body: JSON.stringify({ artist, title, album, language: words.language, text: words.text, source: "embedded" }),
+                    signal: AbortSignal.timeout(15_000),
+                });
+            }
+            catch (error) {
+                report.failed += 1;
+                this.lastError = `could not reach ${this.base}: ${error.message}`;
+                report.stopped = this.lastError;
+                break;
+            }
+            if (response.ok) {
+                this.sent[file] = { hash, at: Date.now(), artist, title };
+                this.save();
+                report.published += 1;
+                continue;
+            }
+            report.failed += 1;
+            const detail = (await response.text().catch(() => "")).slice(0, 200);
+            this.lastError = `nichedb answered ${response.status} for "${title}"${detail ? `: ${detail}` : ""}`;
+            if (response.status === 401 || response.status === 403 || response.status === 429 || response.status >= 500) {
+                report.stopped = this.lastError;
+                break;
+            }
+        }
+        return report;
+    }
+}

package/dist/lyrics.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 declare const NICHEDB_LYRICS = "https://nichedb.dev";
+/** Text as it may be shown: newlines kept, control characters gone, trimmed, capped. */
+export declare function cleanLyrics(text: string): string;
+/** The words a file's own tags carry (lower-cased names, as TagReader gives them), or null. */
+export declare function lyricsFromTags(tags: Record<string, string>): {
+    text: string;
+    language: string;
+} | null;
+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 declare class LyricsFinder {
+    private readonly options;
+    private remote;
+    private asking;
+    private readonly base;
+    private readonly fetcher;
+    private readonly ttl;
+    private readonly timeout;
+    private readonly now;
+    constructor(options: LyricsFinderOptions);
+    /** The file's words, or null. Never throws; never waits on nichedb longer than the timeout. */
+    find(file: string): Promise<Lyrics | null>;
+    /** What nichedb has for this artist and title, kept for ten minutes. */
+    lookup(artist: string, title: string): Promise<Lyrics | null>;
+    private ask;
+}
+export {};

package/dist/lyrics.js

@@ -0,0 +1,145 @@
+/**
+ * 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 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 = {
+    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) {
+    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) {
+    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) {
+    let best = 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;
+}
+/** Finds a file's words, from its tags, else from nichedb. */
+export class LyricsFinder {
+    options;
+    remote = new Map();
+    asking = new Map();
+    base;
+    fetcher;
+    ttl;
+    timeout;
+    now;
+    constructor(options) {
+        this.options = options;
+        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) {
+        let tags = {};
+        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, title) {
+        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;
+    }
+    async ask(artist, title) {
+        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();
+            const found = body?.lyrics;
+            const text = typeof found?.["text"] === "string" ? cleanLyrics(found["text"]) : "";
+            if (!text)
+                return null;
+            const string = (name) => (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/dist/server.d.ts

@@ -606,6 +606,10 @@ export interface HandlerOptions {
             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. */

package/dist/server.js

@@ -65,6 +65,9 @@ import { AiRadio } from "./ai-radio.js";
 import { ListenerShares } from "./listener-shares.js";
 import { HolderStore, TagReader, factsFor } from "./track-facts.js";
 import { SUPPORT_CSP, SUPPORT_PAGE, Support, SupportError, SupportSubscriptions, supportHoldersFrom } from "./support.js";
+import { LyricsFinder } from "./lyrics.js";
+import { LyricsPublisher } from "./lyrics-publish.js";
+import { aiKey } from "./ai-keys.js";
 import { STATION_APP_CSP, STATION_PAGE, STATION_PAGE_CSP, STATION_PAGE_HTML } from "./station-page.js";
 import { GUIDE_CSP, guideHosts, guidePeers, peerBase, PeerGuides, renderGuide } from "./station-guide.js";
 import { StationRunner } from "./station-runner.js";
@@ -2468,6 +2471,8 @@ export function createHandler(engine, options) {
                 ...(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);
@@ -6624,6 +6629,27 @@ export async function serve(argv, version = "0.1.0") {
         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);
@@ -6636,8 +6662,10 @@ export async function serve(argv, version = "0.1.0") {
             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),

package/dist/station-cli.js

@@ -265,6 +265,8 @@ export async function station(argv) {
                 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";
@@ -417,6 +419,46 @@ async function aiCommand(argv, call, show, json) {
             return 2;
     }
 }
+/** `nixamp station lyrics ...`: our own songs' words, published back to nichedb.dev. */
+async function lyricsCommand(argv, call, show, json) {
+    const [sub, id] = argv;
+    switch (sub) {
+        case undefined:
+        case "status":
+            return show(await call("GET", "/api/v1/stations/lyrics"), (body) => {
+                const stations = body["stations"] ?? [];
+                const last = body["last"];
+                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"];
+                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"] ?? {})["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, call, show) {
     const [sub, id] = argv;