nixamp 0.43.1 → 0.45.0

package/dist/station-guide.js

@@ -31,6 +31,8 @@ button.report:hover{color:var(--warn)}
 #share .or{color:var(--muted);font-size:.85rem;margin:8px 0 0}
 #status{margin-top:10px;font-size:.9rem;min-height:1.4em}
 footer{margin-top:40px;color:var(--muted);font-size:.85rem}footer a{color:inherit}
+.ad-unit{margin:28px auto 0;display:flex;justify-content:center}.ad-unit iframe{border:0;display:block;background:transparent}
+.ad-banner_300x250 iframe{width:300px;height:250px;max-width:100%}.ad-text_link iframe{width:100%;height:40px}
 `;
 /**
  * A card's now-playing line from tags as they come: links pasted into a title
@@ -63,7 +65,7 @@ const SCRIPT = `
     } catch { button.textContent = "Could not report; try again"; button.disabled = false; }
   };
   const draw = (stations) => {
-    for (const group of ["ai", "shared", "radio", "tv"]) {
+    for (const group of ["rooms", "ai", "shared", "radio", "tv"]) {
       const grid = document.querySelector("#" + group);
       grid.replaceChildren();
       const list = stations.filter((s) => (s.group || (s.kind === "video" ? "tv" : "radio")) === group);
@@ -137,17 +139,18 @@ const SCRIPT = `
   setInterval(load, 15000);
 })();
 `;
+const CRAWLPROOF = "https://crawlproof.com";
 const hash = (text) => `'sha256-${createHash("sha256").update(text).digest("base64")}'`;
 function escape(text) {
     return text.replace(/[&<>"']/g, (one) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[one]);
 }
-const GROUPS = ["ai", "shared", "radio", "tv"];
+const GROUPS = ["rooms", "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
  * /n/<name>), and for a crawler. Everything from a station is escaped.
  */
-export function renderGuide(entries, apiBase = "") {
+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))
@@ -160,6 +163,14 @@ export function renderGuide(entries, apiBase = "") {
             .replace(`<h2 id="${group}-title" hidden>`, made ? `<h2 id="${group}-title">` : `<h2 id="${group}-title" hidden>`)
             .replace(`<div id="${group}" class="grid" aria-live="polite"></div>`, `<div id="${group}" class="grid" aria-live="polite">${made}</div>`);
     }
+    if (ads.site)
+        page = page.replace("</head>", `<script data-site="${escape(ads.site)}" src="${CRAWLPROOF}/stats.js" async></script>\n</head>`);
+    if (ads.slot) {
+        const format = ads.format ?? "banner_300x250";
+        const slot = ads.slot;
+        // The one ad goes at the top of the content, never against the footer.
+        page = page.replace('<p class="lead">Radio and TV, on the air now. Pick one and press play.</p>\n', (lead) => `${lead}  <div class="ad-unit ad-${format}"><iframe src="${CRAWLPROOF}/api/ads/frame?slot=${encodeURIComponent(slot)}&amp;format=${format}" title="Advertisement" loading="lazy" referrerpolicy="strict-origin-when-cross-origin" sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation" scrolling="no"></iframe></div>\n`);
+    }
     const api = /^https:\/\/[^\s"<>]+$/.test(apiBase) ? apiBase.replace(/\/+$/, "") : "";
     return (page.replace('<p id="empty" class="empty">', entries.length ? '<p id="empty" class="empty" hidden>' : '<p id="empty" class="empty">')).replace("<body>", api ? `<body data-api="${escape(api)}">` : "<body>");
 }
@@ -177,6 +188,8 @@ export const GUIDE_HTML = `<!doctype html>
 <main>
   <h1>Live</h1>
   <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="ai-title" hidden>AI Radio</h2>
   <div id="ai" class="grid" aria-live="polite"></div>
   <h2 id="shared-title" hidden>Shared by listeners</h2>
@@ -208,16 +221,55 @@ export const GUIDE_HTML = `<!doctype html>
     <button type="submit">Share it</button>
     <div id="status" role="status" aria-live="polite"></div>
   </form>
-  <footer>Played by <a href="https://nixamp.com">nixamp</a>, on the Moshpit.</footer>
+  <footer>Played by <a href="https://nixamp.com">nixamp</a>.</footer>
 </main>
 <script>${SCRIPT}</script>
 </body>
 </html>
 `;
-export const GUIDE_CSP = [
-    "default-src 'none'", `script-src ${hash(SCRIPT)}`, `style-src 'self' ${hash(STYLE)}`, "connect-src 'self' https:",
-    "img-src 'self' data:", "base-uri 'none'", "form-action 'none'", "frame-ancestors 'none'",
-].join("; ");
+/**
+ * The guide's policy. With crawlproof configured (guideAds below) its tracker
+ * script and its ad frame are allowed from crawlproof.com and nothing else
+ * changes; the tracker reports by fetch, which connect-src https: already allows.
+ */
+export function guideCsp(ads = {}) {
+    return [
+        "default-src 'none'", `script-src ${hash(SCRIPT)}${ads.site ? ` ${CRAWLPROOF}` : ""}`, `style-src 'self' ${hash(STYLE)}`, "connect-src 'self' https:",
+        `img-src 'self' data:${ads.site || ads.slot ? ` ${CRAWLPROOF}` : ""}`, ...(ads.slot ? [`frame-src ${CRAWLPROOF}`] : []),
+        "base-uri 'none'", "form-action 'none'", "frame-ancestors 'none'",
+    ].join("; ");
+}
+export const GUIDE_CSP = guideCsp();
+const AD_ID = /^[A-Za-z0-9-]{1,64}$/;
+/** A setting as the guide may use it: ids that are ids, a format it knows, or nothing. */
+export function cleanGuideAds(value) {
+    if (typeof value !== "object" || value === null)
+        return {};
+    const one = value;
+    const site = typeof one["site"] === "string" && AD_ID.test(one["site"].trim()) ? one["site"].trim() : "";
+    const slot = typeof one["slot"] === "string" && AD_ID.test(one["slot"].trim()) ? one["slot"].trim() : "";
+    const format = one["format"] === "text_link" || one["format"] === "banner_300x250" ? one["format"] : undefined;
+    return { ...(site ? { site } : {}), ...(slot ? { slot } : {}), ...(format && slot ? { format } : {}) };
+}
+/**
+ * crawlproof on the guide: `guideAds` in config.json (`nixamp station guide-ads
+ * --site ID --slot ID`), each overridden by NIXAMP_GUIDE_CRAWLPROOF_SITE /
+ * NIXAMP_GUIDE_AD_SLOT / NIXAMP_GUIDE_AD_FORMAT. Unset is off: a guide on
+ * somebody's own machine carries nobody's tracker.
+ */
+export function guideAds(env = process.env) {
+    const saved = (() => { try {
+        return readConfig().guideAds ?? {};
+    }
+    catch {
+        return {};
+    } })();
+    return cleanGuideAds({
+        site: env["NIXAMP_GUIDE_CRAWLPROOF_SITE"] ?? saved.site,
+        slot: env["NIXAMP_GUIDE_AD_SLOT"] ?? saved.slot,
+        format: env["NIXAMP_GUIDE_AD_FORMAT"] ?? saved.format,
+    });
+}
 /**
  * The hosts whose front page is the guide: `guideHosts` in config.json
  * (`nixamp station guide-host NAME`, which survives restarts and updates),

package/dist/station-page.d.ts

@@ -4,4 +4,9 @@ export declare const STATION_PAGE_HTML = "<!doctype html>\n<html lang=\"en\">\n<
 /** Only its own script and style, only its own server, never framed. */
 export declare const STATION_PAGE_CSP: string;
 /** The built page: its own bundle, styles and player engines, only this server, never framed. */
+/**
+ * A live room's page (/watch): the same built page shape, but what it plays and
+ * asks about is on the room's own server, any https nixamp server.
+ */
+export declare const WATCH_APP_CSP: string;
 export declare const STATION_APP_CSP: string;

package/dist/station-page.js

@@ -209,6 +209,21 @@ export const STATION_PAGE_CSP = [
     "frame-ancestors 'none'",
 ].join("; ");
 /** The built page: its own bundle, styles and player engines, only this server, never framed. */
+/**
+ * A live room's page (/watch): the same built page shape, but what it plays and
+ * asks about is on the room's own server, any https nixamp server.
+ */
+export const WATCH_APP_CSP = [
+    "default-src 'self'",
+    "style-src 'self' 'unsafe-inline'",
+    "media-src 'self' blob: https:",
+    "worker-src 'self' blob:",
+    "img-src 'self' data: blob: https:",
+    "connect-src 'self' https:",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'none'",
+].join("; ");
 export const STATION_APP_CSP = [
     "default-src 'self'",
     "style-src 'self' 'unsafe-inline'",

package/dist/station-routes.d.ts

@@ -83,6 +83,8 @@ export interface StationContext {
     };
     /** The public stations other servers list (guide peers); absent when there are none. */
     peers?: () => Promise<unknown[]>;
+    /** Live rooms members published to this guide (guide-rooms.ts); absent when this server keeps none. */
+    rooms?: () => Promise<unknown[]>;
 }
 declare function links(ctx: StationContext, station: Station, base?: string): {
     page: string;

package/dist/station-routes.js

@@ -100,7 +100,9 @@ export async function handleStations(request, response, path, url, ctx) {
         const shown = new Set(own.map((one) => one.page));
         const others = url.searchParams.has("local") || !ctx.peers ? [] : (await ctx.peers())
             .filter((one) => !shown.has(one.page));
-        ctx.json(response, 200, { stations: [...own, ...others] });
+        // Rooms are this guide's own; a peer asking for its stations does not list them twice.
+        const rooms = url.searchParams.has("local") || !ctx.rooms ? [] : await ctx.rooms();
+        ctx.json(response, 200, { stations: [...rooms, ...own, ...others] });
         return true;
     }
     const listen = LISTEN.exec(path);

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  Lyrics (shown on the station page from each file's own tag, else nichedb.dev; ours published back):\n  nixamp station lyrics                      the key, what was published, which stations may publish\n  nixamp station lyrics publish ID           publish a station's words now (public, listed, basis owned only)\n  nixamp station lyrics key                  nichedb's key (NIXAMP_LYRICS_KEY), from stdin (--clear forgets it)\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.";
+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-ads [--site ID] [--slot ID] [--format banner_300x250|text_link] [--off]\n                     crawlproof analytics (project ID) and an ad unit (slot ID) on the guide\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  Lyrics (shown on the station page from each file's own tag, else nichedb.dev; ours published back):\n  nixamp station lyrics                      the key, what was published, which stations may publish\n  nixamp station lyrics publish ID           publish a station's words now (public, listed, basis owned only)\n  nixamp station lyrics key                  nichedb's key (NIXAMP_LYRICS_KEY), from stdin (--clear forgets it)\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

@@ -16,6 +16,8 @@ export const USAGE = `nixamp station — make a collection into a station
   nixamp station delete ID
   nixamp station guide-host NAME [--remove]
                      NAME's front page is the public station guide (e.g. a Moshpit name)
+  nixamp station guide-ads [--site ID] [--slot ID] [--format banner_300x250|text_link] [--off]
+                     crawlproof analytics (project ID) and an ad unit (slot ID) on the guide
   nixamp station guide-peer URL [--remove]
                      the guide also lists the public, listed stations of the server at URL
   nixamp station auto [--no-video] [--min 10] [--films 3] [--tv 2] [--breaks 600] [--no-start]

package/package.json

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

package/src/guide-rooms.ts

@@ -0,0 +1,296 @@
+/**
+ * Live rooms on the station guide.
+ *
+ * A room is a channel, or the live stream, of any nixamp server: the address
+ * a Share or a "?play=" link carries, `https://host:port/api/channels/<id>?k=KEY`
+ * or `https://host:port/api/live?k=KEY`. A nixamp.com member publishes one with
+ * a rights basis, as a station is published; the guide lists it beside the
+ * stations, and its card opens /watch?play=<that address>, which plays it as
+ * a film or as radio, whichever it carries.
+ *
+ * Nothing here plays anything: the room's own server does, and this only asks
+ * it, now and then, whether the room is on the air and what is on it.
+ */
+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 { readConfig } from "./library.ts";
+import type { GuideEntry } from "./station-guide.ts";
+
+/** Why a room may be broadcast, the same five reasons a station gives. */
+export const ROOM_BASES = ["owned", "permission", "licensed", "creative-commons", "public-domain"] as const;
+export type RoomBasis = typeof ROOM_BASES[number];
+
+export interface GuideRoom {
+  id: string;
+  /** The room's stream address, with its listen key. */
+  play: string;
+  name: string;
+  kind: "audio" | "video";
+  basis: RoomBasis;
+  note: string;
+  /** The nixamp.com account that published it ("" for this server's owner). */
+  by: string;
+  publishedAt: number;
+}
+
+/** Rooms one member may have on the guide at once, and rooms on it in all. */
+export const ROOMS_PER_MEMBER = 5;
+export const ROOMS_MAX = 200;
+const STATE_TTL_MS = 15_000;
+const PROBE_TIMEOUT_MS = 4_000;
+
+/**
+ * A room's address taken apart, or null when it is not one: https (http only
+ * for a loopback address, for tests), a channel or the live stream, a key,
+ * and nothing else in the query.
+ */
+export function roomAddress(input: string): { origin: string; channel: string | null; 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 channel = /^\/api\/channels\/([A-Za-z0-9._~-]{1,120})\/?$/.exec(url.pathname);
+  const live = /^\/api\/live\/?$/.test(url.pathname);
+  if (!channel && !live) 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;
+  const path = channel ? `/api/channels/${channel[1]}` : "/api/live";
+  return { origin: url.origin, channel: channel ? channel[1]! : null, key, play: `${url.origin}${path}?k=${key}` };
+}
+
+/** Where the guide links a room's page: config `watchBase`, NIXAMP_WATCH_BASE, else this server. */
+export function watchBase(fallback: string, env: Record<string, string | undefined> = process.env): string {
+  const saved = (() => { try { return readConfig().watchBase ?? ""; } catch { return ""; } })();
+  const chosen = (env["NIXAMP_WATCH_BASE"] || saved || fallback).trim().replace(/\/+$/, "");
+  return /^https?:\/\/[^\s"<>]+$/.test(chosen) ? chosen : fallback;
+}
+
+export const watchPage = (base: string, play: string): string => `${base}/watch?play=${encodeURIComponent(play)}`;
+
+export class RoomStore {
+  private rooms: GuideRoom[] = [];
+  constructor(private readonly file: string) {
+    try {
+      if (existsSync(file)) {
+        const saved = JSON.parse(readFileSync(file, "utf8")) as { rooms?: GuideRoom[] };
+        this.rooms = (saved.rooms ?? []).filter((one) => roomAddress(one.play) !== null);
+      }
+    } catch {
+      // Unreadable is empty; the next write replaces it.
+    }
+  }
+
+  static fileFor(stateDir: string, port: number): string {
+    return join(stateDir, `guide-rooms-${port}.json`);
+  }
+
+  list(): GuideRoom[] {
+    return [...this.rooms];
+  }
+
+  get(id: string): GuideRoom | undefined {
+    return this.rooms.find((one) => one.id === id);
+  }
+
+  /** Publishes a room, or refreshes the one already published at that address. */
+  put(room: Omit<GuideRoom, "id" | "publishedAt">): GuideRoom {
+    const existing = this.rooms.find((one) => one.play === room.play);
+    const saved: GuideRoom = { ...room, id: existing?.id ?? randomBytes(6).toString("base64url"), publishedAt: Date.now() };
+    this.rooms = [...this.rooms.filter((one) => one.play !== room.play), saved];
+    this.save();
+    return saved;
+  }
+
+  remove(id: string): boolean {
+    const before = this.rooms.length;
+    this.rooms = this.rooms.filter((one) => one.id !== id);
+    if (this.rooms.length === before) return false;
+    this.save();
+    return true;
+  }
+
+  private save(): void {
+    writeFileSync(`${this.file}.part`, `${JSON.stringify({ version: 1, rooms: this.rooms }, null, 2)}\n`);
+    renameSync(`${this.file}.part`, this.file);
+  }
+}
+
+export interface RoomState {
+  /** Whether the room's server says it is on the air. */
+  live: boolean;
+  name: string;
+  kind: "audio" | "video";
+  nowPlaying: { title: string; artist: string } | null;
+}
+
+interface ChannelRow {
+  id: string;
+  name?: string;
+  kind?: string;
+  live?: boolean;
+  codecs?: { tags?: { title?: string; artist?: string } };
+}
+
+/** Asks a room's own server what is on it: its channel list for a channel, the stream's headers for the live stream. */
+export class RoomProbe {
+  private cache = new Map<string, { at: number; state: RoomState | null }>();
+  /**
+   * `refuse` names why an address may not be fetched from this machine (a
+   * private or loopback network), or "": a member chooses the address, and
+   * this server must not become their way into its own network.
+   */
+  constructor(
+    private readonly fetcher: typeof fetch = fetch,
+    private readonly refuse: (link: string) => Promise<string> = async () => "",
+  ) {}
+
+  async state(play: string, fresh = false): Promise<RoomState | 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 > 500) this.cache.delete(this.cache.keys().next().value!);
+    return state;
+  }
+
+  private async ask(play: string): Promise<RoomState | null> {
+    const address = roomAddress(play);
+    if (!address || (await this.refuse(address.play)) !== "") return null;
+    if (address.channel !== null) {
+      const answer = await this.fetcher(`${address.origin}/api/channels?k=${address.key}`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS), redirect: "error" });
+      if (!answer.ok) return null;
+      const body = (await answer.json()) as { channels?: ChannelRow[] };
+      const row = (body.channels ?? []).find((one) => one.id === address.channel);
+      if (!row) return null;
+      const tags = row.codecs?.tags;
+      return {
+        live: row.live !== false,
+        name: String(row.name ?? address.channel).replace(/\/+$/, "").slice(0, 120),
+        kind: row.kind === "video" ? "video" : "audio",
+        nowPlaying: tags && (tags.title || tags.artist) ? { title: String(tags.title ?? ""), artist: String(tags.artist ?? "") } : null,
+      };
+    }
+    // The live stream: on the air when it answers with media.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+      const answer = await this.fetcher(address.play, { signal: controller.signal, redirect: "error" });
+      const type = answer.headers.get("content-type") ?? "";
+      controller.abort();
+      if (!answer.ok) return null;
+      return { live: true, name: "Live", kind: type.startsWith("video/") ? "video" : "audio", nowPlaying: null };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** The rooms as guide cards: the page to open, on the air or not, and what is on. */
+export async function roomEntries(store: RoomStore, probe: RoomProbe, base: string): Promise<GuideEntry[]> {
+  return Promise.all(store.list().map(async (room) => {
+    const state = await probe.state(room.play);
+    return {
+      id: room.id,
+      name: room.name,
+      kind: state?.kind ?? room.kind,
+      group: "rooms" as const,
+      state: state?.live ? "live" : "offline",
+      page: watchPage(base, room.play),
+      nowPlaying: state?.nowPlaying ?? null,
+    };
+  }));
+}
+
+export interface RoomContext {
+  store: RoomStore;
+  probe: RoomProbe;
+  /** The page base for a room's card. */
+  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>;
+  json: (response: ServerResponse, status: number, body: unknown) => void;
+  readBody: (request: IncomingMessage) => Promise<unknown>;
+  /** Refused by the caller's rate limit, or null. */
+  throttle?: () => { retryAfter: number } | null;
+}
+
+/** Answers /api/v1/guide/rooms; false when the path is not one. */
+export async function handleRooms(request: IncomingMessage, response: ServerResponse, path: string, ctx: RoomContext): Promise<boolean> {
+  if (path !== "/api/v1/guide/rooms" && !path.startsWith("/api/v1/guide/rooms/")) return false;
+  const method = request.method ?? "GET";
+  if (path === "/api/v1/guide/rooms" && (method === "GET" || method === "HEAD")) {
+    ctx.json(response, 200, { rooms: await roomEntries(ctx.store, ctx.probe, ctx.base) });
+    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 live room", 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/rooms" && method === "POST") {
+    const body = (await ctx.readBody(request).catch(() => null)) as { play?: unknown; basis?: unknown; note?: unknown; title?: unknown; agree?: unknown } | null;
+    const address = roomAddress(typeof body?.play === "string" ? body.play : "");
+    if (!address) {
+      ctx.json(response, 400, { error: "play must be a nixamp room's stream address: https://host/api/channels/<id>?k=KEY", code: "bad_address" });
+      return true;
+    }
+    const basis = ROOM_BASES.find((one) => one === body?.basis);
+    if (!basis || body?.agree !== true) {
+      ctx.json(response, 400, { error: "say why it may be broadcast (owned, permission, licensed, creative-commons or public-domain) and agree", code: "basis_required" });
+      return true;
+    }
+    const state = await ctx.probe.state(address.play, true);
+    if (!state) {
+      ctx.json(response, 404, { error: "that room is not on its server, or the key does not open it", code: "not_found" });
+      return true;
+    }
+    const all = ctx.store.list();
+    const mine = all.filter((one) => one.by === by && one.play !== address.play);
+    if (by !== "" && mine.length >= ROOMS_PER_MEMBER) {
+      ctx.json(response, 409, { error: `a member may have ${ROOMS_PER_MEMBER} rooms on the guide; take one off first`, code: "too_many" });
+      return true;
+    }
+    if (!all.some((one) => one.play === address.play) && all.length >= ROOMS_MAX) {
+      ctx.json(response, 409, { error: "the guide is full", code: "full" });
+      return true;
+    }
+    const taken = all.find((one) => one.play === address.play);
+    if (taken && taken.by !== by && !ctx.canControl) {
+      ctx.json(response, 409, { error: "somebody else published that room", code: "taken" });
+      return true;
+    }
+    const title = typeof body?.title === "string" ? body.title.trim().slice(0, 120) : "";
+    const note = typeof body?.note === "string" ? body.note.trim().slice(0, 300) : "";
+    const room = ctx.store.put({ play: address.play, name: title || state.name, kind: state.kind, basis, note, by: taken?.by ?? by });
+    ctx.json(response, 200, { room: { id: room.id, name: room.name, kind: room.kind, basis: room.basis }, page: watchPage(ctx.base, room.play) });
+    return true;
+  }
+  const one = /^\/api\/v1\/guide\/rooms\/([A-Za-z0-9_-]{1,32})$/.exec(path);
+  if (one && method === "DELETE") {
+    const room = ctx.store.get(one[1]!);
+    if (!room || (!ctx.canControl && room.by !== by)) {
+      ctx.json(response, 404, { error: "no such room of yours on the guide", code: "not_found" });
+      return true;
+    }
+    ctx.store.remove(room.id);
+    ctx.json(response, 200, { removed: room.id });
+    return true;
+  }
+  ctx.json(response, 405, { error: "method not allowed", code: "method_not_allowed" });
+  return true;
+}

package/src/library.ts

@@ -31,6 +31,10 @@ export interface Config {
   guideHosts?: string[];
   /** Other servers (https base addresses) whose public, listed stations this guide shows too. */
   guidePeers?: string[];
+  /** Where the guide links a published live room's page (https://live.streaming.pit.world); this server's own address when unset. */
+  watchBase?: string;
+  /** crawlproof on the guide: tracker project id (site), ad slot and format (`nixamp station guide-ads`). */
+  guideAds?: { site?: string; slot?: string; format?: "banner_300x250" | "text_link" };
   /** Station limits kept across restarts (station-metering.ts). */
   limits?: Record<string, unknown>;
   /** Proxies whose X-Forwarded-For is believed for listener shares (`nixamp station shares trust ADDRESS`). */
@@ -53,6 +57,7 @@ export function readConfig(): Config {
       ...(typeof record["limits"] === "object" && record["limits"] !== null ? { limits: record["limits"] as Record<string, unknown> } : {}),
       ...(Array.isArray(record["trustedProxies"]) ? { trustedProxies: (record["trustedProxies"] as unknown[]).filter((one): one is string => typeof one === "string") } : {}),
       ...(Array.isArray(record["guideHosts"]) ? { guideHosts: (record["guideHosts"] as unknown[]).filter((one): one is string => typeof one === "string") } : {}),
+      ...(typeof record["guideAds"] === "object" && record["guideAds"] !== null ? { guideAds: record["guideAds"] as Config["guideAds"] } : {}),
       ...(Array.isArray(record["guidePeers"]) ? { guidePeers: (record["guidePeers"] as unknown[]).filter((one): one is string => typeof one === "string") } : {}),
     };
   } catch {

package/src/pit-footer.ts

@@ -0,0 +1,40 @@
+/**
+ * The pit.world global footer (site name, search, ring, publish), fetched on
+ * the server and appended as the last thing in <body> of the nixamp.com pages.
+ *
+ * A module-level cache: the last good copy is served, and one older than an
+ * hour is refreshed in the background (3s timeout). A failed refresh keeps the
+ * old copy; with no copy at all the page goes out unchanged, so pit.world being
+ * down never breaks a page.
+ */
+const PIT_FOOTER_URL = "https://pit.world/snippets/footer.html?site=nixamp.com";
+const MAX_AGE_MS = 60 * 60 * 1000;
+
+let cached = "";
+let fetchedAt = 0;
+let inflight: Promise<void> | null = null;
+
+export function refreshPitFooter(): Promise<void> {
+  inflight ??= fetch(PIT_FOOTER_URL, { signal: AbortSignal.timeout(3000) })
+    .then(async (res) => {
+      const text = res.ok ? await res.text() : "";
+      if (!text.includes("data-pit-footer")) throw new Error(`pit footer: HTTP ${res.status}`);
+      cached = text;
+      fetchedAt = Date.now();
+    })
+    .catch(() => {
+      fetchedAt = Date.now() - MAX_AGE_MS + 60_000; // try again in a minute
+    })
+    .finally(() => {
+      inflight = null;
+    });
+  return inflight;
+}
+
+/** The page with the footer before its last </body>, or the page unchanged. */
+export function withPitFooter(page: string): string {
+  if (Date.now() - fetchedAt > MAX_AGE_MS) void refreshPitFooter();
+  if (!cached || page.includes("data-pit-footer")) return page;
+  const at = page.lastIndexOf("</body>");
+  return at < 0 ? page : page.slice(0, at) + cached + page.slice(at);
+}