nixamp 0.35.0 → 0.36.0

package/src/auto-stations.ts

@@ -0,0 +1,171 @@
+/**
+ * Auto stations: a station for every genre the library has, kept up to date.
+ *
+ * Radio from the music's own genre tags, folded into genres a listener would
+ * recognise ("Rap/Hip-Hop", "Hip Hop" and "Gangsta" are all Hip-Hop; "Pop,
+ * Rock, Metal" is in three). TV from the genres nichedb knows for each film.
+ * Lectures, interviews and talk are not music and stay out of radio.
+ *
+ * Each genre's station is found again by its key on the next sync and its
+ * files replaced, so new music lands in the right station by itself and a
+ * station's link never changes. Nothing is published: an auto station is
+ * unlisted, a link for whoever the owner hands it to. Making one public is
+ * the owner's decision, with the rights basis that asks for.
+ *
+ * TV costs a core per running station (it is re-encoded), so only the
+ * biggest few run; the rest are made and wait, stopped.
+ */
+import type { LibraryIndex, LibraryItem } from "./library-index.ts";
+import { shown } from "./library-index.ts";
+import type { StationRunner } from "./station-runner.ts";
+import type { Station, StationStore } from "./stations.ts";
+
+const RULES: Array<[RegExp, string]> = [
+  [/metal|thrash|trash|doom|death|grind|neue deutsche|h(a|ä)rte|djent|metalcore/i, "Metal"],
+  [/punk|hardcore|emo|screamo/i, "Punk"],
+  [/hip.?hop|\brap\b|gangsta|trap|grime|drill/i, "Hip-Hop"],
+  [/industrial/i, "Industrial"],
+  [/electro|techno|house|edm|dance|trance|ambient|drum.?n.?bass|dubstep|synth/i, "Electronic"],
+  [/reggae|\bska\b|\bdub\b|dancehall/i, "Reggae"],
+  [/jazz|swing|bebop/i, "Jazz"],
+  [/blues/i, "Blues"],
+  [/classical|symphon|orchestr|baroque|opera/i, "Classical"],
+  [/country|folk|bluegrass|americana/i, "Country & Folk"],
+  [/soul|r&b|rnb|funk|motown|gospel/i, "Soul & R&B"],
+  [/latin|reggaeton|salsa|bachata|cumbia/i, "Latin"],
+  [/alternat|indie|ind(e|é)|grunge|shoegaze/i, "Alternative"],
+  [/rock/i, "Rock"],
+  [/pop/i, "Pop"],
+];
+
+const NOT_MUSIC = /lecture|interview|audiobook|podcast|speech|spoken|talk|course|sermon|lesson|comedy/i;
+
+/** The genres a tag belongs to, recognisably named; [] when it is not music or not known. */
+export function genreBuckets(raw: string): string[] {
+  if (!raw || NOT_MUSIC.test(raw)) return [];
+  const out = new Set<string>();
+  for (const part of raw.split(/[,;/|]+|\s+&\s+/)) {
+    const hit = RULES.find(([pattern]) => pattern.test(part));
+    if (hit) out.add(hit[1]);
+  }
+  return [...out];
+}
+
+export interface AutoOptions {
+  /** Radio from tags; TV from nichedb's genres. */
+  video: boolean;
+  /** A genre needs at least this many files (radio) to get a station. */
+  minItems: number;
+  /** Films for a TV station. */
+  minFilms: number;
+  start: boolean;
+  /** TV stations running at once. */
+  maxVideoRunning: number;
+  /** Seconds between breaks on the stations this makes. */
+  breaksEvery: number;
+}
+
+export const DEFAULT_AUTO: AutoOptions = { video: true, minItems: 10, minFilms: 3, start: true, maxVideoRunning: 2, breaksEvery: 600 };
+
+export interface AutoReport {
+  radio: Array<{ genre: string; id: string; files: number; made: boolean; running: boolean }>;
+  tv: Array<{ genre: string; id: string; films: number; made: boolean; running: boolean }>;
+  skipped: string[];
+}
+
+export interface AutoDeps {
+  index: LibraryIndex;
+  store: StationStore;
+  runner: StationRunner;
+  owner: string;
+  /** nichedb's genres for a film, from the enrichment cache or a lookup; [] when unknown. */
+  filmGenres?: (title: string) => Promise<string[]>;
+  /** Whether another station may be started now (the server's running limit). */
+  mayStart: () => boolean;
+  log?: (line: string) => void;
+}
+
+function order(items: LibraryItem[]): LibraryItem[] {
+  return [...items].sort((a, b) => {
+    const x = shown(a), y = shown(b);
+    return (x.albumArtist || x.artist).localeCompare(y.albumArtist || y.artist) || x.album.localeCompare(y.album) || x.disc - y.disc || x.track - y.track || a.rel.localeCompare(b.rel);
+  });
+}
+
+async function upsert(
+  deps: AutoDeps,
+  key: string,
+  name: string,
+  paths: string[],
+  video: boolean,
+  options: AutoOptions,
+): Promise<{ station: Station; made: boolean }> {
+  const existing = deps.store.byAuto(key);
+  if (existing) {
+    const same = existing.items.length === paths.length && existing.items.every((one, at) => one === paths[at]);
+    return { station: same ? existing : deps.store.update(existing.id, {}, paths), made: false };
+  }
+  const station = deps.store.create({ name, shuffle: true, repeat: true, video, breaksEvery: options.breaksEvery }, paths, deps.owner);
+  deps.store.markAuto(station.id, key);
+  // A link, not a listing: unlisted needs no rights basis and publishes nothing.
+  deps.store.setAccess(station.id, { visibility: "unlisted" }, deps.owner || "auto");
+  return { station, made: true };
+}
+
+/** Make or update a station per genre; start what the limits allow. */
+export async function syncAutoStations(deps: AutoDeps, options: AutoOptions = DEFAULT_AUTO): Promise<AutoReport> {
+  const report: AutoReport = { radio: [], tv: [], skipped: [] };
+  const ready = deps.index.search({ state: "ready", limit: 500, offset: 0 });
+  // search() pages at 500; walk them all.
+  const all: LibraryItem[] = [...ready.items];
+  for (let offset = 500; offset < ready.total; offset += 500) all.push(...deps.index.search({ state: "ready", limit: 500, offset }).items);
+
+  const radio = new Map<string, LibraryItem[]>();
+  for (const item of all) {
+    if (item.video) continue;
+    for (const genre of genreBuckets(shown(item).genre)) {
+      const list = radio.get(genre) ?? [];
+      list.push(item);
+      radio.set(genre, list);
+    }
+  }
+  for (const [genre, items] of [...radio].sort((a, b) => b[1].length - a[1].length)) {
+    if (items.length < options.minItems) {
+      report.skipped.push(`${genre} radio (${items.length} files)`);
+      continue;
+    }
+    const { station, made } = await upsert(deps, `genre:audio:${genre.toLowerCase()}`, `${genre} Radio`, order(items).map((one) => one.path), false, options);
+    let running = station.desired === "running";
+    if (!running && options.start && deps.mayStart()) {
+      await deps.runner.start(station.id).then(() => { running = true; }, (error: Error) => deps.log?.(`  auto stations: ${genre} Radio did not start: ${error.message}`));
+    }
+    report.radio.push({ genre, id: station.id, files: items.length, made, running });
+  }
+
+  if (options.video && deps.filmGenres) {
+    const tv = new Map<string, LibraryItem[]>();
+    for (const item of all) {
+      if (!item.video || item.duration < 40 * 60) continue;
+      const genres = await deps.filmGenres(shown(item).title).catch(() => []);
+      for (const genre of genres.slice(0, 2)) {
+        const list = tv.get(genre) ?? [];
+        list.push(item);
+        tv.set(genre, list);
+      }
+    }
+    let runningTv = deps.store.list().filter((one) => one.video && one.auto && one.desired === "running").length;
+    for (const [genre, films] of [...tv].sort((a, b) => b[1].length - a[1].length)) {
+      if (films.length < options.minFilms) {
+        report.skipped.push(`${genre} TV (${films.length} films)`);
+        continue;
+      }
+      const { station, made } = await upsert(deps, `genre:video:${genre.toLowerCase()}`, `${genre} TV`, films.map((one) => one.path), true, options);
+      let running = station.desired === "running";
+      if (!running && options.start && runningTv < options.maxVideoRunning && deps.mayStart()) {
+        await deps.runner.start(station.id).then(() => { running = true; runningTv += 1; }, (error: Error) => deps.log?.(`  auto stations: ${genre} TV did not start: ${error.message}`));
+      }
+      report.tv.push({ genre, id: station.id, films: films.length, made, running });
+    }
+  }
+  return report;
+}

package/src/channels.ts

@@ -129,7 +129,7 @@ export interface PullResume {
    * lists of files on this machine; not remembered, because whoever owns the
    * rotation (the station) puts it back.
    */
-  rotation?: Pick<PlaylistInput, "repeat" | "order" | "current" | "excluded" | "onFailure" | "passOver">;
+  rotation?: Pick<PlaylistInput, "repeat" | "order" | "current" | "excluded" | "onFailure" | "passOver" | "breaks">;
 }
 
 /**

package/src/library-index.ts

@@ -335,6 +335,8 @@ export class LibraryIndex {
   private timer: ReturnType<typeof setTimeout> | null = null;
   private dirty = false;
   private jobs = new Map<string, { report: ScanReport; abort: AbortController }>();
+  /** Told when any scan finishes, for whatever keeps up with the library (auto stations). */
+  onScanned: ((report: ScanReport) => void) | null = null;
 
   constructor(
     private readonly file: string,
@@ -622,6 +624,9 @@ export class LibraryIndex {
     report.status = signal.aborted ? "cancelled" : "done";
     report.finishedAt = this.now();
     this.touch();
+    if (report.status === "done") {
+      try { this.onScanned?.(report); } catch { /* a listener's trouble is not the scan's */ }
+    }
     return report;
   }
 

package/src/library.ts

@@ -25,6 +25,8 @@ export interface Config {
   library?: string;
   /** Whether this machine is listed in the public directory; unset until chosen. */
   publish?: boolean;
+  /** Auto stations: a station per genre, re-synced after every library scan. */
+  autoStations?: Record<string, unknown>;
 }
 
 export function configPath(): string {
@@ -39,6 +41,7 @@ export function readConfig(): Config {
     return {
       ...(typeof record["library"] === "string" ? { library: record["library"] } : {}),
       ...(typeof record["publish"] === "boolean" ? { publish: record["publish"] } : {}),
+      ...(typeof record["autoStations"] === "object" && record["autoStations"] !== null ? { autoStations: record["autoStations"] as Record<string, unknown> } : {}),
     };
   } catch {
     return {};

package/src/playlist-input.ts

@@ -34,6 +34,12 @@ export interface PlaylistInput {
    * still arriving, and the channel redials and waits for it.
    */
   passOver?: boolean;
+  /**
+   * A break every so often, between entries and never in the middle of one:
+   * `next` answers a file to play (an advert, an ident) or null for no break
+   * this time. The break is outside the rotation and the station's history.
+   */
+  breaks?: { everySeconds: number; next: () => Promise<string | null> };
   /** Told when an entry is passed over because it would not play. */
   onFailure?: (event: { at: number; file: string; reason: string }) => void;
 }
@@ -99,9 +105,10 @@ export class PlaylistInputStream {
       let files = o.current?.() ?? o.files;
       if (files.length === 0) throw new Error("The playlist is empty");
       let order = orderFor(files);
-      let step = Math.min(o.at, order.length);
+      let step = Math.min(Math.max(0, o.at), order.length);
       let played = 0;
       let last = "";
+      let lastBreak = 0;
       for (;;) {
         if (signal.aborted) break;
         // Asked at every boundary, so an edit lands on the next track. The
@@ -128,11 +135,20 @@ export class PlaylistInputStream {
           continue;
         }
         {
-          const at = order[step]!;
-          step += 1;
-          const file = files[at]!;
-          last = file;
-          if (o.excluded?.(file)) continue;
+          // A break, when one is due: in place of the next entry, which stays
+          // next. Not at the very start, and never inside an entry.
+          let breakFile: string | null = null;
+          if (o.breaks && !first && offset - lastBreak >= o.breaks.everySeconds) {
+            lastBreak = offset;
+            breakFile = await o.breaks.next().catch(() => null);
+            if (signal.aborted) return;
+          }
+          const isBreak = breakFile !== null;
+          const at = isBreak ? -1 : order[step]!;
+          if (!isBreak) step += 1;
+          const file = isBreak ? breakFile! : files[at]!;
+          if (!isBreak) last = file;
+          if (!isBreak && o.excluded?.(file)) continue;
           const position = first && step - 1 === o.at ? o.position : 0;
           first = false;
           let reached = 0;
@@ -200,13 +216,20 @@ export class PlaylistInputStream {
               abort();
               await closed;
             }
-            failuresInARow = 0;
-            played += 1;
+            if (!isBreak) {
+              failuresInARow = 0;
+              played += 1;
+            }
             // Match the frame grid used above so rounding cannot accumulate a
             // backwards timestamp over hundreds of short files.
             const length = skipped ? Math.min(duration, reached) : duration;
             offset += o.video ? Math.ceil(length * 30) / 30 : length;
+            // The next break is counted from the end of this one, so a spot
+            // longer than the gap cannot follow itself.
+            if (isBreak) lastBreak = offset;
           } catch (error) {
+            // A break that would not play is simply no break.
+            if (isBreak && !signal.aborted) continue;
             if (signal.aborted || !o.passOver) throw error;
             // Passed over, not dialled again: the next entry is what a
             // listener should hear, and a file that will not decode now will

package/src/server.ts

@@ -78,9 +78,12 @@ import { ListenerStore } from "./library-user.ts";
 import { Importer } from "./handoff.ts";
 import { handleHandoffs } from "./handoff-routes.ts";
 import { STATION_PAGE, STATION_PAGE_CSP, STATION_PAGE_HTML } from "./station-page.ts";
+import { GUIDE_CSP, GUIDE_HTML, guideHosts } from "./station-guide.ts";
 import { StationRunner } from "./station-runner.ts";
 import { StationError, StationStore, channelOf, stationOfChannel, type Station } from "./stations.ts";
 import { STATION_CONTROL_LIMIT, StationUsage, limitsFromEnv, type Limits } from "./station-metering.ts";
+import { StationBreaks } from "./station-breaks.ts";
+import { DEFAULT_AUTO, syncAutoStations, type AutoOptions } from "./auto-stations.ts";
 import { CompressionService } from "./compression/service.ts";
 import { handleChannelCompression, handleCompressionApi, handleStaticRelay, type RouteContext } from "./compression/routes.ts";
 import { DEFAULT_SITE as NICHEDB, Enricher, type EnrichKind, FIXTURE_TTL_MS } from "./enrich.ts";
@@ -1717,7 +1720,13 @@ export interface HandlerOptions {
   /** Music handed over from BitTorrented. */
   importer?: Importer;
   /** This server's stations and what keeps them on the air. */
-  stations?: { store: StationStore; runner: StationRunner; usage?: StationUsage; limits?: Limits };
+  stations?: {
+    store: StationStore;
+    runner: StationRunner;
+    usage?: StationUsage;
+    limits?: Limits;
+    auto?: { sync: (input: Record<string, unknown>) => Promise<unknown>; setting: () => unknown };
+  };
   web: string | null;
   /** Branded clients on this same backend, keyed by an explicitly configured host. */
   webSites?: ReadonlyMap<string, import("./web-sites.ts").WebSite>;
@@ -2640,6 +2649,11 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
     // port is open from another device before wondering whether the link is
     // wrong, and it says nothing about the library.
     const eventChannelRequest = Boolean(channelId && await eventForChannel());
+    // The public station guide: at /guide, and at the front of a host named
+    // for it (a Moshpit name such as live.streaming, NIXAMP_GUIDE_HOSTS).
+    const requestHost = String(request.headers["x-forwarded-host"] ?? request.headers.host ?? "").split(",")[0]!.trim().replace(/:\d+$/, "").toLowerCase();
+    const isGuidePage = Boolean(options.stations) && (request.method === "GET" || request.method === "HEAD") &&
+      (path === "/guide" || (path === "/" && guideHosts().has(requestHost)));
     // Whether this request holds only the listen key. A listener may browse
     // and hear the library, but where it lives on this machine is the
     // owner's business: the absolute path names the user account and the disk.
@@ -2652,6 +2666,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       // A station's link is its own key, checked by the station.
       !isStationListenPath(path) &&
       !STATION_PAGE.test(path) &&
+      !isGuidePage &&
       !eventChannelRequest
     ) {
       let scope = scopeOf(keyFrom(request, url), key, listenKey);
@@ -2704,6 +2719,18 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
       return { allowed: false, account: "" };
     };
 
+    if (isGuidePage) {
+      response.writeHead(200, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-cache",
+        "content-security-policy": GUIDE_CSP,
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+      });
+      response.end(request.method === "HEAD" ? undefined : GUIDE_HTML);
+      return;
+    }
+
     // The page a station's link opens. The same bytes for every station: it
     // reads its id and token from its own address.
     if (options.stations && STATION_PAGE.test(path) && (request.method === "GET" || request.method === "HEAD")) {
@@ -2788,6 +2815,7 @@ export function createHandler(engine: Engine, options: HandlerOptions) {
         headers: CORS,
         ...(options.stations.usage ? { usage: options.stations.usage } : {}),
         ...(options.stations.limits ? { limits: options.stations.limits } : {}),
+        ...(options.stations.auto ? { auto: options.stations.auto } : {}),
         throttle: () => {
           const verdict = guard.check(`stations:${control.account || callerOf(request.headers, request.socket.remoteAddress, behindProxy)}`, STATION_CONTROL_LIMIT);
           return verdict.ok ? null : { retryAfter: verdict.retryAfter };
@@ -6663,7 +6691,15 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
   const stationUsage = new StationUsage(StationUsage.fileFor(stateDir(), options.port));
   const stationLimits = limitsFromEnv();
   process.once("exit", () => stationUsage.flush());
+  // Breaks between songs and films: the network's spot, or a house one.
+  const stationBreaks = new StationBreaks({
+    dir: join(stateDir(), "ads"),
+    site: process.env["NIXAMP_SITE"] || "https://nixamp.com",
+    hasSlot: Boolean(process.env["AD_SLOT"]),
+    guard: (url) => refusedDestination(url),
+  });
   stationRunner = new StationRunner({
+    breaks: (video) => stationBreaks.next(video ? "video" : "audio"),
     onRestart: (id) => stationUsage.restarted(id),
     onFailure: (id) => stationUsage.failed(id),
     store: stationStore,
@@ -6679,7 +6715,62 @@ export async function serve(argv: string[], version = "0.1.0"): Promise<void> {
     roots: () => [...new Set([engine.snapshot(false).root || chosen, ...libraryIndex.roots()])].filter((one) => one !== ""),
     log: (line) => console.log(line),
   });
-  const stations = { store: stationStore, runner: stationRunner, usage: stationUsage, limits: stationLimits };
+  // Auto stations: a station per genre, kept in step with the library.
+  const autoSetting = (): AutoOptions | null => {
+    const saved = readConfig().autoStations;
+    if (!saved) return null;
+    const pick = (name: keyof AutoOptions) => (saved[name] === undefined ? DEFAULT_AUTO[name] : saved[name]);
+    return {
+      video: pick("video") !== false,
+      minItems: Number(pick("minItems")) || DEFAULT_AUTO.minItems,
+      minFilms: Number(pick("minFilms")) || DEFAULT_AUTO.minFilms,
+      start: pick("start") !== false,
+      maxVideoRunning: Number(pick("maxVideoRunning")) >= 0 ? Number(pick("maxVideoRunning")) : DEFAULT_AUTO.maxVideoRunning,
+      breaksEvery: Number(pick("breaksEvery")) >= 0 ? Number(pick("breaksEvery")) : DEFAULT_AUTO.breaksEvery,
+    };
+  };
+  let autoRunning: Promise<unknown> | null = null;
+  const runAuto = (settings: AutoOptions): Promise<unknown> => {
+    if (autoRunning) return autoRunning;
+    autoRunning = syncAutoStations({
+      index: libraryIndex,
+      store: stationStore,
+      runner: stationRunner!,
+      owner: options.owner || "",
+      mayStart: () => stationLimits.runningStations === 0 || stationStore.list().filter((one) => one.desired === "running").length < stationLimits.runningStations,
+      filmGenres: async (title) => {
+        const hit = await enricher.lookup(title, "title");
+        const genres = hit?.data?.["genres"];
+        return Array.isArray(genres) ? genres.filter((one): one is string => typeof one === "string") : [];
+      },
+      log: (line) => console.log(line),
+    }, settings).then((report) => {
+      const made = report as { radio: unknown[]; tv: unknown[] };
+      console.log(`  auto stations: ${made.radio.length} radio, ${made.tv.length} TV.`);
+      return report;
+    }).finally(() => { autoRunning = null; });
+    return autoRunning;
+  };
+  libraryIndex.onScanned = () => {
+    const settings = autoSetting();
+    if (settings) void runAuto(settings);
+  };
+  const stationAuto = {
+    setting: () => autoSetting(),
+    sync: async (input: Record<string, unknown>) => {
+      if (input["off"] === true) {
+        writeConfig({ autoStations: undefined });
+        return { off: true };
+      }
+      const settings: AutoOptions = { ...DEFAULT_AUTO, ...(autoSetting() ?? {}) };
+      for (const name of Object.keys(DEFAULT_AUTO) as (keyof AutoOptions)[]) {
+        if (input[name] !== undefined) (settings as unknown as Record<string, unknown>)[name] = input[name];
+      }
+      writeConfig({ autoStations: settings as unknown as Record<string, unknown> });
+      return runAuto(settings);
+    },
+  };
+  const stations = { store: stationStore, runner: stationRunner, usage: stationUsage, limits: stationLimits, auto: stationAuto };
   // Music handed over from BitTorrented, copied into a folder of our own.
   const importer = new Importer(join(stateDir(), `handoffs-${options.port}.json`), {
     index: libraryIndex,

package/src/station-breaks.ts

@@ -0,0 +1,93 @@
+/**
+ * The break: a short spot between songs or films, instead of commercials.
+ *
+ * Asked for once per break, never per listener, and never in the middle of
+ * anything (playlist-input.ts places it between entries). Where it comes
+ * from, in order:
+ *
+ *   1. the ad network, through this server's own AD_SLOT (ads.ts), or
+ *      through nixamp.com's /api/ads/next when this server has none, so a
+ *      self-hosted station carries the same spot the site does and the
+ *      network meters the impression;
+ *   2. a house spot the operator dropped in $XDG_STATE_HOME/nixamp/ads/
+ *      (spot.mp4 for TV, spot.mp3 for radio);
+ *   3. nothing: no break this time, and the music goes on.
+ *
+ * A creative is fetched once per URL into ads/cache and played from disk:
+ * https only, public addresses only, at most 50 MB.
+ */
+import { createHash } from "node:crypto";
+import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { extname, join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { nextAdvert, type Advert } from "./ads.ts";
+
+const MAX_BYTES = 50 * 1024 * 1024;
+
+export interface BreakOptions {
+  dir: string;
+  /** nixamp.com, when this server has no slot of its own. */
+  site: string;
+  hasSlot: boolean;
+  guard: (url: string) => Promise<string>;
+  fetcher?: typeof fetch;
+  /** Injected by tests in place of the network. */
+  ask?: (kind: "audio" | "video") => Promise<Advert>;
+}
+
+export class StationBreaks {
+  constructor(private readonly options: BreakOptions) {}
+
+  private async ask(kind: "audio" | "video"): Promise<Advert> {
+    if (this.options.ask) return this.options.ask(kind);
+    if (this.options.hasSlot) return nextAdvert(kind);
+    const send = this.options.fetcher ?? fetch;
+    try {
+      const answer = await send(`${this.options.site.replace(/\/+$/, "")}/api/ads/next?kind=${kind}`, { signal: AbortSignal.timeout(2_000) });
+      if (!answer.ok) return { url: null };
+      const body = (await answer.json()) as { url?: unknown; kind?: unknown };
+      return typeof body.url === "string" ? { url: body.url, kind: body.kind === "video" ? "video" : "audio" } : { url: null };
+    } catch {
+      return { url: null };
+    }
+  }
+
+  /** A file to play for this break, or null for none. */
+  async next(kind: "audio" | "video"): Promise<string | null> {
+    const advert = await this.ask(kind);
+    if (advert.url) {
+      const cached = await this.cache(advert.url).catch(() => null);
+      if (cached) return cached;
+    }
+    const house = join(this.options.dir, kind === "video" ? "spot.mp4" : "spot.mp3");
+    return existsSync(house) ? house : null;
+  }
+
+  private async cache(url: string): Promise<string | null> {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:") return null;
+    const folder = join(this.options.dir, "cache");
+    const file = join(folder, `${createHash("sha1").update(url).digest("hex")}${extname(parsed.pathname).slice(0, 6) || ".mp4"}`);
+    if (existsSync(file)) return file;
+    if (await this.options.guard(url)) return null;
+    const answer = await (this.options.fetcher ?? fetch)(url, { signal: AbortSignal.timeout(20_000) });
+    if (!answer.ok || !answer.body) return null;
+    if (Number(answer.headers.get("content-length") ?? 0) > MAX_BYTES) return null;
+    mkdirSync(folder, { recursive: true });
+    const part = `${file}.part`;
+    let bytes = 0;
+    const counted = Readable.fromWeb(answer.body as import("node:stream/web").ReadableStream).on("data", (chunk: Buffer) => {
+      bytes += chunk.length;
+      if (bytes > MAX_BYTES) counted.destroy(new Error("too big"));
+    });
+    try {
+      await pipeline(counted, createWriteStream(part));
+      renameSync(part, file);
+      return file;
+    } catch {
+      rmSync(part, { force: true });
+      return null;
+    }
+  }
+}

package/src/station-cli.ts

@@ -177,6 +177,27 @@ export async function station(argv: string[]): Promise<number> {
           return [`page    ${links["page"]}`, `stream  ${links["stream"]}`, `m3u     ${links["m3u"]}`].join("\n");
         });
       }
+      case "auto": {
+        const body: Record<string, unknown> = argv.includes("--off") ? { off: true } : {
+          ...(argv.includes("--no-video") ? { video: false } : {}),
+          ...(argv.includes("--no-start") ? { start: false } : {}),
+          ...(flag(argv, "--min") ? { minItems: Number(flag(argv, "--min")) } : {}),
+          ...(flag(argv, "--films") ? { minFilms: Number(flag(argv, "--films")) } : {}),
+          ...(flag(argv, "--tv") ? { maxVideoRunning: Number(flag(argv, "--tv")) } : {}),
+          ...(flag(argv, "--breaks") ? { breaksEvery: Number(flag(argv, "--breaks")) } : {}),
+        };
+        return show(await call("POST", "/api/v1/stations/auto", body), (answer) => {
+          const report = answer["report"] as { off?: boolean; radio?: Array<Record<string, unknown>>; tv?: Array<Record<string, unknown>>; skipped?: string[] };
+          if (report.off) return "Auto stations are off. The stations already made stay as they are.";
+          const line = (one: Record<string, unknown>, unit: string) => `  ${String(one["genre"]).padEnd(16)} ${String(one["files"] ?? one["films"]).padStart(5)} ${unit}  ${one["running"] ? "on air" : "stopped"}${one["made"] ? "  (new)" : ""}  [${String(one["id"])}]`;
+          return [
+            "Radio:", ...(report.radio ?? []).map((one) => line(one, "files")),
+            "TV:", ...((report.tv ?? []).length ? (report.tv ?? []).map((one) => line(one, "films")) : ["  none (no film genres known yet)"]),
+            ...((report.skipped ?? []).length ? [`Too small for a station: ${(report.skipped ?? []).join(", ")}`] : []),
+            "Every library scan keeps these up to date. They are unlisted: `nixamp station link ID` for a link.",
+          ].join("\n");
+        });
+      }
       case "delete": {
         const station = needId();
         if (!station) return 2;

package/src/station-guide.ts

@@ -0,0 +1,92 @@
+/**
+ * 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: string): string => `'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: Record<string, string | undefined> = process.env): Set<string> {
+  return new Set((env["NIXAMP_GUIDE_HOSTS"] ?? "").split(",").map((one) => one.trim().toLowerCase()).filter(Boolean));
+}