nixamp 0.47.0 → 0.48.0

package/dist/server.js

@@ -70,6 +70,7 @@ import { LyricsPublisher } from "./lyrics-publish.js";
 import { aiKey } from "./ai-keys.js";
 import { STATION_APP_CSP, STATION_PAGE, STATION_PAGE_CSP, STATION_PAGE_HTML, WATCH_APP_CSP } from "./station-page.js";
 import { handleRooms, RoomProbe, roomEntries, RoomStore, watchBase } from "./guide-rooms.js";
+import { handleVods, VodProbe, vodEntries, VodStore, vodView } from "./guide-vods.js";
 import { withPitFooter } from "./pit-footer.js";
 import { guideAds, guideCsp, guideHosts, guidePeers, peerBase, PeerGuides, renderGuide } from "./station-guide.js";
 import { StationRunner } from "./station-runner.js";
@@ -2186,6 +2187,8 @@ export function createHandler(engine, options) {
             !(path === "/watch" && Boolean(options.stations?.rooms)) &&
             // Live rooms on the guide: listed for anybody, published by a member (guide-rooms.ts).
             !((path === "/api/v1/guide/rooms" || path.startsWith("/api/v1/guide/rooms/")) && Boolean(options.stations?.rooms)) &&
+            // On demand: a file's page and the guide's list of them (guide-vods.ts); the file's own key travels in its play address.
+            !((path === "/vod" || /^\/vod\/[A-Za-z0-9_-]{1,32}$/.test(path) || path === "/api/v1/guide/vods" || path.startsWith("/api/v1/guide/vods/")) && Boolean(options.stations?.vods)) &&
             !STATION_PAGE.test(path) &&
             !isPublicAsset &&
             !isGuidePage &&
@@ -2397,6 +2400,61 @@ export function createHandler(engine, options) {
             response.end(request.method === "HEAD" ? undefined : built);
             return;
         }
+        // A file on demand: /vod (all of them) and /vod/<id> (one), the page a VOD link opens.
+        const vodPath = /^\/vod(?:\/([A-Za-z0-9_-]{1,32}))?$/.exec(path);
+        if (options.stations?.vods && vodPath && (request.method === "GET" || request.method === "HEAD")) {
+            const built = web !== null && isFile(join(web, "vod.html")) ? readFileSync(join(web, "vod.html"), "utf8") : null;
+            if (!built) {
+                json(response, 404, { error: "this server was started without its web pages" });
+                return;
+            }
+            const vods = options.stations.vods;
+            const one = vodPath[1] ? vods.store.get(vodPath[1]) : undefined;
+            const base = watchBase(options.stations.publicBase?.() || `https://${request.headers.host ?? "localhost"}`);
+            const view = one ? vodView(one, base, null) : null;
+            // A link preview reads the page, not its script: the file's name goes in the head.
+            const escape = (text) => text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+            const head = view
+                ? `<title>${escape(String(view.name))} · on demand</title>\n    <meta property="og:title" content="${escape(String(view.name))}" />\n    <meta property="og:type" content="${view.kind === "video" ? "video.other" : "music.song"}" />\n    <meta property="og:url" content="${escape(String(view.page))}" />\n    <meta property="og:description" content="On demand: play it from the start, seek anywhere." />`
+                : "<title>On demand · nixamp</title>";
+            response.writeHead(vodPath[1] && !one ? 404 : 200, {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-cache",
+                "content-security-policy": WATCH_APP_CSP,
+                "referrer-policy": "no-referrer",
+                "x-content-type-options": "nosniff",
+            });
+            response.end(request.method === "HEAD" ? undefined : built.replace(/<title>[^<]*<\/title>/, head));
+            return;
+        }
+        if (options.stations?.vods && (path === "/api/v1/guide/vods" || path.startsWith("/api/v1/guide/vods/"))) {
+            const control = await controlOf();
+            const session = tokenFrom(request.headers) || url.searchParams.get("session") || "";
+            const vods = options.stations.vods;
+            const publicBase = (options.stations.publicBase?.() ?? "").replace(/\/+$/, "");
+            await handleVods(request, response, path, {
+                store: vods.store,
+                probe: vods.probe,
+                base: watchBase(publicBase || `https://${request.headers.host ?? "localhost"}`),
+                canControl: control.allowed,
+                member: async () => (session && options.owner ? (await options.owner.accountFor(session)) || "" : ""),
+                ownPlay: (item) => (publicBase && listenKey && options.library?.index.item(item) ? `${publicBase}/api/v1/library/items/${item}/play?k=${listenKey}` : ""),
+                ownState: (id) => {
+                    const item = options.library?.index.item(id);
+                    if (!item || item.state !== "ready")
+                        return null;
+                    const title = item.override.title || item.title || item.rel.split("/").pop()?.replace(/\.[^.]+$/, "") || id;
+                    return { name: title.slice(0, 160), kind: item.video ? "video" : "audio", duration: item.duration, artist: (item.override.artist || item.artist).slice(0, 160) };
+                },
+                json,
+                readBody,
+                throttle: () => {
+                    const verdict = guard.check(`vods:${callerOf(request.headers, request.socket.remoteAddress, behindProxy)}`, STATION_CONTROL_LIMIT);
+                    return verdict.ok ? null : { retryAfter: verdict.retryAfter };
+                },
+            });
+            return;
+        }
         if (options.stations?.rooms && (path === "/api/v1/guide/rooms" || path.startsWith("/api/v1/guide/rooms/"))) {
             const control = await controlOf();
             const session = tokenFrom(request.headers) || url.searchParams.get("session") || "";
@@ -2448,6 +2506,7 @@ export function createHandler(engine, options) {
                 probe: options.library.probe,
                 retag: options.library.retag,
                 sendFile,
+                play: (req, res, file) => playFile(req, res, file, url, options),
                 json,
                 readBody,
             });
@@ -2533,8 +2592,16 @@ export function createHandler(engine, options) {
                 ...(options.stations.lyricsPublisher ? { lyricsPublisher: options.stations.lyricsPublisher } : {}),
                 passes: listenPasses,
                 ...(options.stations.peers ? { peers: () => options.stations.peers.entries() } : {}),
-                ...(options.stations.rooms ? {
-                    rooms: () => roomEntries(options.stations.rooms.store, options.stations.rooms.probe, watchBase(options.stations.publicBase?.() || `${scheme}://${request.headers.host ?? "localhost"}`)),
+                ...(options.stations.rooms || options.stations.vods ? {
+                    rooms: async () => {
+                        const base = watchBase(options.stations.publicBase?.() || `${scheme}://${request.headers.host ?? "localhost"}`);
+                        const { rooms, vods } = options.stations;
+                        const [live, onDemand] = await Promise.all([
+                            rooms ? roomEntries(rooms.store, rooms.probe, base) : [],
+                            vods ? vodEntries(vods.store, vods.probe, base) : [],
+                        ]);
+                        return [...live, ...onDemand];
+                    },
                 } : {}),
                 throttle: () => {
                     const verdict = guard.check(`stations:${control.account || callerOf(request.headers, request.socket.remoteAddress, behindProxy)}`, STATION_CONTROL_LIMIT);
@@ -5898,6 +5965,18 @@ export function createHandler(engine, options) {
             handleStaticRelay(request, response, compression, file, engine.snapshot().tracks?.[index]?.title ?? file);
             return;
         }
+        // Which library item a playlist track is, for publishing it on demand (guide-vods.ts).
+        const mediaItem = /^\/api\/media\/(\d+)\/item$/.exec(path);
+        if (mediaItem) {
+            const file = engine.trackPath(Number(mediaItem[1]));
+            const item = file === undefined ? undefined : options.library?.index.itemAt(file);
+            if (!item) {
+                json(response, 404, { error: "that track is not in this server's library", code: "not_in_library" });
+                return;
+            }
+            json(response, 200, { id: item.id, video: item.video, title: item.override.title || item.title, duration: item.duration });
+            return;
+        }
         if (path.startsWith("/api/media/")) {
             if (!options.media) {
                 json(response, 403, { error: "media streaming is off" });
@@ -5910,42 +5989,7 @@ export function createHandler(engine, options) {
                 return;
             }
             watch(request, response, "media", engine.snapshot().tracks?.[index]?.title ?? file);
-            // A browser asks for every track here, and a matroska or an avi handed
-            // to it raw is bytes it cannot play. Seeking is what this route is for
-            // and transcoding gives it up, but an unseekable film beats a silent
-            // one -- and the seekable formats are untouched.
-            // A ceiling the caller asked for, because only the caller knows what its
-            // link can carry. Capped at both ends: nothing below 200k is watchable,
-            // and above 20 megabits the original was always the better answer.
-            const asked = Number(url.searchParams.get("kbps") ?? "");
-            const capKbps = Number.isFinite(asked) && asked > 0 ? Math.min(20_000, Math.max(200, asked)) : 0;
-            // Whether this browser decodes H.265, which only it can know: Safari and
-            // televisions do, Chrome on a desktop does not and says nothing when
-            // handed it. Copying a 4K HEVC film is free; re-encoding one does not
-            // keep up with playing it, so the answer is worth carrying in the URL.
-            const allowHevc = url.searchParams.get("hevc") === "1";
-            if (playsInBrowser(file) && capKbps === 0) {
-                sendFile(request, response, file);
-                return;
-            }
-            // A film, or something whose name refuses to say. A live channel at
-            // .../301 used to fall through to the audio branch and arrive as MP3
-            // with `-vn` -- a match you could only listen to.
-            if (hasPicture(file) || nameSaysNothing(file)) {
-                // What ffprobe finds inside decides how little work it takes to keep
-                // the picture, and whether there is a picture to keep at all.
-                const codecs = await codecsOf({ ffmpeg: [], ffprobe: options.ffprobe ?? ["ffprobe"], play: null }, file);
-                if (codecs.video !== "") {
-                    // Told back to the playlist, so an entry that was added before this
-                    // could be asked stops claiming to be a song. Without it a track
-                    // added by an older nixamp goes to an audio element for ever, and
-                    // the only cure is noticing and adding it again.
-                    engine.sawPicture(index);
-                    pipeFfmpeg(request, response, file, options.ffmpeg ?? ["ffmpeg"], videoArgs(codecs, capKbps, { allowHevc }), "video/mp4", transportInputArgs(file, codecs.container));
-                    return;
-                }
-            }
-            transcode(request, response, file, options.ffmpeg ?? ["ffmpeg"]);
+            await playFile(request, response, file, url, options, () => engine.sawPicture(index));
             return;
         }
         // Whatever the source is, this comes back as MP3 a browser will play:
@@ -6273,6 +6317,49 @@ async function liveAudio(request, response, engine, ffmpeg, ffprobe) {
  * for everything else.
  */
 /** Audio, from whatever this is: the shape every non-browser source took. */
+/**
+ * A file as a browser plays it: the bytes themselves, seekable, when the
+ * browser can; otherwise an MP4 or MP3 made on the way. `onPicture` hears
+ * that ffprobe found a picture in it.
+ */
+async function playFile(request, response, file, url, options, onPicture = () => undefined) {
+    // A browser asks for every track here, and a matroska or an avi handed
+    // to it raw is bytes it cannot play. Seeking is what this route is for
+    // and transcoding gives it up, but an unseekable film beats a silent
+    // one -- and the seekable formats are untouched.
+    // A ceiling the caller asked for, because only the caller knows what its
+    // link can carry. Capped at both ends: nothing below 200k is watchable,
+    // and above 20 megabits the original was always the better answer.
+    const asked = Number(url.searchParams.get("kbps") ?? "");
+    const capKbps = Number.isFinite(asked) && asked > 0 ? Math.min(20_000, Math.max(200, asked)) : 0;
+    // Whether this browser decodes H.265, which only it can know: Safari and
+    // televisions do, Chrome on a desktop does not and says nothing when
+    // handed it. Copying a 4K HEVC film is free; re-encoding one does not
+    // keep up with playing it, so the answer is worth carrying in the URL.
+    const allowHevc = url.searchParams.get("hevc") === "1";
+    if (playsInBrowser(file) && capKbps === 0) {
+        sendFile(request, response, file);
+        return;
+    }
+    // A film, or something whose name refuses to say. A live channel at
+    // .../301 used to fall through to the audio branch and arrive as MP3
+    // with `-vn` -- a match you could only listen to.
+    if (hasPicture(file) || nameSaysNothing(file)) {
+        // What ffprobe finds inside decides how little work it takes to keep
+        // the picture, and whether there is a picture to keep at all.
+        const codecs = await codecsOf({ ffmpeg: [], ffprobe: options.ffprobe ?? ["ffprobe"], play: null }, file);
+        if (codecs.video !== "") {
+            // Told back to the playlist, so an entry that was added before this
+            // could be asked stops claiming to be a song. Without it a track
+            // added by an older nixamp goes to an audio element for ever, and
+            // the only cure is noticing and adding it again.
+            onPicture();
+            pipeFfmpeg(request, response, file, options.ffmpeg ?? ["ffmpeg"], videoArgs(codecs, capKbps, { allowHevc }), "video/mp4", transportInputArgs(file, codecs.container));
+            return;
+        }
+    }
+    transcode(request, response, file, options.ffmpeg ?? ["ffmpeg"]);
+}
 function transcode(request, response, source, ffmpeg) {
     pipeFfmpeg(request, response, source, ffmpeg, ["-vn", "-f", "mp3", "-b:a", "192k"], "audio/mpeg");
 }
@@ -6661,6 +6748,8 @@ export async function serve(argv, version = "0.1.0") {
         }),
         // Live rooms published to this guide; the probe never reaches this machine's own network.
         rooms: { store: new RoomStore(RoomStore.fileFor(stateDir(), options.port)), probe: new RoomProbe(fetch, (link) => refusedDestination(link)) },
+        // Files published to play on demand; the same guard on whose network the probe reaches.
+        vods: { store: new VodStore(VodStore.fileFor(stateDir(), options.port)), probe: new VodProbe(fetch, (link) => refusedDestination(link)) },
     };
     // Music handed over from BitTorrented, copied into a folder of our own.
     const importer = new Importer(join(stateDir(), `handoffs-${options.port}.json`), {

package/dist/station-guide.d.ts

@@ -11,8 +11,8 @@ export interface GuideEntry {
     id?: string;
     name: string;
     kind: "audio" | "video";
-    /** rooms (live rooms, src/guide-rooms.ts), ai, shared, radio or tv; from kind when absent. */
-    group?: "rooms" | "ai" | "shared" | "radio" | "tv";
+    /** rooms (live rooms, src/guide-rooms.ts), vod (on demand, src/guide-vods.ts), ai, shared, radio or tv; from kind when absent. */
+    group?: "rooms" | "vod" | "ai" | "shared" | "radio" | "tv";
     state: string;
     page: string;
     nowPlaying: {

package/dist/station-guide.js

@@ -65,7 +65,7 @@ const SCRIPT = `
     } catch { button.textContent = "Could not report; try again"; button.disabled = false; }
   };
   const draw = (stations) => {
-    for (const group of ["rooms", "ai", "shared", "radio", "tv"]) {
+    for (const group of ["rooms", "vod", "ai", "shared", "radio", "tv"]) {
       const grid = document.querySelector("#" + group);
       grid.replaceChildren();
       const list = stations.filter((s) => (s.group || (s.kind === "video" ? "tv" : "radio")) === group);
@@ -74,7 +74,7 @@ const SCRIPT = `
         const card = el("div", "card");
         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),
+        a.append(el("div", "live", s.state === "live" ? "● LIVE" : s.state === "vod" ? "▶ ON DEMAND" : "off the air"), el("div", "name", s.name),
           el("div", "now", nowLine(s.nowPlaying)));
         card.append(a);
         if (group === "shared") {
@@ -144,7 +144,7 @@ const hash = (text) => `'sha256-${createHash("sha256").update(text).digest("base
 function escape(text) {
     return text.replace(/[&<>"']/g, (one) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[one]);
 }
-const GROUPS = ["rooms", "ai", "shared", "radio", "tv"];
+const GROUPS = ["rooms", "vod", "ai", "shared", "radio", "tv"];
 /**
  * The guide with its stations already in it, so it reads the same through a
  * gateway that cannot run its script against this server (the Moshpit's
@@ -154,7 +154,7 @@ export function renderGuide(entries, apiBase = "", ads = {}) {
     const groupOf = (one) => one.group ?? (one.kind === "video" ? "tv" : "radio");
     const cards = (group) => entries
         .filter((one) => groupOf(one) === group && /^https?:\/\//.test(one.page))
-        .map((one) => `<div class="card"><a class="station" href="${escape(one.page)}"><div class="live">${one.state === "live" ? "● LIVE" : "off the air"}</div><div class="name">${escape(one.name)}</div><div class="now">${escape(nowLine(one.nowPlaying))}</div></a></div>`)
+        .map((one) => `<div class="card"><a class="station" href="${escape(one.page)}"><div class="live">${one.state === "live" ? "● LIVE" : one.state === "vod" ? "▶ ON DEMAND" : "off the air"}</div><div class="name">${escape(one.name)}</div><div class="now">${escape(nowLine(one.nowPlaying))}</div></a></div>`)
         .join("");
     let page = GUIDE_HTML;
     for (const group of GROUPS) {
@@ -190,6 +190,8 @@ export const GUIDE_HTML = `<!doctype html>
   <p class="lead">Radio and TV, on the air now. Pick one and press play.</p>
   <h2 id="rooms-title" hidden>Live rooms</h2>
   <div id="rooms" class="grid" aria-live="polite"></div>
+  <h2 id="vod-title" hidden>On demand</h2>
+  <div id="vod" class="grid" aria-live="polite"></div>
   <h2 id="ai-title" hidden>AI Radio</h2>
   <div id="ai" class="grid" aria-live="polite"></div>
   <h2 id="shared-title" hidden>Shared by listeners</h2>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/broadcast.ts

@@ -129,7 +129,9 @@ export function buildBroadcastArgs(plan: BroadcastPlan): string[] {
     "-bufsize", `${plan.settings.videoBitrate * 2}k`,
     // A strict constant frame rate. A source that only produces frames when
     // something changes reads to YouTube as a stream that is falling behind.
-    "-vf", `scale=${width}:${height},fps=${plan.settings.framerate}`,
+    // Letterboxed, never stretched, and square pixels first so an anamorphic
+    // source keeps its shape.
+    "-vf", `scale='trunc(iw*sar/2)*2':ih,setsar=1,scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${plan.settings.framerate}`,
     "-pix_fmt", "yuv420p",
     "-g", String(gop),
     "-c:a", "aac",

package/src/guide-vods.ts

@@ -0,0 +1,302 @@
+/**
+ * On demand: published files on the station guide.
+ *
+ * A live room plays wherever the room is now; a video on demand plays from
+ * its start, and a listener may seek. It is one library item of any nixamp
+ * server, at the address `https://host/api/v1/library/items/<id>/play?k=KEY`
+ * (library-routes.ts: the file itself when a browser takes it, else an MP4
+ * made on the way). A nixamp.com member publishes one with a rights basis, as
+ * a live room is published; the guide lists it under "On demand", and its
+ * short link, <watchBase>/vod/<id>, is the thing to share.
+ *
+ * Nothing here plays anything: the file's own server does, and this only asks
+ * it, now and then, whether the file is still there and what it is.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { ROOM_BASES, type RoomBasis } from "./guide-rooms.ts";
+import type { GuideEntry } from "./station-guide.ts";
+
+export interface GuideVod {
+  id: string;
+  /** The file's play address, with its listen key. */
+  play: string;
+  name: string;
+  kind: "audio" | "video";
+  /** Seconds; 0 when its server did not know. */
+  duration: number;
+  basis: RoomBasis;
+  note: string;
+  /** The nixamp.com account that published it ("" for this server's owner). */
+  by: string;
+  publishedAt: number;
+}
+
+/** Files one member may have on the guide at once, and files on it in all. */
+export const VODS_PER_MEMBER = 25;
+export const VODS_MAX = 1000;
+const STATE_TTL_MS = 60_000;
+const PROBE_TIMEOUT_MS = 4_000;
+
+/**
+ * A file's play address taken apart, or null when it is not one: https (http
+ * only for a loopback address, for tests), a library item, a key, nothing else.
+ */
+export function vodAddress(input: string): { origin: string; item: string; key: string; play: string } | null {
+  let url: URL;
+  try {
+    url = new URL(input.trim());
+  } catch {
+    return null;
+  }
+  const loopback = url.hostname === "127.0.0.1" || url.hostname === "localhost";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) return null;
+  if (url.username || url.password || url.hash) return null;
+  const item = /^\/api\/v1\/library\/items\/([0-9a-f]{16})\/(?:play|stream)\/?$/.exec(url.pathname);
+  if (!item) return null;
+  const key = url.searchParams.get("k") ?? "";
+  if (!/^[A-Za-z0-9_-]{8,128}$/.test(key) || [...url.searchParams.keys()].some((name) => name !== "k")) return null;
+  return { origin: url.origin, item: item[1]!, key, play: `${url.origin}/api/v1/library/items/${item[1]}/play?k=${key}` };
+}
+
+export const vodPage = (base: string, id: string): string => `${base}/vod/${id}`;
+
+export class VodStore {
+  private vods: GuideVod[] = [];
+  constructor(private readonly file: string) {
+    try {
+      if (existsSync(file)) {
+        const saved = JSON.parse(readFileSync(file, "utf8")) as { vods?: GuideVod[] };
+        this.vods = (saved.vods ?? []).filter((one) => vodAddress(one.play) !== null);
+      }
+    } catch {
+      // Unreadable is empty; the next write replaces it.
+    }
+  }
+
+  static fileFor(stateDir: string, port: number): string {
+    return join(stateDir, `guide-vods-${port}.json`);
+  }
+
+  /** Newest first, the order the guide shows them. */
+  list(): GuideVod[] {
+    return [...this.vods].sort((a, b) => b.publishedAt - a.publishedAt);
+  }
+
+  get(id: string): GuideVod | undefined {
+    return this.vods.find((one) => one.id === id);
+  }
+
+  /** Publishes a file, or refreshes the one already published at that address (its link stays). */
+  put(vod: Omit<GuideVod, "id" | "publishedAt">): GuideVod {
+    const existing = this.vods.find((one) => one.play === vod.play);
+    const saved: GuideVod = { ...vod, id: existing?.id ?? randomBytes(6).toString("base64url"), publishedAt: existing?.publishedAt ?? Date.now() };
+    this.vods = [...this.vods.filter((one) => one.play !== vod.play), saved];
+    this.save();
+    return saved;
+  }
+
+  remove(id: string): boolean {
+    const before = this.vods.length;
+    this.vods = this.vods.filter((one) => one.id !== id);
+    if (this.vods.length === before) return false;
+    this.save();
+    return true;
+  }
+
+  private save(): void {
+    writeFileSync(`${this.file}.part`, `${JSON.stringify({ version: 1, vods: this.vods }, null, 2)}\n`);
+    renameSync(`${this.file}.part`, this.file);
+  }
+}
+
+export interface VodState {
+  name: string;
+  kind: "audio" | "video";
+  duration: number;
+  artist: string;
+}
+
+/** Asks a file's own server what it is: its library item, read with the same key. */
+export class VodProbe {
+  private cache = new Map<string, { at: number; state: VodState | null }>();
+  /** `refuse` names why an address may not be fetched from this machine, or "" (see RoomProbe). */
+  constructor(
+    private readonly fetcher: typeof fetch = fetch,
+    private readonly refuse: (link: string) => Promise<string> = async () => "",
+  ) {}
+
+  async state(play: string, fresh = false): Promise<VodState | null> {
+    const cached = this.cache.get(play);
+    if (!fresh && cached && Date.now() - cached.at < STATE_TTL_MS) return cached.state;
+    const state = await this.ask(play).catch(() => null);
+    this.cache.set(play, { at: Date.now(), state });
+    if (this.cache.size > 2000) this.cache.delete(this.cache.keys().next().value!);
+    return state;
+  }
+
+  private async ask(play: string): Promise<VodState | null> {
+    const address = vodAddress(play);
+    if (!address || (await this.refuse(address.play)) !== "") return null;
+    const answer = await this.fetcher(`${address.origin}/api/v1/library/items/${address.item}?k=${address.key}`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS), redirect: "error" });
+    if (!answer.ok) return null;
+    const item = ((await answer.json()) as { item?: Record<string, unknown> }).item;
+    if (!item || item["state"] !== "ready") return null;
+    const rel = String(item["rel"] ?? "");
+    const fallback = rel.split("/").pop()?.replace(/\.[^.]+$/, "") ?? address.item;
+    return {
+      name: String(item["title"] || fallback).slice(0, 160),
+      kind: item["video"] === true ? "video" : "audio",
+      duration: Number(item["duration"]) || 0,
+      artist: String(item["artist"] ?? "").slice(0, 160),
+    };
+  }
+}
+
+/** "1:02:03" or "4:05". */
+export function clock(seconds: number): string {
+  const s = Math.max(0, Math.round(seconds));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const pad = (n: number): string => String(n).padStart(2, "0");
+  return h > 0 ? `${h}:${pad(m)}:${pad(s % 60)}` : `${m}:${pad(s % 60)}`;
+}
+
+/** The published files as guide cards, newest first; one whose server no longer has it says so. */
+export async function vodEntries(store: VodStore, probe: VodProbe, base: string): Promise<GuideEntry[]> {
+  return Promise.all(store.list().map(async (vod) => {
+    const state = await probe.state(vod.play);
+    return {
+      id: vod.id,
+      name: vod.name,
+      kind: state?.kind ?? vod.kind,
+      group: "vod" as const,
+      state: state ? "vod" : "offline",
+      page: vodPage(base, vod.id),
+      nowPlaying: { title: clock(state?.duration || vod.duration), artist: state?.artist ?? "" },
+    };
+  }));
+}
+
+/** One file as its page reads it: never who published it, always where it plays. */
+export function vodView(vod: GuideVod, base: string, state: VodState | null): Record<string, unknown> {
+  return {
+    id: vod.id,
+    name: vod.name,
+    kind: state?.kind ?? vod.kind,
+    duration: state?.duration || vod.duration,
+    artist: state?.artist ?? "",
+    note: vod.note,
+    basis: vod.basis,
+    publishedAt: vod.publishedAt,
+    available: state !== null,
+    play: vod.play,
+    page: vodPage(base, vod.id),
+  };
+}
+
+export interface VodContext {
+  store: VodStore;
+  probe: VodProbe;
+  /** The page base for a file's link. */
+  base: string;
+  /** Whether the request holds this server's control key (or is its signed-in owner). */
+  canControl: boolean;
+  /** The nixamp.com account behind the request's session, or "". */
+  member: () => Promise<string>;
+  /** This server's own play address for one of its library items, for the owner publishing by id; "" when it has none. */
+  ownPlay?: (item: string) => string;
+  /** What this server's own library says of one of its items, so publishing it never asks itself over the network. */
+  ownState?: (item: string) => VodState | null;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  /** The request body as text (server.ts readBody). */
+  readBody: (request: IncomingMessage) => Promise<unknown>;
+  /** Refused by the caller's rate limit, or null. */
+  throttle?: () => { retryAfter: number } | null;
+}
+
+/** Answers /api/v1/guide/vods; false when the path is not one. */
+export async function handleVods(request: IncomingMessage, response: ServerResponse, path: string, ctx: VodContext): Promise<boolean> {
+  if (path !== "/api/v1/guide/vods" && !path.startsWith("/api/v1/guide/vods/")) return false;
+  const method = request.method ?? "GET";
+  const one = /^\/api\/v1\/guide\/vods\/([A-Za-z0-9_-]{1,32})$/.exec(path);
+  if (method === "GET" || method === "HEAD") {
+    if (path === "/api/v1/guide/vods") {
+      ctx.json(response, 200, { vods: await vodEntries(ctx.store, ctx.probe, ctx.base) });
+      return true;
+    }
+    const vod = one ? ctx.store.get(one[1]!) : undefined;
+    if (!vod) {
+      ctx.json(response, 404, { error: "no such video on this guide", code: "not_found" });
+      return true;
+    }
+    ctx.json(response, 200, { vod: vodView(vod, ctx.base, await ctx.probe.state(vod.play)) });
+    return true;
+  }
+  const by = ctx.canControl ? "" : await ctx.member();
+  if (!ctx.canControl && by === "") {
+    ctx.json(response, 401, { error: "sign in to nixamp.com to publish a video", code: "sign_in" });
+    return true;
+  }
+  const refused = ctx.throttle?.();
+  if (refused) {
+    response.setHeader("retry-after", String(refused.retryAfter));
+    ctx.json(response, 429, { error: "too many changes; wait a moment", code: "throttled" });
+    return true;
+  }
+  if (path === "/api/v1/guide/vods" && method === "POST") {
+    const raw = await ctx.readBody(request).catch(() => null);
+    const body = (typeof raw === "string" ? (() => { try { return JSON.parse(raw) as unknown; } catch { return null; } })() : raw) as
+      { play?: unknown; item?: unknown; basis?: unknown; note?: unknown; title?: unknown; agree?: unknown } | null;
+    // The owner may name one of this server's own items; everybody else hands over the address.
+    const own = ctx.canControl && typeof body?.item === "string" && /^[0-9a-f]{16}$/.test(body.item) && ctx.ownPlay ? ctx.ownPlay(body.item) : "";
+    const address = vodAddress(own || (typeof body?.play === "string" ? body.play : ""));
+    if (!address) {
+      ctx.json(response, 400, { error: "play must be a nixamp file's address: https://host/api/v1/library/items/<id>/play?k=KEY", code: "bad_address" });
+      return true;
+    }
+    const basis = ROOM_BASES.find((b) => b === body?.basis);
+    if (!basis || body?.agree !== true) {
+      ctx.json(response, 400, { error: "say why it may be shared (owned, permission, licensed, creative-commons or public-domain) and agree", code: "basis_required" });
+      return true;
+    }
+    const state = (own && ctx.ownState ? ctx.ownState(String(body?.item)) : null) ?? await ctx.probe.state(address.play, true);
+    if (!state) {
+      ctx.json(response, 404, { error: "that file is not in its server's library, or the key does not open it", code: "not_found" });
+      return true;
+    }
+    const all = ctx.store.list();
+    const taken = all.find((v) => v.play === address.play);
+    if (taken && taken.by !== by && !ctx.canControl) {
+      ctx.json(response, 409, { error: "somebody else published that file", code: "taken" });
+      return true;
+    }
+    if (by !== "" && all.filter((v) => v.by === by && v.play !== address.play).length >= VODS_PER_MEMBER) {
+      ctx.json(response, 409, { error: `a member may have ${VODS_PER_MEMBER} videos on the guide; take one off first`, code: "too_many" });
+      return true;
+    }
+    if (!taken && all.length >= VODS_MAX) {
+      ctx.json(response, 409, { error: "the guide is full", code: "full" });
+      return true;
+    }
+    const title = typeof body?.title === "string" ? body.title.trim().slice(0, 160) : "";
+    const note = typeof body?.note === "string" ? body.note.trim().slice(0, 300) : "";
+    const vod = ctx.store.put({ play: address.play, name: title || state.name, kind: state.kind, duration: state.duration, basis, note, by: taken?.by ?? by });
+    ctx.json(response, 200, { vod: vodView(vod, ctx.base, state), page: vodPage(ctx.base, vod.id) });
+    return true;
+  }
+  if (one && method === "DELETE") {
+    const vod = ctx.store.get(one[1]!);
+    if (!vod || (!ctx.canControl && vod.by !== by)) {
+      ctx.json(response, 404, { error: "no such video of yours on the guide", code: "not_found" });
+      return true;
+    }
+    ctx.store.remove(vod.id);
+    ctx.json(response, 200, { removed: vod.id });
+    return true;
+  }
+  ctx.json(response, 405, { error: "method not allowed", code: "method_not_allowed" });
+  return true;
+}

package/src/library-cli.ts

@@ -161,6 +161,25 @@ export async function libraryTool(argv: string[]): Promise<number> {
         console.error("nixamp library playlist new NAME [ITEM...] | show ID | add ID ITEM... | delete ID");
         return 2;
       }
+      case "publish": {
+        // On demand on this server's guide (guide-vods.ts): the server builds the
+        // file's public address from its own public URL and listen key.
+        const [item] = rest;
+        const basis = flag(argv, "--basis");
+        if (!item || !basis) { console.error("nixamp library publish needs an item id and --basis owned|permission|licensed|creative-commons|public-domain"); return 2; }
+        return out(await call("POST", "/api/v1/guide/vods", { item, basis, agree: true, title: flag(argv, "--title") ?? "", note: flag(argv, "--note") ?? "" }),
+          (body) => `on demand: ${String(body["page"])}`);
+      }
+      case "vods":
+        return out(await call("GET", "/api/v1/guide/vods"), (body) => {
+          const vods = (body["vods"] as Record<string, unknown>[]) ?? [];
+          return vods.length === 0 ? "nothing published on demand" : vods.map((one) => `${String(one["id"])}  ${String(one["name"])}  ${String(one["page"])}${one["state"] === "offline" ? "  [not answering]" : ""}`).join("\n");
+        });
+      case "unpublish": {
+        const [vod] = rest;
+        if (!vod) { console.error("nixamp library unpublish needs a video id (see nixamp library vods)"); return 2; }
+        return out(await call("DELETE", `/api/v1/guide/vods/${vod}`), (body) => `removed ${String(body["removed"])}`);
+      }
       default:
         console.log(LIBRARY_USAGE);
         return 2;