nixamp 0.39.2 → 0.40.1

package/dist/station-routes.d.ts

@@ -16,6 +16,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Channels } from "./channels.ts";
 import type { StationRunner } from "./station-runner.ts";
 import { type Limits, type StationUsage } from "./station-metering.ts";
+import { type TrackFacts } from "./track-facts.ts";
 import { type OwnerStation, type PublicStation, type Station, type StationStore } from "./stations.ts";
 /** Whether this path is one a station's own link may open, without the server's key. */
 export declare function isStationListenPath(path: string): boolean;
@@ -59,6 +60,8 @@ export interface StationContext {
     throttle?: () => {
         retryAfter: number;
     } | null;
+    /** What a listener may know about the track on the air (track-facts.ts). */
+    facts?: (station: Station, file: string) => Promise<TrackFacts>;
     /** Auto stations: run a sync with these settings (and keep them), or read them. */
     auto?: {
         sync: (input: Record<string, unknown>) => Promise<unknown>;

package/dist/station-routes.js

@@ -1,7 +1,8 @@
 import { alertsFor } from "./station-metering.js";
+import { aiFromTags } from "./track-facts.js";
 import { StationError, channelOf, tokensMatch, } from "./stations.js";
 /** The three things a station's link opens. */
-const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u|events)$/;
+const LISTEN = /^\/api\/v1\/stations\/([a-z0-9]{10})\/(stream|state|listen\.m3u|events|now)$/;
 /** Whether this path is one a station's own link may open, without the server's key. */
 export function isStationListenPath(path) {
     return LISTEN.test(path) || path === "/api/v1/stations/guide";
@@ -56,6 +57,9 @@ export function publicView(ctx, station) {
 export function guideGroup(station) {
     if (station.auto.startsWith("ai:"))
         return "ai";
+    // A station whose owner declared the music AI-made ("made with Suno") is AI radio too.
+    if (station.rights?.basis === "owned" && aiFromTags({ comment: station.rights.note }))
+        return "ai";
     if (station.auto.startsWith("share:"))
         return "shared";
     return station.video ? "tv" : "radio";
@@ -137,7 +141,21 @@ export async function handleStations(request, response, path, url, ctx) {
                 const view = publicView(ctx, station);
                 return { station: station.id, playback: `${station.id}:${ctx.channels.info(channelOf(station.id))?.startedAt ?? 0}`, track: `${station.id}:${instance}`, at: Date.now(), state: view.state, nowPlaying: view.nowPlaying };
             };
-            send("hello", now());
+            // Each "now" carries what is known about the track: who made it, AI or
+            // not, whose copyright, how to support them.
+            const withFacts = async () => {
+                const payload = now();
+                const file = nowPlayingFile(ctx, station);
+                if (!ctx.facts || !file)
+                    return payload;
+                try {
+                    return { ...payload, facts: await ctx.facts(station, file) };
+                }
+                catch {
+                    return payload;
+                }
+            };
+            void withFacts().then((payload) => send("hello", payload));
             const tick = setInterval(() => {
                 const current = ctx.store.get(station.id);
                 if (!current) {
@@ -149,7 +167,7 @@ export async function handleStations(request, response, path, url, ctx) {
                 if (file !== lastFile) {
                     lastFile = file;
                     instance += 1;
-                    send("now", now());
+                    void withFacts().then((payload) => send("now", payload));
                 }
                 else if (state !== lastState) {
                     send("state", now());
@@ -169,6 +187,11 @@ export async function handleStations(request, response, path, url, ctx) {
             response.on("close", leave);
             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 });
+            return true;
+        }
         if (what === "state") {
             ctx.json(response, 200, publicView(ctx, station));
             return true;

package/dist/station-usage.d.ts

@@ -1,2 +1,2 @@
 /** `nixamp station` usage, apart so `nixamp help station` does not load the client. */
-export declare const USAGE = "nixamp station \u2014 make a collection into a station\n\n  nixamp station list\n  nixamp station create --name NAME (--folder PATH | --playlist ID | --items 0,1,2) [--shuffle] [--no-repeat] [--bitrate 128] [--breaks 600]\n  nixamp station show ID\n  nixamp station status ID\n  nixamp station start ID\n  nixamp station stop ID\n  nixamp station skip ID\n  nixamp station breaks ID SECONDS a spot between entries every SECONDS (120..86400; --off for none)\n  nixamp station retry ID          try every left-out file again\n  nixamp station publish ID --basis owned|permission|licensed|public-domain [--note TEXT] [--unlisted] [--no-list]\n  nixamp station unpublish ID [--private]\n  nixamp station link ID [--rotate]\n  nixamp station delete ID\n  nixamp station guide-host NAME [--remove]\n                     NAME's front page is the public station guide (e.g. a Moshpit name)\n  nixamp station guide-peer URL [--remove]\n                     the guide also lists the public, listed stations of the server at URL\n  nixamp station auto [--no-video] [--min 10] [--films 3] [--tv 2] [--breaks 600] [--no-start]\n                     a station per genre, kept in step with the library (--off stops it)\n\n  AI radio (music composed for a station, a few tracks a day):\n  nixamp station ai                          what is composing, this month's seconds, the stations\n  nixamp station ai create (--preset lofi|synthwave|ambient|chiptune|punk|jazz | --name NAME --style TEXT)\n                     [--vocals] [--seconds 120] [--per-day 2] [--unlisted]   public on the guide unless --unlisted\n  nixamp station ai generate KEY             compose one now\n  nixamp station ai set KEY [--style TEXT] [--per-day N] [--seconds N] [--off|--on]\n  nixamp station ai remove KEY [--files]\n  nixamp station ai budget SECONDS           seconds of music a month across AI stations (0: no cap)\n  nixamp station ai resume                   after the provider ran out of credit\n  nixamp station ai key NAME                 ELEVENLABS_API_KEY | GEMINI_API_KEY | OPENAI_API_KEY | ANTHROPIC_API_KEY,\n                                             NIXAMP_OPENAI_URL | NIXAMP_OPENAI_MODEL (an OpenAI-compatible stand-in), from stdin\n\n  Listener shares (anybody shares an MP3 link or file from the guide; AI files and checks it):\n  nixamp station shares                      the setting and what is waiting\n  nixamp station shares on [--owner-moderation] [--unlisted] [--max-mb 60] [--per-hour 6]\n  nixamp station shares off\n  nixamp station shares list [--state held|approved|reported|rejected]\n  nixamp station shares approve|reject|delete SHARE\n  nixamp station shares trust ADDRESS [--remove]   believe this proxy's X-Forwarded-For\n\n  --json        machine-readable output\n  --url, --key  another server, as with `nixamp admin`\n\nA new station is private and stopped. Starting it does not publish it.";
+export declare const USAGE = "nixamp station \u2014 make a collection into a station\n\n  nixamp station list\n  nixamp station create --name NAME (--folder PATH | --playlist ID | --items 0,1,2) [--shuffle] [--no-repeat] [--bitrate 128] [--breaks 600]\n  nixamp station show ID\n  nixamp station status ID\n  nixamp station start ID\n  nixamp station stop ID\n  nixamp station skip ID\n  nixamp station breaks ID SECONDS a spot between entries every SECONDS (120..86400; --off for none)\n  nixamp station retry ID          try every left-out file again\n  nixamp station publish ID --basis owned|permission|licensed|public-domain [--note TEXT] [--unlisted] [--no-list]\n  nixamp station unpublish ID [--private]\n  nixamp station link ID [--rotate]\n  nixamp station delete ID\n  nixamp station guide-host NAME [--remove]\n                     NAME's front page is the public station guide (e.g. a Moshpit name)\n  nixamp station guide-peer URL [--remove]\n                     the guide also lists the public, listed stations of the server at URL\n  nixamp station auto [--no-video] [--min 10] [--films 3] [--tv 2] [--breaks 600] [--no-start]\n                     a station per genre, kept in step with the library (--off stops it)\n\n  AI radio (music composed for a station, a few tracks a day):\n  nixamp station ai                          what is composing, this month's seconds, the stations\n  nixamp station ai create (--preset lofi|synthwave|ambient|chiptune|punk|jazz | --name NAME --style TEXT)\n                     [--vocals] [--seconds 120] [--per-day 2] [--unlisted]   public on the guide unless --unlisted\n  nixamp station ai generate KEY             compose one now\n  nixamp station ai set KEY [--style TEXT] [--per-day N] [--seconds N] [--off|--on]\n  nixamp station ai remove KEY [--files]\n  nixamp station ai budget SECONDS           seconds of music a month across AI stations (0: no cap)\n  nixamp station ai resume                   after the provider ran out of credit\n  nixamp station ai key NAME                 ELEVENLABS_API_KEY | GEMINI_API_KEY | OPENAI_API_KEY | ANTHROPIC_API_KEY,\n                                             NIXAMP_OPENAI_URL | NIXAMP_OPENAI_MODEL (an OpenAI-compatible stand-in), from stdin\n\n  Listener shares (anybody shares an MP3 link or file from the guide; AI files and checks it):\n  nixamp station shares                      the setting and what is waiting\n  nixamp station shares on [--owner-moderation] [--unlisted] [--max-mb 60] [--per-hour 6]\n  nixamp station shares off\n  nixamp station shares list [--state held|approved|reported|rejected]\n  nixamp station shares approve|reject|delete SHARE\n  nixamp station shares trust ADDRESS [--remove]   believe this proxy's X-Forwarded-For\n\n  Copyright holders (the now-playing card: who holds a track's copyright, and how to support them):\n  nixamp station holder list\n  nixamp station holder set NAME [--artist ARTIST]... [--station ID]... [--support https://...] [--label Subscribe] [--license TEXT]\n  nixamp station holder remove ID\n\n  --json        machine-readable output\n  --url, --key  another server, as with `nixamp admin`\n\nA new station is private and stopped. Starting it does not publish it.";

package/dist/station-usage.js

@@ -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
 
+  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]
+  nixamp station holder remove ID
+
   --json        machine-readable output
   --url, --key  another server, as with \`nixamp admin\`
 

package/dist/support.d.ts

@@ -0,0 +1,43 @@
+export interface SupportHolder {
+    id: string;
+    name: string;
+}
+export declare function supportHoldersFrom(env?: Record<string, string | undefined>): SupportHolder[];
+export declare const AMOUNTS: number[];
+export declare class SupportError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status?: number, code?: string);
+}
+export declare class Support {
+    private readonly options;
+    private merchant;
+    private merchantUntil;
+    constructor(options: {
+        key: string;
+        site: string;
+        holders: SupportHolder[];
+        fetcher?: typeof fetch;
+        now?: () => number;
+    });
+    holder(id: string): SupportHolder | undefined;
+    get enabled(): boolean;
+    private provider;
+    /** The business and the coins it has a wallet for, asked at most every 10 minutes. */
+    coins(): Promise<{
+        business: string;
+        coins: string[];
+    }>;
+    /** A CoinPay checkout for this much, to this holder; the address to send the payer to. */
+    checkout(input: {
+        holder?: unknown;
+        amountUsd?: unknown;
+        coin?: unknown;
+        station?: unknown;
+        track?: unknown;
+    }): Promise<{
+        url: string;
+    }>;
+}
+export declare const SUPPORT_PAGE: string;
+export declare const SUPPORT_CSP: string;

package/dist/support.js

@@ -0,0 +1,203 @@
+/**
+ * Support a copyright holder: a payment through nixamp.com's own CoinPay
+ * business, for the holders whose money that business may take.
+ *
+ * A station's now-playing card links a track's holder to their support page.
+ * Holders who collect for themselves register their own link on the station
+ * (`nixamp station holder set NAME --support URL`); this page is for the
+ * holders nixamp.com collects for -- today Profullstack's own music (the
+ * band Þrøngva, AI radio) -- named in NIXAMP_SUPPORT_HOLDERS ("id=Name,...").
+ *
+ * One payment, in crypto, on CoinPay's hosted checkout. CoinPay offers no
+ * crypto subscription a business key can start (its plan/subscribe API is
+ * Stripe's, which we do not use), so "monthly" is not offered rather than
+ * pretended.
+ */
+import { createHash, randomUUID } from "node:crypto";
+export function supportHoldersFrom(env = process.env) {
+    const raw = env["NIXAMP_SUPPORT_HOLDERS"] ?? "profullstack=Profullstack";
+    return raw.split(",").map((one) => one.trim()).filter(Boolean).map((one) => {
+        const [id, ...name] = one.split("=");
+        return { id: (id ?? "").trim().toLowerCase(), name: name.join("=").trim() || (id ?? "").trim() };
+    }).filter((one) => /^[a-z0-9-]{1,40}$/.test(one.id));
+}
+export const AMOUNTS = [3, 5, 10, 25, 50];
+const MIN_USD = 1;
+const MAX_USD = 1000;
+export class SupportError extends Error {
+    status;
+    code;
+    constructor(message, status = 400, code = "invalid") {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export class Support {
+    options;
+    merchant = null;
+    merchantUntil = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    holder(id) {
+        return this.options.holders.find((one) => one.id === id.toLowerCase());
+    }
+    get enabled() {
+        return Boolean(this.options.key);
+    }
+    async provider(path, init = {}) {
+        if (!this.options.key)
+            throw new SupportError("Support payments are not set up here.", 503, "unavailable");
+        const response = await (this.options.fetcher ?? fetch)(`https://coinpayportal.com${path}`, {
+            ...init,
+            signal: AbortSignal.timeout(15_000),
+            headers: { authorization: `Bearer ${this.options.key}`, "content-type": "application/json", ...(init.headers ?? {}) },
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok || body["success"] !== true)
+            throw new SupportError("The payment service did not answer; nothing was charged. Try again.", 502, "provider");
+        return body;
+    }
+    /** The business and the coins it has a wallet for, asked at most every 10 minutes. */
+    async coins() {
+        const now = this.options.now?.() ?? Date.now();
+        if (!this.merchant || now >= this.merchantUntil) {
+            this.merchantUntil = now + 600_000;
+            this.merchant = this.provider("/api/supported-coins").then((body) => {
+                const business = String(body["business_id"] ?? "");
+                if (!/^[0-9a-f-]{36}$/.test(business))
+                    throw new SupportError("Support payments are not set up here.", 503, "unavailable");
+                const coins = (Array.isArray(body["coins"]) ? body["coins"] : [])
+                    .filter((coin) => typeof coin === "object" && coin !== null)
+                    .filter((coin) => coin.is_active && coin.has_wallet && typeof coin.symbol === "string")
+                    .map((coin) => coin.symbol);
+                return { business, coins };
+            }).catch((error) => { this.merchant = null; throw error; });
+        }
+        return this.merchant;
+    }
+    /** A CoinPay checkout for this much, to this holder; the address to send the payer to. */
+    async checkout(input) {
+        const holder = typeof input.holder === "string" ? this.holder(input.holder) : undefined;
+        if (!holder)
+            throw new SupportError("Nobody by that name is supported here.", 404, "not_found");
+        const amount = Number(input.amountUsd);
+        if (!Number.isFinite(amount) || amount < MIN_USD || amount > MAX_USD)
+            throw new SupportError(`Choose an amount from $${MIN_USD} to $${MAX_USD}.`, 400, "invalid_amount");
+        const { business, coins } = await this.coins();
+        const coin = typeof input.coin === "string" ? input.coin.toUpperCase() : "";
+        if (!coins.includes(coin))
+            throw new SupportError(`Pay with one of: ${coins.join(", ")}.`, 400, "invalid_coin");
+        const clean = (value) => (typeof value === "string" ? value.replace(/[\u0000-\u001f]/g, " ").slice(0, 120) : "");
+        const order = randomUUID();
+        const created = await this.provider("/api/payments/create", {
+            method: "POST",
+            headers: { "idempotency-key": `nixamp-support-${order}` },
+            body: JSON.stringify({
+                business_id: business,
+                amount_usd: Math.round(amount * 100) / 100,
+                currency: coin.toLowerCase(),
+                payment_method: "crypto",
+                description: `Support ${holder.name} on nixamp`,
+                metadata: { app: "nixamp", product: "support", holder: holder.id, order, station: clean(input.station), track: clean(input.track) },
+                redirect_url: `${this.options.site}/support/${holder.id}?thanks=1`,
+            }),
+        });
+        const payment = created["payment"];
+        const id = typeof payment?.id === "string" ? payment.id : "";
+        if (!/^[A-Za-z0-9_-]{6,80}$/.test(id))
+            throw new SupportError("The checkout did not start; nothing was charged. Try again.", 502, "provider");
+        return { url: `https://coinpayportal.com/pay/${id}` };
+    }
+}
+const STYLE = `
+:root{--bg:#080c09;--fg:#e8efe9;--muted:#9aa79d;--card:#0e1410;--line:#1f2a22;--accent:#3ddc84}
+*{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}
+main{max-width:520px;margin:0 auto;padding:48px 16px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}
+h1{margin:0 0 6px;font-size:1.5rem}p{color:var(--muted);margin:0 0 18px}
+.amounts{display:flex;flex-wrap:wrap;gap:8px;margin:0 0 14px}
+.amounts button{flex:1 1 64px;padding:10px;border-radius:10px;border:1px solid var(--line);background:transparent;color:var(--fg);font:inherit;font-weight:700;cursor:pointer}
+.amounts button[aria-pressed=true]{border-color:var(--accent);color:var(--accent)}
+label{display:block;color:var(--muted);font-size:.9rem;margin:10px 0 4px}
+input,select{width:100%;padding:10px;border-radius:10px;border:1px solid var(--line);background:var(--bg);color:var(--fg);font:inherit}
+button.go{margin-top:18px;width:100%;padding:12px;border:0;border-radius:999px;background:var(--accent);color:#06120a;font:inherit;font-weight:800;cursor:pointer}
+button:focus-visible,input:focus-visible,select:focus-visible{outline:3px solid var(--accent);outline-offset:2px}
+#status{min-height:1.4em;margin-top:12px;color:var(--muted)}
+.thanks{color:var(--accent);font-weight:700}
+small{display:block;margin-top:18px;color:var(--muted)}small a{color:inherit}
+`;
+const SCRIPT = `
+(async () => {
+  const holder = location.pathname.split("/").filter(Boolean)[1] || "";
+  const params = new URLSearchParams(location.search);
+  const $ = (s) => document.querySelector(s);
+  let amount = 5;
+  for (const b of document.querySelectorAll(".amounts button")) {
+    b.addEventListener("click", () => {
+      amount = Number(b.dataset.usd);
+      $("#other").value = "";
+      for (const o of document.querySelectorAll(".amounts button")) o.setAttribute("aria-pressed", String(o === b));
+    });
+  }
+  if (params.get("thanks")) { $("#status").className = "thanks"; $("#status").textContent = "Thank you. Your payment is on its way."; }
+  try {
+    const info = await (await fetch("/api/v1/support/" + encodeURIComponent(holder), { cache: "no-store" })).json();
+    if (info.name) { $("#who").textContent = info.name; document.title = "Support " + info.name + " · nixamp"; }
+    const coins = info.coins || [];
+    $("#coin").replaceChildren(...coins.map((c) => { const o = document.createElement("option"); o.value = c; o.textContent = c.replace(/_/g, " "); return o; }));
+    if (!coins.length) { $("#go").disabled = true; $("#status").textContent = info.error || "Payments are not available right now."; }
+  } catch { $("#status").textContent = "Payments are not available right now."; }
+  $("#form").addEventListener("submit", async (event) => {
+    event.preventDefault();
+    const other = Number($("#other").value);
+    const usd = other > 0 ? other : amount;
+    $("#go").disabled = true;
+    $("#status").textContent = "Starting the checkout…";
+    try {
+      const r = await fetch("/api/v1/support/" + encodeURIComponent(holder), { method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ amountUsd: usd, coin: $("#coin").value, station: params.get("station") || "", track: params.get("track") || "" }) });
+      const body = await r.json();
+      if (r.ok && body.url) { location.href = body.url; return; }
+      $("#status").textContent = body.error || "That did not work.";
+    } catch { $("#status").textContent = "Could not reach the payment service."; }
+    $("#go").disabled = false;
+  });
+})();
+`;
+const hash = (text) => `'sha256-${createHash("sha256").update(text).digest("base64")}'`;
+export const SUPPORT_PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Support · nixamp</title>
+<link rel="icon" href="/favicon.png">
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+  <div class="card">
+    <h1>Support <span id="who">the artist</span></h1>
+    <p>Pay the copyright holder of the music you are listening to, directly. One payment, in crypto, through CoinPay.</p>
+    <form id="form">
+      <div class="amounts">${AMOUNTS.map((usd, at) => `<button type="button" data-usd="${usd}" aria-pressed="${at === 1}">$${usd}</button>`).join("")}</div>
+      <label for="other">Or another amount (US$)</label>
+      <input id="other" type="number" min="1" max="1000" step="1" inputmode="numeric">
+      <label for="coin">Pay with</label>
+      <select id="coin"></select>
+      <button id="go" class="go" type="submit">Continue to payment</button>
+      <div id="status" role="status" aria-live="polite"></div>
+    </form>
+    <small>Payments go through <a href="https://coinpayportal.com">CoinPay</a> to nixamp.com, which pays the holder. Nothing recurs.</small>
+  </div>
+</main>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+export const SUPPORT_CSP = [
+    "default-src 'none'", `script-src ${hash(SCRIPT)}`, `style-src ${hash(STYLE)}`, "connect-src 'self'",
+    "img-src 'self' data:", "base-uri 'none'", "form-action 'none'", "frame-ancestors 'none'",
+].join("; ");

package/dist/track-facts.d.ts

@@ -0,0 +1,88 @@
+import type { Station } from "./stations.ts";
+export interface TrackFacts {
+    title: string;
+    artist: string;
+    album: string;
+    year: string;
+    genre: string;
+    ai: {
+        generated: boolean | null;
+        by: string;
+        evidence: string;
+    };
+    rights: {
+        holder: string;
+        basis: string;
+        note: string;
+        license: string;
+        source: "tag" | "holder" | "share" | "ai-radio" | "station" | "";
+    };
+    support: {
+        holder: string;
+        url: string;
+        label: string;
+    } | null;
+}
+export interface Holder {
+    id: string;
+    name: string;
+    /** Artist names (as tagged) whose tracks are theirs; case does not matter. */
+    artists: string[];
+    /** Stations whose every track is theirs. */
+    stations: string[];
+    /** Where a listener supports them: a subscription or donation page (https). */
+    support: string;
+    /** The button's words, e.g. "Subscribe" or "Donate". */
+    label: string;
+    /** e.g. "All rights reserved", "CC BY 4.0". */
+    license: string;
+}
+/** The tags ffprobe reads from a file, lower-cased, cached by size and time. */
+export declare class TagReader {
+    private readonly ffprobe;
+    private cache;
+    constructor(ffprobe: string[]);
+    /** Known now, or {} while it is read in the background. */
+    known(path: string): Record<string, string> | null;
+    read(path: string): Promise<Record<string, string>>;
+}
+/** Whether these tags say the track was made by AI, and with what. */
+export declare function aiFromTags(tags: Record<string, string>): {
+    by: string;
+    evidence: string;
+} | null;
+export interface FactSources {
+    station: Station;
+    file: string;
+    tags: Record<string, string>;
+    /** What the library knows when the file has no tag for it. */
+    known?: {
+        title: string;
+        artist: string;
+        album: string;
+    } | null;
+    holders: Holder[];
+    /** A listener's share of this file, when it is one. */
+    share?: {
+        basis: string;
+        note: string;
+        by: string;
+    } | null;
+    /** AI radio's record of this file, when it composed it. */
+    aiTrack?: {
+        made: string;
+    } | null;
+}
+export declare function factsFor(input: FactSources): TrackFacts;
+/** The copyright holders this server's owner registered. */
+export declare class HolderStore {
+    private readonly file;
+    private holders;
+    constructor(file: string);
+    static fileFor(stateDir: string, port: number): string;
+    private save;
+    list(): Holder[];
+    /** Make or change a holder, found by id or by name. */
+    set(input: Record<string, unknown>): Holder;
+    remove(id: string): boolean;
+}

package/dist/track-facts.js

@@ -0,0 +1,220 @@
+/**
+ * What a listener may know about the track on the air: who made it, whether
+ * it was made by AI, who holds its copyright, and how to support them.
+ *
+ * Gathered from what is already known, never guessed into a fact:
+ *  - the file's own tags (title, artist, album, year, genre, and the
+ *    copyright, publisher, comment and encoder tags ffprobe reads);
+ *  - where it came from on this server: composed by AI radio, shared by a
+ *    listener (with their declaration), or the station's own declared basis;
+ *  - the copyright holders the owner registered (`nixamp station holder`),
+ *    matched by artist or station, with the link that supports them.
+ * "AI-generated" is true only on evidence (a tag naming Suno, Udio,
+ * ElevenLabs...; AI radio's own files), and null -- not stated -- otherwise.
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { StationError } from "./stations.js";
+/** The tags ffprobe reads from a file, lower-cased, cached by size and time. */
+export class TagReader {
+    ffprobe;
+    cache = new Map();
+    constructor(ffprobe) {
+        this.ffprobe = ffprobe;
+    }
+    /** Known now, or {} while it is read in the background. */
+    known(path) {
+        const hit = this.cache.get(path);
+        if (!hit)
+            return null;
+        try {
+            const info = statSync(path);
+            return hit.key === `${info.size}:${info.mtimeMs}` ? hit.tags : null;
+        }
+        catch {
+            return hit.tags;
+        }
+    }
+    read(path) {
+        const known = this.known(path);
+        if (known)
+            return Promise.resolve(known);
+        const [command, ...prefix] = this.ffprobe;
+        if (!command)
+            return Promise.resolve({});
+        return new Promise((done) => {
+            const child = spawn(command, [...prefix, "-v", "error", "-print_format", "json", "-show_entries", "format_tags:stream_tags", path], { stdio: ["ignore", "pipe", "ignore"] });
+            let out = "";
+            const timer = setTimeout(() => child.kill("SIGKILL"), 10_000);
+            timer.unref?.();
+            child.stdout.on("data", (chunk) => { if (out.length < 1024 * 1024)
+                out += chunk.toString("utf8"); });
+            child.on("error", () => { clearTimeout(timer); done({}); });
+            child.on("close", () => {
+                clearTimeout(timer);
+                const tags = {};
+                try {
+                    const parsed = JSON.parse(out);
+                    for (const source of [...(parsed.streams ?? []).map((one) => one.tags ?? {}), parsed.format?.tags ?? {}]) {
+                        for (const [name, value] of Object.entries(source))
+                            if (typeof value === "string")
+                                tags[name.toLowerCase()] = value.slice(0, 2000);
+                    }
+                }
+                catch {
+                    // No tags is an answer too.
+                }
+                try {
+                    const info = statSync(path);
+                    if (this.cache.size > 5000)
+                        this.cache.clear();
+                    this.cache.set(path, { key: `${info.size}:${info.mtimeMs}`, tags });
+                }
+                catch {
+                    // Gone already.
+                }
+                done(tags);
+            });
+        });
+    }
+}
+const AI_MARKS = [
+    [/\bsuno\b/i, "Suno"],
+    [/\budio\b/i, "Udio"],
+    [/elevenlabs|eleven labs/i, "ElevenLabs Music"],
+    [/musicgen|audiocraft/i, "MusicGen"],
+    [/stable audio/i, "Stable Audio"],
+    [/riffusion/i, "Riffusion"],
+    [/ace-?step/i, "ACE-Step"],
+    [/mubert/i, "Mubert"],
+    [/\b(ai[- ]generated|generated (by|with) ai|made (by|with) ai)\b/i, "AI"],
+];
+/** Whether these tags say the track was made by AI, and with what. */
+export function aiFromTags(tags) {
+    for (const field of ["comment", "description", "encoded_by", "encoder", "software", "tsse", "publisher", "copyright", "genre"]) {
+        const value = tags[field];
+        if (!value)
+            continue;
+        // The encoder field is usually just "Lavf..." -- only a named model counts.
+        for (const [pattern, by] of AI_MARKS) {
+            if (pattern.test(value))
+                return { by, evidence: `${field} tag: "${value.slice(0, 120)}"` };
+        }
+    }
+    if (/^ai$/i.test(tags["genre"] ?? ""))
+        return { by: "AI", evidence: 'genre tag: "AI"' };
+    return null;
+}
+export function factsFor(input) {
+    const { station, tags } = input;
+    const title = tags["title"] || input.known?.title || "";
+    const artist = tags["artist"] || tags["album_artist"] || input.known?.artist || "";
+    const album = tags["album"] || input.known?.album || "";
+    const year = (tags["date"] || tags["year"] || tags["tdrc"] || "").slice(0, 4);
+    const genre = tags["genre"] || "";
+    const tagged = aiFromTags(tags);
+    const ai = input.aiTrack
+        ? { generated: true, by: input.aiTrack.made.split("+").pop()?.trim() || "AI", evidence: "composed for this station by AI radio" }
+        : tagged
+            ? { generated: true, by: tagged.by, evidence: tagged.evidence }
+            : { generated: null, by: "", evidence: "" };
+    const lower = artist.toLowerCase();
+    const holder = input.holders.find((one) => one.stations.includes(station.id))
+        ?? (lower ? input.holders.find((one) => one.artists.some((name) => name.toLowerCase() === lower)) : undefined);
+    const copyright = tags["copyright"] || tags["tcop"] || "";
+    let rights;
+    if (copyright) {
+        rights = { holder: copyright.replace(/^(\(c\)|©|copyright)\s*/i, "").slice(0, 200), basis: "", note: "", license: holder?.license ?? "", source: "tag" };
+    }
+    else if (holder) {
+        rights = { holder: holder.name, basis: station.rights?.basis ?? "", note: "", license: holder.license, source: "holder" };
+    }
+    else if (input.share) {
+        rights = { holder: input.share.by || "the person who shared it", basis: input.share.basis, note: input.share.note, license: input.share.basis === "creative-commons" || input.share.basis === "public-domain" ? input.share.note : "", source: "share" };
+    }
+    else if (input.aiTrack) {
+        rights = { holder: "this station's owner", basis: "owned", note: station.rights?.note ?? "", license: "", source: "ai-radio" };
+    }
+    else if (station.rights) {
+        rights = { holder: "", basis: station.rights.basis, note: station.rights.note, license: "", source: "station" };
+    }
+    else {
+        rights = { holder: "", basis: "", note: "", license: "", source: "" };
+    }
+    const support = holder && holder.support ? { holder: holder.name, url: holder.support, label: holder.label || "Support" } : null;
+    return { title, artist, album, year, genre, ai, rights, support };
+}
+function slug(text) {
+    return text.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "holder";
+}
+/** The copyright holders this server's owner registered. */
+export class HolderStore {
+    file;
+    holders = new Map();
+    constructor(file) {
+        this.file = file;
+        try {
+            const parsed = JSON.parse(readFileSync(file, "utf8"));
+            for (const one of parsed.holders ?? [])
+                if (one?.id)
+                    this.holders.set(one.id, one);
+        }
+        catch {
+            // None yet.
+        }
+    }
+    static fileFor(stateDir, port) {
+        return join(stateDir, `holders-${port}.json`);
+    }
+    save() {
+        mkdirSync(dirname(this.file), { recursive: true });
+        const temporary = `${this.file}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify({ version: 1, holders: [...this.holders.values()] }, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, this.file);
+    }
+    list() {
+        return [...this.holders.values()];
+    }
+    /** Make or change a holder, found by id or by name. */
+    set(input) {
+        const name = typeof input["name"] === "string" ? input["name"].replace(/[\u0000-\u001f]/g, " ").trim().slice(0, 120) : "";
+        const id = typeof input["id"] === "string" && input["id"] ? input["id"] : slug(name);
+        const existing = this.holders.get(id);
+        if (!existing && !name)
+            throw new StationError("name_required", "a copyright holder needs a name");
+        const words = (value) => Array.isArray(value)
+            ? value.filter((one) => typeof one === "string").map((one) => one.trim().slice(0, 120)).filter(Boolean).slice(0, 100)
+            : undefined;
+        const support = typeof input["support"] === "string" ? input["support"].trim() : undefined;
+        if (support) {
+            let url;
+            try {
+                url = new URL(support);
+            }
+            catch {
+                throw new StationError("invalid_support", "the support link is a web address (https://...)");
+            }
+            if (url.protocol !== "https:")
+                throw new StationError("invalid_support", "the support link must be https");
+        }
+        const holder = {
+            id,
+            name: name || existing.name,
+            artists: words(input["artists"]) ?? existing?.artists ?? [],
+            stations: (words(input["stations"]) ?? existing?.stations ?? []).filter((one) => /^[a-z0-9]{10}$/.test(one)),
+            support: support ?? existing?.support ?? "",
+            label: typeof input["label"] === "string" ? input["label"].trim().slice(0, 30) : existing?.label ?? "Support",
+            license: typeof input["license"] === "string" ? input["license"].trim().slice(0, 120) : existing?.license ?? "",
+        };
+        this.holders.set(id, holder);
+        this.save();
+        return holder;
+    }
+    remove(id) {
+        const had = this.holders.delete(id);
+        if (had)
+            this.save();
+        return had;
+    }
+}