nixamp 0.35.0 → 0.36.1

package/dist/stations.js

@@ -121,6 +121,9 @@ export class StationStore {
                         owner: one.owner ?? "",
                         description: one.description ?? "",
                         idempotencyKey: one.idempotencyKey ?? "",
+                        video: one.video ?? false,
+                        breaksEvery: one.breaksEvery ?? 0,
+                        auto: one.auto ?? "",
                     });
                 }
             }
@@ -169,6 +172,9 @@ export class StationStore {
             desired: "stopped",
             listenToken: newToken(),
             bitrate: this.bitrateFrom(input.bitrate),
+            video: input.video === true,
+            breaksEvery: this.breaksFrom(input.breaksEvery),
+            auto: "",
             rights: null,
             owner,
             failures: {},
@@ -180,6 +186,24 @@ export class StationStore {
         this.save();
         return station;
     }
+    breaksFrom(value) {
+        if (value === undefined || value === null || value === 0)
+            return 0;
+        if (typeof value !== "number" || !Number.isInteger(value) || value < 120 || value > 86_400) {
+            throw new StationError("invalid_breaks", "breaksEvery is seconds between breaks, from 120 to 86400, or 0 for none");
+        }
+        return value;
+    }
+    /** Mark a station as made by auto stations, so a later sync updates it rather than making another. */
+    markAuto(id, key) {
+        const station = this.require(id);
+        station.auto = key;
+        this.save();
+        return station;
+    }
+    byAuto(key) {
+        return [...this.stations.values()].find((one) => one.auto === key);
+    }
     bitrateFrom(value) {
         if (value === undefined)
             return DEFAULT_BITRATE;
@@ -205,6 +229,8 @@ export class StationStore {
             station.repeat = input.repeat !== false;
         if (input.bitrate !== undefined)
             station.bitrate = this.bitrateFrom(input.bitrate);
+        if (input.breaksEvery !== undefined)
+            station.breaksEvery = this.breaksFrom(input.breaksEvery);
         if (items !== null) {
             if (items.length === 0)
                 throw new StationError("empty_station", "a station needs at least one file that plays");

package/package.json

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

package/src/auto-stations.ts

@@ -0,0 +1,180 @@
+/**
+ * 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;
+
+/** Never on a genre TV station, whatever nichedb calls it. */
+const ADULT = /\b(xxx|porn|nsfw|onlyfans|brazzers|blacked|bangbros|milf|hentai|sex|erotic|adult)\b/i;
+
+export function adultTitle(title: string, genres: string[] = []): boolean {
+  return ADULT.test(title) || genres.some((one) => /adult|erotic|porn/i.test(one));
+}
+
+/** 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 title = shown(item).title;
+      const genres = await deps.filmGenres(title).catch(() => []);
+      if (adultTitle(`${title} ${item.rel}`, genres)) continue;
+      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/enrich.ts

@@ -221,6 +221,21 @@ export class Enricher {
    * channel however its name reads. `auto` lets nichedb's parser decide from
    * the name itself, which is right for a file.
    */
+  /**
+   * What is already known about a name, without asking anybody: for work
+   * that runs over a whole library and must not send nichedb a thousand
+   * questions at once.
+   */
+  known(name: string): Enriched | null {
+    const asked = String(name ?? "").trim();
+    if (asked === "") return null;
+    for (const kind of ["auto", "title"] as EnrichKind[]) {
+      const had = this.cache.get(cacheKey(asked, kind, null));
+      if (had?.hit) return had.hit;
+    }
+    return null;
+  }
+
   async lookup(name: string, kind: EnrichKind = "auto", year: number | null = null): Promise<Enriched | null> {
     const asked = String(name ?? "").trim();
     if (asked === "") return null;

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,10 @@ 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>;
+  /** Hosts (e.g. Moshpit names) whose front page is the public station guide. */
+  guideHosts?: string[];
 }
 
 export function configPath(): string {
@@ -39,6 +43,8 @@ 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> } : {}),
+      ...(Array.isArray(record["guideHosts"]) ? { guideHosts: (record["guideHosts"] as unknown[]).filter((one): one is string => typeof one === "string") } : {}),
     };
   } 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,69 @@ 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;
+  let autoLast: { at: number; report: 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,
+      // Only what is already known: a sync over a whole library must not ask
+      // nichedb a question per file (it queued minutes of queries there).
+      filmGenres: async (title) => {
+        const hit = enricher.known(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.`);
+      autoLast = { at: Date.now(), report };
+      return report;
+    }).finally(() => { autoRunning = null; });
+    return autoRunning;
+  };
+  libraryIndex.onScanned = () => {
+    const settings = autoSetting();
+    if (settings) void runAuto(settings);
+  };
+  const stationAuto = {
+    setting: () => ({ ...(autoSetting() ?? { off: true }), running: autoRunning !== null, last: autoLast }),
+    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> });
+      // In the background: a big library takes a while, and an HTTP request
+      // that waits for it times out before it is done.
+      void runAuto(settings);
+      return { started: true, 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;
+    }
+  }
+}