nixamp 0.34.0 → 0.36.0

package/dist/station-guide.js

@@ -0,0 +1,86 @@
+/**
+ * The station guide: every station on this server its owner made public
+ * and listed, what is on each, and a way in. What a Moshpit name like
+ * live.streaming opens.
+ *
+ * Like the station page, the same bytes for every server: it asks
+ * /api/v1/stations/guide for the list and writes it in as text.
+ */
+import { createHash } from "node:crypto";
+const STYLE = `
+:root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b}
+@media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f}}
+*{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:880px;margin:0 auto;padding:40px 16px}
+h1{margin:0 0 4px;font-size:1.8rem}p.lead{color:var(--muted);margin:0 0 24px}
+h2{font-size:1rem;letter-spacing:.06em;text-transform:uppercase;color:var(--muted);margin:28px 0 10px}
+.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:12px}
+a.station{display:block;background:var(--card);border:1px solid var(--line);border-radius:14px;padding:16px;color:inherit;text-decoration:none}
+a.station:hover,a.station:focus-visible{border-color:var(--accent);outline:none}
+.name{font-weight:700;font-size:1.05rem}.now{color:var(--muted);font-size:.9rem;margin-top:6px;min-height:1.4em}
+.live{color:var(--live);font-size:.8rem;font-weight:700}.empty{color:var(--muted)}
+footer{margin-top:40px;color:var(--muted);font-size:.85rem}footer a{color:inherit}
+`;
+const SCRIPT = `
+(async () => {
+  const el = (tag, cls, text) => { const n = document.createElement(tag); if (cls) n.className = cls; if (text) n.textContent = text; return n; };
+  const draw = (stations) => {
+    for (const [kind, box] of [["audio", "#radio"], ["video", "#tv"]]) {
+      const grid = document.querySelector(box);
+      grid.replaceChildren();
+      const list = stations.filter((s) => s.kind === kind);
+      document.querySelector(box + "-title").hidden = list.length === 0;
+      for (const s of list) {
+        const a = el("a", "station");
+        a.href = s.page;
+        a.append(el("div", "live", s.state === "live" ? "● LIVE" : "off the air"), el("div", "name", s.name),
+          el("div", "now", s.nowPlaying ? [s.nowPlaying.title, s.nowPlaying.artist].filter(Boolean).join(" — ") : ""));
+        grid.append(a);
+      }
+    }
+    document.querySelector("#empty").hidden = stations.length > 0;
+  };
+  const load = async () => {
+    try {
+      const r = await fetch("/api/v1/stations/guide", { cache: "no-store" });
+      if (r.ok) draw((await r.json()).stations);
+    } catch {}
+  };
+  await load();
+  setInterval(load, 15000);
+})();
+`;
+const hash = (text) => `'sha256-${createHash("sha256").update(text).digest("base64")}'`;
+export const GUIDE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Live · stations</title>
+<meta name="description" content="Radio and TV stations, live now.">
+<link rel="icon" href="data:,">
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+  <h1>Live</h1>
+  <p class="lead">Radio and TV, on the air now. Pick one and press play.</p>
+  <h2 id="radio-title" hidden>Radio</h2>
+  <div id="radio" class="grid" aria-live="polite"></div>
+  <h2 id="tv-title" hidden>TV</h2>
+  <div id="tv" class="grid" aria-live="polite"></div>
+  <p id="empty" class="empty">Nothing is on the air here yet.</p>
+  <footer>Played by <a href="https://nixamp.com">nixamp</a>, on the Moshpit.</footer>
+</main>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+export const GUIDE_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("; ");
+/** The hosts whose front page is the guide (NIXAMP_GUIDE_HOSTS, comma-separated). */
+export function guideHosts(env = process.env) {
+    return new Set((env["NIXAMP_GUIDE_HOSTS"] ?? "").split(",").map((one) => one.trim().toLowerCase()).filter(Boolean));
+}

package/dist/station-mcp.d.ts

@@ -22,6 +22,13 @@ export declare const STATION_TOOLS: ({
             listed?: undefined;
             basis?: undefined;
             note?: undefined;
+            video?: undefined;
+            minItems?: undefined;
+            minFilms?: undefined;
+            maxVideoRunning?: undefined;
+            breaksEvery?: undefined;
+            start?: undefined;
+            off?: undefined;
             id?: undefined;
             private?: undefined;
         };
@@ -55,6 +62,13 @@ export declare const STATION_TOOLS: ({
             listed?: undefined;
             basis?: undefined;
             note?: undefined;
+            video?: undefined;
+            minItems?: undefined;
+            minFilms?: undefined;
+            maxVideoRunning?: undefined;
+            breaksEvery?: undefined;
+            start?: undefined;
+            off?: undefined;
             private?: undefined;
         };
         required: string[];
@@ -110,6 +124,13 @@ export declare const STATION_TOOLS: ({
             listed?: undefined;
             basis?: undefined;
             note?: undefined;
+            video?: undefined;
+            minItems?: undefined;
+            minFilms?: undefined;
+            maxVideoRunning?: undefined;
+            breaksEvery?: undefined;
+            start?: undefined;
+            off?: undefined;
             id?: undefined;
             private?: undefined;
         };
@@ -163,6 +184,13 @@ export declare const STATION_TOOLS: ({
             listed?: undefined;
             basis?: undefined;
             note?: undefined;
+            video?: undefined;
+            minItems?: undefined;
+            minFilms?: undefined;
+            maxVideoRunning?: undefined;
+            breaksEvery?: undefined;
+            start?: undefined;
+            off?: undefined;
             private?: undefined;
         };
         required: string[];
@@ -198,6 +226,13 @@ export declare const STATION_TOOLS: ({
             listed?: undefined;
             basis?: undefined;
             note?: undefined;
+            video?: undefined;
+            minItems?: undefined;
+            minFilms?: undefined;
+            maxVideoRunning?: undefined;
+            breaksEvery?: undefined;
+            start?: undefined;
+            off?: undefined;
             private?: undefined;
         };
         required: string[];
@@ -241,6 +276,13 @@ export declare const STATION_TOOLS: ({
             note: {
                 readonly type: "string";
             };
+            video?: undefined;
+            minItems?: undefined;
+            minFilms?: undefined;
+            maxVideoRunning?: undefined;
+            breaksEvery?: undefined;
+            start?: undefined;
+            off?: undefined;
             private?: undefined;
         };
         required: string[];
@@ -269,6 +311,63 @@ export declare const STATION_TOOLS: ({
                 type: "string";
                 description: string;
             };
+            video: {
+                type: string;
+            };
+            minItems: {
+                type: string;
+            };
+            minFilms: {
+                type: string;
+            };
+            maxVideoRunning: {
+                type: string;
+            };
+            breaksEvery: {
+                type: string;
+            };
+            start: {
+                type: string;
+            };
+            off: {
+                type: string;
+            };
+            id?: undefined;
+            private?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            playlist?: undefined;
+            idempotencyKey?: undefined;
+            name?: undefined;
+            description?: undefined;
+            folder?: undefined;
+            items?: undefined;
+            shuffle?: undefined;
+            repeat?: undefined;
+            bitrate?: undefined;
+            action?: undefined;
+            visibility?: undefined;
+            listed?: undefined;
+            basis?: undefined;
+            note?: undefined;
+            video?: undefined;
+            minItems?: undefined;
+            minFilms?: undefined;
+            maxVideoRunning?: undefined;
+            breaksEvery?: undefined;
+            start?: undefined;
+            off?: undefined;
+            server: {
+                type: "string";
+                description: string;
+            };
             id: {
                 type: "string";
                 description: string;

package/dist/station-mcp.js

@@ -78,6 +78,18 @@ export const STATION_TOOLS = [
             required: ["id", "visibility"],
         },
     },
+    {
+        name: "station_auto",
+        description: "A station for every genre in the library (radio from music tags, TV from film genres), kept up to date after every library scan, with a short break between songs and films. Unlisted; publishing stays a separate step. off: true stops the automation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                server: SERVER,
+                video: { type: "boolean" }, minItems: { type: "integer" }, minFilms: { type: "integer" },
+                maxVideoRunning: { type: "integer" }, breaksEvery: { type: "integer" }, start: { type: "boolean" }, off: { type: "boolean" },
+            },
+        },
+    },
     {
         name: "station_unpublish",
         description: "Take a station out of the directory, or make it private: its links stop working and listeners are disconnected.",
@@ -134,6 +146,10 @@ export async function callStationTool(name, args, options = {}) {
             const all = answer.body["stations"] ?? [];
             return say(all.length === 0 ? "No stations on this server yet." : all.map(line).join("\n"));
         }
+        if (name === "station_auto") {
+            const answer = await call("POST", "/api/v1/stations/auto", pick(["video", "minItems", "minFilms", "maxVideoRunning", "breaksEvery", "start", "off"]));
+            return answer.ok ? say(JSON.stringify(answer.body["report"], null, 2)) : refused(answer.body);
+        }
         if (!/^[a-z0-9]{10}$/.test(id) && name !== "station_create")
             return say("Which station? Pass its id from station_list.", true);
         if (name === "station_get") {

package/dist/station-metering.d.ts

@@ -0,0 +1,59 @@
+export interface Limits {
+    stationListeners: number;
+    totalListeners: number;
+    runningStations: number;
+    /** Bytes per station per month; 0 is no allowance. */
+    monthlyBytes: number;
+}
+export declare function limitsFromEnv(env?: Record<string, string | undefined>): Limits;
+/** Station control: start, stop, edit, publish. Thirty a minute is a person. */
+export declare const STATION_CONTROL_LIMIT: {
+    allowed: number;
+    windowMs: number;
+};
+export interface MonthUsage {
+    bytes: number;
+    listenerSeconds: number;
+    peakListeners: number;
+    restarts: number;
+    failures: number;
+}
+export declare function monthOf(at: number): string;
+export declare class StationUsage {
+    private readonly file;
+    private readonly now;
+    /** station -> month -> usage */
+    private usage;
+    private live;
+    private timer;
+    constructor(file: string, now?: () => number);
+    static fileFor(stateDir: string, port: number): string;
+    private month;
+    private touch;
+    flush(): void;
+    /** Somebody started listening; returns what to call when they stop. */
+    joined(station: string): () => void;
+    delivered(station: string, bytes: number): void;
+    restarted(station: string): void;
+    failed(station: string): void;
+    listeners(station: string): number;
+    totalListeners(): number;
+    thisMonth(station: string): MonthUsage;
+    history(station: string): Record<string, MonthUsage>;
+    forget(station: string): void;
+    /**
+     * Whether one more listener may join this station now: null to go
+     * ahead, or why not, with a code and how long to wait.
+     */
+    admit(station: string, limits: Limits): {
+        code: string;
+        error: string;
+        status: number;
+        retryAfter: number;
+    } | null;
+}
+/** Things an owner should know about a station, in words. */
+export declare function alertsFor(station: {
+    desired: string;
+    failures: Record<string, number>;
+}, state: string, offlineSince: number, usage: MonthUsage, limits: Limits, now?: number): string[];

package/dist/station-metering.js

@@ -0,0 +1,189 @@
+/**
+ * What stations cost to run, and the limits that keep one from costing
+ * everything.
+ *
+ * Counted where it is spent: every byte a station's link delivers and every
+ * second somebody is connected, per station, per calendar month, kept in
+ * `usage-<port>.json`. Restarts and files that would not play are counted
+ * too, because those are what an operator is asked about.
+ *
+ * Limits are the operator's (environment, below), and each is a refusal a
+ * person can act on, never a silent cut:
+ *
+ *   NIXAMP_STATION_MAX_LISTENERS   per station (default 200)
+ *   NIXAMP_MAX_LISTENERS           across every station (default 500)
+ *   NIXAMP_MAX_RUNNING_STATIONS    stations on the air at once (default 10)
+ *   NIXAMP_STATION_MONTHLY_GB      delivered per station per month (default 0: no allowance)
+ *
+ * When an allowance runs out the policy is "pause": nobody new is admitted
+ * until the month turns or the allowance is raised; nobody already
+ * listening is cut off mid-song. Control requests are limited separately
+ * (STATION_CONTROL_LIMIT) so that a flood of listeners never locks the owner
+ * out, and a flood of control requests never starves listeners.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function limitsFromEnv(env = process.env) {
+    const whole = (name, fallback) => {
+        const value = Number(env[name]);
+        return Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
+    };
+    return {
+        stationListeners: whole("NIXAMP_STATION_MAX_LISTENERS", 200),
+        totalListeners: whole("NIXAMP_MAX_LISTENERS", 500),
+        runningStations: whole("NIXAMP_MAX_RUNNING_STATIONS", 10),
+        monthlyBytes: Math.round(Number(env["NIXAMP_STATION_MONTHLY_GB"] ?? 0) * 1024 ** 3) || 0,
+    };
+}
+/** Station control: start, stop, edit, publish. Thirty a minute is a person. */
+export const STATION_CONTROL_LIMIT = { allowed: 30, windowMs: 60_000 };
+const BLANK = { bytes: 0, listenerSeconds: 0, peakListeners: 0, restarts: 0, failures: 0 };
+export function monthOf(at) {
+    return new Date(at).toISOString().slice(0, 7);
+}
+export class StationUsage {
+    file;
+    now;
+    /** station -> month -> usage */
+    usage = {};
+    live = new Map();
+    timer = null;
+    constructor(file, now = Date.now) {
+        this.file = file;
+        this.now = now;
+        try {
+            this.usage = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            this.usage = {};
+        }
+    }
+    static fileFor(stateDir, port) {
+        return join(stateDir, `usage-${port}.json`);
+    }
+    month(station, at = this.now()) {
+        const byMonth = (this.usage[station] ??= {});
+        return (byMonth[monthOf(at)] ??= { ...BLANK });
+    }
+    touch() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => this.flush(), 5_000);
+        this.timer.unref?.();
+    }
+    flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        // Listening still going on is counted up to now, then counted on from now.
+        const at = this.now();
+        for (const [station, listeners] of this.live) {
+            for (const [who, since] of listeners) {
+                this.month(station, at).listenerSeconds += Math.max(0, (at - since) / 1000);
+                listeners.set(who, at);
+            }
+        }
+        try {
+            mkdirSync(dirname(this.file), { recursive: true });
+            const temporary = `${this.file}.${process.pid}.tmp`;
+            writeFileSync(temporary, JSON.stringify(this.usage), { mode: 0o600 });
+            renameSync(temporary, this.file);
+        }
+        catch {
+            // Counting is not a reason to stop serving.
+        }
+    }
+    /** Somebody started listening; returns what to call when they stop. */
+    joined(station) {
+        const who = {};
+        let listeners = this.live.get(station);
+        if (!listeners) {
+            listeners = new Map();
+            this.live.set(station, listeners);
+        }
+        listeners.set(who, this.now());
+        const month = this.month(station);
+        month.peakListeners = Math.max(month.peakListeners, listeners.size);
+        this.touch();
+        return () => {
+            const since = listeners.get(who);
+            if (since === undefined)
+                return;
+            listeners.delete(who);
+            this.month(station).listenerSeconds += Math.max(0, (this.now() - since) / 1000);
+            this.touch();
+        };
+    }
+    delivered(station, bytes) {
+        this.month(station).bytes += bytes;
+        this.touch();
+    }
+    restarted(station) {
+        this.month(station).restarts += 1;
+        this.touch();
+    }
+    failed(station) {
+        this.month(station).failures += 1;
+        this.touch();
+    }
+    listeners(station) {
+        return this.live.get(station)?.size ?? 0;
+    }
+    totalListeners() {
+        let total = 0;
+        for (const listeners of this.live.values())
+            total += listeners.size;
+        return total;
+    }
+    thisMonth(station) {
+        return { ...this.month(station) };
+    }
+    history(station) {
+        return { ...(this.usage[station] ?? {}) };
+    }
+    forget(station) {
+        delete this.usage[station];
+        this.live.delete(station);
+        this.touch();
+    }
+    /**
+     * Whether one more listener may join this station now: null to go
+     * ahead, or why not, with a code and how long to wait.
+     */
+    admit(station, limits) {
+        if (limits.monthlyBytes > 0 && this.month(station).bytes >= limits.monthlyBytes) {
+            const now = new Date(this.now());
+            const next = Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1);
+            return { code: "allowance_exhausted", error: "this station has used its delivery allowance for the month", status: 429, retryAfter: Math.ceil((next - this.now()) / 1000) };
+        }
+        if (limits.stationListeners > 0 && this.listeners(station) >= limits.stationListeners) {
+            return { code: "station_full", error: "this station is full; try again in a little while", status: 503, retryAfter: 60 };
+        }
+        if (limits.totalListeners > 0 && this.totalListeners() >= limits.totalListeners) {
+            return { code: "server_full", error: "this server is carrying as many listeners as it can; try again in a little while", status: 503, retryAfter: 60 };
+        }
+        return null;
+    }
+}
+/** Things an owner should know about a station, in words. */
+export function alertsFor(station, state, offlineSince, usage, limits, now = Date.now()) {
+    const alerts = [];
+    if (station.desired === "running" && (state === "offline" || state === "recovering") && offlineSince > 0) {
+        const minutes = Math.floor((now - offlineSince) / 60_000);
+        if (minutes >= 2)
+            alerts.push(`Off the air for ${minutes} minutes while it should be running.`);
+    }
+    const left = Object.values(station.failures).filter((count) => count >= 3).length;
+    if (left > 0)
+        alerts.push(`${left} file${left === 1 ? " is" : "s are"} left out because ${left === 1 ? "it" : "they"} would not play.`);
+    if (usage.restarts >= 5)
+        alerts.push(`Restarted ${usage.restarts} times this month: something keeps stopping it.`);
+    if (limits.monthlyBytes > 0) {
+        const share = usage.bytes / limits.monthlyBytes;
+        if (share >= 1)
+            alerts.push("The delivery allowance for this month is used up: nobody new can join until it resets.");
+        else if (share >= 0.9)
+            alerts.push(`${Math.round(share * 100)}% of this month's delivery allowance is used.`);
+    }
+    return alerts;
+}

package/dist/station-page.d.ts

@@ -1,5 +1,5 @@
 /** A station page's path: /station/<id>. */
 export declare const STATION_PAGE: RegExp;
-export declare const STATION_PAGE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<meta name=\"robots\" content=\"noindex\">\n<link rel=\"icon\" href=\"data:,\">\n<title>Station \u00B7 nixamp</title>\n<style>\n:root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b;--warn:#9a6700;--off:#8c2f39}\n@media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f;--warn:#e3b341;--off:#f0838f}}\n*{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}\nmain{max-width:560px;margin:0 auto;padding:48px 16px}\n.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}\nh1{font-size:1.6rem;line-height:1.2;margin:0 0 4px}\n.about{color:var(--muted);margin:0 0 20px}\n.chip{display:inline-flex;align-items:center;gap:8px;font-size:.85rem;font-weight:600;padding:4px 10px;border-radius:999px;border:1px solid var(--line)}\n.chip::before{content:\"\";width:8px;height:8px;border-radius:50%;background:currentColor}\n.live{color:var(--live)}.reconnecting{color:var(--warn)}.unavailable,.stopped{color:var(--off)}\n.now{margin:20px 0;min-height:3em}.now .title{font-weight:600}.now .by{color:var(--muted)}\n.controls{display:flex;align-items:center;gap:16px;flex-wrap:wrap}\nbutton{font:inherit;font-weight:600;border:0;border-radius:999px;padding:12px 28px;background:var(--accent);color:#fff;cursor:pointer;min-width:120px}\nbutton:disabled{opacity:.5;cursor:not-allowed}\nbutton:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid var(--accent);outline-offset:3px}\nlabel{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.9rem}\ninput[type=range]{width:120px;accent-color:var(--accent)}\n.small{margin-top:20px;font-size:.85rem;color:var(--muted)}.small a{color:inherit}\n.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}\n@media (prefers-reduced-motion:no-preference){.live::before{animation:pulse 2s ease-in-out infinite}}\n@keyframes pulse{50%{opacity:.35}}\n</style>\n</head>\n<body>\n<main>\n  <div class=\"card\">\n    <span id=\"state\" class=\"chip unavailable\" role=\"status\">Loading</span>\n    <h1 id=\"name\">&nbsp;</h1>\n    <p id=\"about\" class=\"about\" hidden></p>\n    <div class=\"now\" aria-live=\"polite\"><div id=\"title\" class=\"title\"></div><div id=\"by\" class=\"by\"></div></div>\n    <div class=\"controls\">\n      <button id=\"play\" type=\"button\" aria-pressed=\"false\" disabled>Play</button>\n      <label>Volume <input id=\"volume\" type=\"range\" min=\"0\" max=\"1\" step=\"0.05\" value=\"1\"></label>\n    </div>\n    <p class=\"small\"><a id=\"m3u\" href=\"#\">Open in another player (.m3u)</a> \u00B7 Pausing here does not pause the station.</p>\n  </div>\n  <p class=\"small\">Played by <a href=\"https://nixamp.com\">nixamp</a>.</p>\n  <div id=\"announce\" class=\"sr\" aria-live=\"assertive\"></div>\n</main>\n<script>\n(() => {\n  const id = location.pathname.split(\"/\").filter(Boolean)[1] || \"\";\n  const token = new URLSearchParams(location.search).get(\"t\") || \"\";\n  const q = \"?t=\" + encodeURIComponent(token);\n  const api = \"/api/v1/stations/\" + encodeURIComponent(id);\n  const $ = (s) => document.querySelector(s);\n  const audio = new Audio();\n  audio.preload = \"none\";\n  let wanted = false, retry = 0, timer = 0, last = null, live = false;\n  const chip = (state, text) => { const c = $(\"#state\"); c.className = \"chip \" + state; c.textContent = text; };\n  const say = (text) => { $(\"#announce\").textContent = text; };\n  const draw = (s) => {\n    last = s;\n    document.title = s.name + \" \u00B7 nixamp\";\n    $(\"#name\").textContent = s.name;\n    $(\"#about\").textContent = s.description || \"\";\n    $(\"#about\").hidden = !s.description;\n    if (!live) title(s);\n    if (wanted && retry > 0) chip(\"reconnecting\", \"Reconnecting\");\n    else if (s.state === \"live\") chip(\"live\", \"Live\");\n    else if (s.state === \"starting\" || s.state === \"recovering\") chip(\"reconnecting\", \"Coming back\");\n    else if (s.state === \"stopped\") chip(\"stopped\", \"Off the air\");\n    else chip(\"unavailable\", \"Unavailable\");\n    $(\"#play\").disabled = !(s.state === \"live\" || s.state === \"recovering\" || s.state === \"starting\");\n    $(\"#m3u\").href = api + \"/listen.m3u\" + q;\n  };\n  const title = (s) => {\n    const playing = s.nowPlaying;\n    $(\"#title\").textContent = playing ? (playing.title || \"Untitled\") : (s.state === \"live\" ? \"On the air\" : \"\");\n    $(\"#by\").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(\" \u00B7 \") : \"\";\n  };\n  // What is ahead of the speaker: the sound the player holds and has not\n  // played yet. A new title waits that long, so it changes with the song.\n  const ahead = () => {\n    if (!wanted || audio.paused || audio.buffered.length === 0) return 0;\n    return Math.max(0, Math.min(30, audio.buffered.end(audio.buffered.length - 1) - audio.currentTime));\n  };\n  const listen = () => {\n    if (!window.EventSource) return;\n    const events = new EventSource(api + \"/events\" + q);\n    events.addEventListener(\"hello\", (e) => { live = true; title(JSON.parse(e.data)); });\n    events.addEventListener(\"now\", (e) => {\n      const s = JSON.parse(e.data);\n      setTimeout(() => { title(s); say(s.nowPlaying ? \"Now playing \" + (s.nowPlaying.title || \"\") : \"\"); }, ahead() * 1000);\n    });\n    events.addEventListener(\"state\", () => poll());\n    events.onerror = () => { live = false; };\n  };\n  const poll = async () => {\n    try {\n      const r = await fetch(api + \"/state\" + q, { cache: \"no-store\" });\n      if (r.status === 404) { $(\"#name\").textContent = \"This station is not available\"; chip(\"unavailable\", \"Unavailable\"); $(\"#play\").disabled = true; stop(); return; }\n      if (r.ok) draw(await r.json());\n    } catch {}\n  };\n  // Always the live edge: a fresh request, never a cached or paused one.\n  const join = () => { audio.src = api + \"/stream\" + q + \"&n=\" + Date.now(); audio.play().catch(() => { wanted = false; button(); }); };\n  const stop = () => { wanted = false; clearTimeout(timer); audio.pause(); audio.removeAttribute(\"src\"); audio.load(); button(); };\n  const button = () => { const b = $(\"#play\"); b.textContent = wanted ? \"Stop\" : \"Play\"; b.setAttribute(\"aria-pressed\", String(wanted)); };\n  const again = () => {\n    if (!wanted) return;\n    retry += 1;\n    if (last) draw(last);\n    clearTimeout(timer);\n    timer = setTimeout(join, Math.min(15000, 1000 * 2 ** Math.min(retry, 4)));\n  };\n  audio.addEventListener(\"playing\", () => { if (retry) say(\"Back on\"); retry = 0; if (last) draw(last); });\n  audio.addEventListener(\"error\", again);\n  audio.addEventListener(\"ended\", again);\n  audio.addEventListener(\"stalled\", () => { if (wanted && audio.readyState < 3) again(); });\n  $(\"#play\").addEventListener(\"click\", () => { if (wanted) { stop(); say(\"Stopped\"); } else { wanted = true; retry = 0; button(); join(); say(\"Playing\"); } });\n  $(\"#volume\").addEventListener(\"input\", (e) => { audio.volume = Number(e.target.value); });\n  poll();\n  listen();\n  setInterval(poll, 5000);\n})();\n</script>\n</body>\n</html>\n";
+export declare const STATION_PAGE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<meta name=\"robots\" content=\"noindex\">\n<link rel=\"icon\" href=\"data:,\">\n<title>Station \u00B7 nixamp</title>\n<style>\n:root{--bg:#f6f5f2;--fg:#17171a;--muted:#5d5d66;--card:#fff;--line:#dedcd6;--accent:#1f6feb;--live:#0b7a3b;--warn:#9a6700;--off:#8c2f39}\n@media (prefers-color-scheme:dark){:root{--bg:#121214;--fg:#ececf1;--muted:#a4a4b0;--card:#1c1c20;--line:#2c2c33;--accent:#6aa7ff;--live:#3fbf7f;--warn:#e3b341;--off:#f0838f}}\n*{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}\nmain{max-width:560px;margin:0 auto;padding:48px 16px}\n.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:24px}\nh1{font-size:1.6rem;line-height:1.2;margin:0 0 4px}\n.about{color:var(--muted);margin:0 0 20px}\n.chip{display:inline-flex;align-items:center;gap:8px;font-size:.85rem;font-weight:600;padding:4px 10px;border-radius:999px;border:1px solid var(--line)}\n.chip::before{content:\"\";width:8px;height:8px;border-radius:50%;background:currentColor}\n.live{color:var(--live)}.reconnecting{color:var(--warn)}.unavailable,.stopped{color:var(--off)}\n.now{margin:20px 0;min-height:3em}.now .title{font-weight:600}.now .by{color:var(--muted)}\n.controls{display:flex;align-items:center;gap:16px;flex-wrap:wrap}\nbutton{font:inherit;font-weight:600;border:0;border-radius:999px;padding:12px 28px;background:var(--accent);color:#fff;cursor:pointer;min-width:120px}\nbutton:disabled{opacity:.5;cursor:not-allowed}\nbutton:focus-visible,input:focus-visible,a:focus-visible{outline:3px solid var(--accent);outline-offset:3px}\nlabel{display:flex;align-items:center;gap:8px;color:var(--muted);font-size:.9rem}\ninput[type=range]{width:120px;accent-color:var(--accent)}\n.small{margin-top:20px;font-size:.85rem;color:var(--muted)}.small a{color:inherit}\n.screen{display:block;width:100%;aspect-ratio:16/9;background:#000;border-radius:10px;margin:12px 0}\n.sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}\n@media (prefers-reduced-motion:no-preference){.live::before{animation:pulse 2s ease-in-out infinite}}\n@keyframes pulse{50%{opacity:.35}}\n</style>\n</head>\n<body>\n<main>\n  <div class=\"card\">\n    <span id=\"state\" class=\"chip unavailable\" role=\"status\">Loading</span>\n    <video id=\"screen\" class=\"screen\" playsinline preload=\"none\" hidden></video>\n    <h1 id=\"name\">&nbsp;</h1>\n    <p id=\"about\" class=\"about\" hidden></p>\n    <div class=\"now\" aria-live=\"polite\"><div id=\"title\" class=\"title\"></div><div id=\"by\" class=\"by\"></div></div>\n    <div class=\"controls\">\n      <button id=\"play\" type=\"button\" aria-pressed=\"false\" disabled>Play</button>\n      <label>Volume <input id=\"volume\" type=\"range\" min=\"0\" max=\"1\" step=\"0.05\" value=\"1\"></label>\n    </div>\n    <p class=\"small\"><a id=\"m3u\" href=\"#\">Open in another player (.m3u)</a> \u00B7 Pausing here does not pause the station.</p>\n  </div>\n  <p class=\"small\">Played by <a href=\"https://nixamp.com\">nixamp</a>.</p>\n  <div id=\"announce\" class=\"sr\" aria-live=\"assertive\"></div>\n</main>\n<script>\n(() => {\n  const id = location.pathname.split(\"/\").filter(Boolean)[1] || \"\";\n  const token = new URLSearchParams(location.search).get(\"t\") || \"\";\n  const q = \"?t=\" + encodeURIComponent(token);\n  const api = \"/api/v1/stations/\" + encodeURIComponent(id);\n  const $ = (s) => document.querySelector(s);\n  // Sound, or a TV station's picture: the element is chosen by the first state.\n  let audio = new Audio();\n  audio.preload = \"none\";\n  let wired = false;\n  const wire = () => {\n    if (wired) return;\n    wired = true;\n    audio.addEventListener(\"playing\", () => { if (retry) say(\"Back on\"); retry = 0; if (last) draw(last); });\n    audio.addEventListener(\"error\", again);\n    audio.addEventListener(\"ended\", again);\n    audio.addEventListener(\"stalled\", () => { if (wanted && audio.readyState < 3) again(); });\n  };\n  let wanted = false, retry = 0, timer = 0, last = null, live = false;\n  const chip = (state, text) => { const c = $(\"#state\"); c.className = \"chip \" + state; c.textContent = text; };\n  const say = (text) => { $(\"#announce\").textContent = text; };\n  const draw = (s) => {\n    last = s;\n    if (s.kind === \"video\" && audio.tagName !== \"VIDEO\") {\n      audio = $(\"#screen\");\n      audio.hidden = false;\n      wired = false;\n      wire();\n    }\n    document.title = s.name + \" \u00B7 nixamp\";\n    $(\"#name\").textContent = s.name;\n    $(\"#about\").textContent = s.description || \"\";\n    $(\"#about\").hidden = !s.description;\n    if (!live) title(s);\n    if (wanted && retry > 0) chip(\"reconnecting\", \"Reconnecting\");\n    else if (s.state === \"live\") chip(\"live\", \"Live\");\n    else if (s.state === \"starting\" || s.state === \"recovering\") chip(\"reconnecting\", \"Coming back\");\n    else if (s.state === \"stopped\") chip(\"stopped\", \"Off the air\");\n    else chip(\"unavailable\", \"Unavailable\");\n    $(\"#play\").disabled = !(s.state === \"live\" || s.state === \"recovering\" || s.state === \"starting\");\n    $(\"#m3u\").href = api + \"/listen.m3u\" + q;\n  };\n  const title = (s) => {\n    const playing = s.nowPlaying;\n    $(\"#title\").textContent = playing ? (playing.title || \"Untitled\") : (s.state === \"live\" ? \"On the air\" : \"\");\n    $(\"#by\").textContent = playing ? [playing.artist, playing.album].filter(Boolean).join(\" \u00B7 \") : \"\";\n  };\n  // What is ahead of the speaker: the sound the player holds and has not\n  // played yet. A new title waits that long, so it changes with the song.\n  const ahead = () => {\n    if (!wanted || audio.paused || audio.buffered.length === 0) return 0;\n    return Math.max(0, Math.min(30, audio.buffered.end(audio.buffered.length - 1) - audio.currentTime));\n  };\n  const listen = () => {\n    if (!window.EventSource) return;\n    const events = new EventSource(api + \"/events\" + q);\n    events.addEventListener(\"hello\", (e) => { live = true; title(JSON.parse(e.data)); });\n    events.addEventListener(\"now\", (e) => {\n      const s = JSON.parse(e.data);\n      setTimeout(() => { title(s); say(s.nowPlaying ? \"Now playing \" + (s.nowPlaying.title || \"\") : \"\"); }, ahead() * 1000);\n    });\n    events.addEventListener(\"state\", () => poll());\n    events.onerror = () => { live = false; };\n  };\n  const poll = async () => {\n    try {\n      const r = await fetch(api + \"/state\" + q, { cache: \"no-store\" });\n      if (r.status === 404) { $(\"#name\").textContent = \"This station is not available\"; chip(\"unavailable\", \"Unavailable\"); $(\"#play\").disabled = true; stop(); return; }\n      if (r.ok) draw(await r.json());\n    } catch {}\n  };\n  // Always the live edge: a fresh request, never a cached or paused one.\n  const join = () => { audio.src = api + \"/stream\" + q + \"&n=\" + Date.now(); audio.play().catch(() => { wanted = false; button(); }); };\n  const stop = () => { wanted = false; clearTimeout(timer); audio.pause(); audio.removeAttribute(\"src\"); audio.load(); button(); };\n  const button = () => { const b = $(\"#play\"); b.textContent = wanted ? \"Stop\" : \"Play\"; b.setAttribute(\"aria-pressed\", String(wanted)); };\n  const again = () => {\n    if (!wanted) return;\n    retry += 1;\n    if (last) draw(last);\n    clearTimeout(timer);\n    timer = setTimeout(join, Math.min(15000, 1000 * 2 ** Math.min(retry, 4)));\n  };\n  wire();\n  $(\"#play\").addEventListener(\"click\", () => { if (wanted) { stop(); say(\"Stopped\"); } else { wanted = true; retry = 0; button(); join(); say(\"Playing\"); } });\n  $(\"#volume\").addEventListener(\"input\", (e) => { audio.volume = Number(e.target.value); });\n  poll();\n  listen();\n  setInterval(poll, 5000);\n})();\n</script>\n</body>\n</html>\n";
 /** Only its own script and style, only its own server, never framed. */
 export declare const STATION_PAGE_CSP: string;

package/dist/station-page.js

@@ -29,6 +29,7 @@ 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}
+.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}}
 @keyframes pulse{50%{opacity:.35}}
@@ -40,13 +41,29 @@ const SCRIPT = `
   const q = "?t=" + encodeURIComponent(token);
   const api = "/api/v1/stations/" + encodeURIComponent(id);
   const $ = (s) => document.querySelector(s);
-  const audio = new Audio();
+  // Sound, or a TV station's picture: the element is chosen by the first state.
+  let audio = new Audio();
   audio.preload = "none";
+  let wired = false;
+  const wire = () => {
+    if (wired) return;
+    wired = true;
+    audio.addEventListener("playing", () => { if (retry) say("Back on"); retry = 0; if (last) draw(last); });
+    audio.addEventListener("error", again);
+    audio.addEventListener("ended", again);
+    audio.addEventListener("stalled", () => { if (wanted && audio.readyState < 3) again(); });
+  };
   let wanted = false, retry = 0, timer = 0, last = null, live = false;
   const chip = (state, text) => { const c = $("#state"); c.className = "chip " + state; c.textContent = text; };
   const say = (text) => { $("#announce").textContent = text; };
   const draw = (s) => {
     last = s;
+    if (s.kind === "video" && audio.tagName !== "VIDEO") {
+      audio = $("#screen");
+      audio.hidden = false;
+      wired = false;
+      wire();
+    }
     document.title = s.name + " · nixamp";
     $("#name").textContent = s.name;
     $("#about").textContent = s.description || "";
@@ -100,10 +117,7 @@ const SCRIPT = `
     clearTimeout(timer);
     timer = setTimeout(join, Math.min(15000, 1000 * 2 ** Math.min(retry, 4)));
   };
-  audio.addEventListener("playing", () => { if (retry) say("Back on"); retry = 0; if (last) draw(last); });
-  audio.addEventListener("error", again);
-  audio.addEventListener("ended", again);
-  audio.addEventListener("stalled", () => { if (wanted && audio.readyState < 3) again(); });
+  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); });
   poll();
@@ -126,6 +140,7 @@ const PAGE = `<!doctype html>
 <main>
   <div class="card">
     <span id="state" class="chip unavailable" role="status">Loading</span>
+    <video id="screen" class="screen" playsinline preload="none" hidden></video>
     <h1 id="name">&nbsp;</h1>
     <p id="about" class="about" hidden></p>
     <div class="now" aria-live="polite"><div id="title" class="title"></div><div id="by" class="by"></div></div>

package/dist/station-routes.d.ts

@@ -15,6 +15,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 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;
@@ -43,6 +44,18 @@ export interface StationContext {
     readBody: (request: IncomingMessage) => Promise<string>;
     /** Headers every answer carries (CORS). */
     headers: Record<string, string>;
+    /** Metering and limits; absent in tests that do not care. */
+    usage?: StationUsage;
+    limits?: Limits;
+    /** Null to go ahead with a change, or how long to wait (control rate limit). */
+    throttle?: () => {
+        retryAfter: number;
+    } | null;
+    /** Auto stations: run a sync with these settings (and keep them), or read them. */
+    auto?: {
+        sync: (input: Record<string, unknown>) => Promise<unknown>;
+        setting: () => unknown;
+    };
 }
 declare function links(ctx: StationContext, station: Station): {
     page: string;