nixamp 0.68.1 → 0.69.0

package/package.json

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

package/src/ai-label.ts

@@ -133,9 +133,9 @@ export interface LabelSettings {
   videos: boolean;
   /** Each album's single (song 1) is filmed with Veo, while the month's Veo budget lasts. */
   veo: boolean;
-  /** How many 8 s Veo shots of the band playing (never the singer) a single is cut from. */
+  /** How many 4 s Veo shots of the band playing (never the singer) a single is cut from. */
   veoShots: number;
-  /** How many 8 s Veo story scenes (a short film from the song's words, nobody singing) a single gets. */
+  /** How many 4 s Veo story scenes (a short film from the song's words, nobody singing) a single gets. */
   storyShots: number;
   /** How many close-ups of the singer a single gets, lip-synced to the song (0: none, the band only). */
   lipsyncShots: number;
@@ -144,6 +144,8 @@ export interface LabelSettings {
    * length (shotPlan) and the three above are not used. Setting any of them turns this off.
    */
   coverSong: boolean;
+  /** With coverSong: what one music video may cost in dollars, the shots planned to fit (shotPlan). */
+  videoUsd: number;
   /** Public, listed and owned, so the genre stations are on the guide. */
   publish: boolean;
   /** Songs made at the same time (ElevenLabs takes several requests at once on a paid plan). */
@@ -402,6 +404,7 @@ export const DEFAULTS: Omit<LabelSettings, "pausedReason"> = {
   storyShots: 4,
   lipsyncShots: 2,
   coverSong: true,
+  videoUsd: 8, // VIDEO_USD
   parallel: 1,
   genreOrder: ["Punk", "Blues", "Country", "Jazz", "Classic Rock", "Metal", "Hip-Hop", "Pop", "R&B"],
 };
@@ -807,16 +810,35 @@ export function renderStoryVideo(ffmpeg: string[], input: { audio: string; image
   return runLow(ffmpeg, [...ffmpeg.slice(1), ...args], 60 * 60_000, "the video failed");
 }
 
+/** What a second of Veo and of lip sync is counted at on nixamp.com (veo-studio.ts), and the shots' lengths. */
+export const VEO_USD_PER_SECOND = 0.15;
+export const LIPSYNC_USD_PER_SECOND = 0.1;
+/** Story and band shots: the cut takes 4 s at a time, so a 4 s shot is used whole at half an 8 s one's price. */
+export const SHOT_SECONDS = 4;
+/** The singer's close-ups stay 8 s: each is lip-synced to 8 s of the song. */
+export const SINGER_SECONDS = 8;
+/** What one music video may cost (Anthony, 2026-10-21: "$5-10"); videoUsd in the settings. */
+export const VIDEO_USD = 8;
+
 /**
- * How many shots a single needs so that its footage covers the whole song with
- * nothing shown twice (8 s a shot, the singer's close-ups whole, the rest cut in
- * 4 s halves): about a quarter the singer, a fifth the band, the rest the story.
+ * The shots a single gets for its budget: two lip-synced close-ups of the singer,
+ * then as many 4 s shots as the rest buys, a third the band and the rest the
+ * story. Footage shorter than the song is cut in turn and shown again.
+ * $8 with a singer: 2 close-ups ($4.00 with their sync) and 6 shots ($3.60).
  */
-export function shotPlan(seconds: number, singing: boolean): { story: number; band: number; singer: number } {
-  const total = Math.ceil(Math.max(30, seconds) / 8) + 1;
-  const singer = singing ? Math.max(2, Math.round(total / 4)) : 0;
-  const band = Math.max(2, Math.round(total / 5));
-  return { story: Math.max(2, total - singer - band), band, singer };
+export function shotPlan(_seconds: number, singing: boolean, usd = VIDEO_USD): { story: number; band: number; singer: number } {
+  const closeUp = SINGER_SECONDS * (VEO_USD_PER_SECOND + LIPSYNC_USD_PER_SECOND), shot = SHOT_SECONDS * VEO_USD_PER_SECOND;
+  // Two close-ups when they leave room for at least two shots; one when the budget is tight.
+  const singer = !singing ? 0 : usd >= 2 * closeUp + 2 * shot ? 2 : 1;
+  const left = usd - singer * SINGER_SECONDS * (VEO_USD_PER_SECOND + LIPSYNC_USD_PER_SECOND);
+  const shots = Math.max(2, Math.floor(left / (SHOT_SECONDS * VEO_USD_PER_SECOND) + 1e-9));
+  const band = Math.max(1, Math.round(shots / 3));
+  return { story: Math.max(1, shots - band), band, singer };
+}
+
+/** What a plan costs on nixamp.com, in dollars. */
+export function planUsd(plan: { story: number; band: number; singer: number }): number {
+  return (plan.story + plan.band) * SHOT_SECONDS * VEO_USD_PER_SECOND + plan.singer * SINGER_SECONDS * (VEO_USD_PER_SECOND + LIPSYNC_USD_PER_SECOND);
 }
 
 /**
@@ -1201,6 +1223,8 @@ export class AiLabel {
     // Counts given by hand mean those counts; coverSong says otherwise only when given too.
     if (shots !== undefined || story !== undefined || close !== undefined) this.settings.coverSong = false;
     if (input["coverSong"] !== undefined) this.settings.coverSong = input["coverSong"] === true;
+    const usd = Number(input["videoUsd"]);
+    if (input["videoUsd"] !== undefined && Number.isFinite(usd)) this.settings.videoUsd = Math.min(40, Math.max(2, usd));
     const perDay = whole("albumsPerDay", 0, 24);
     if (perDay !== undefined) this.settings.albumsPerDay = perDay;
     if (input["newArtistChance"] !== undefined) {
@@ -1448,7 +1472,7 @@ export class AiLabel {
     // Paid-for shots live beside the album until the video is cut, so nothing filmed is filmed twice.
     const shots = join(_album.folder, `.veo-${song.n}`);
     const plan = this.settings.coverSong
-      ? shotPlan(seconds, Boolean(this.deps.lipsync))
+      ? shotPlan(seconds, Boolean(this.deps.lipsync), this.settings.videoUsd ?? VIDEO_USD)
       : { story: this.settings.storyShots, band: this.settings.veoShots, singer: this.settings.lipsyncShots };
     const { band: clips, singer } = await this.filmShots(artist, _album, song, shots, scenes, plan);
     const wanted = plan.band + plan.story;
@@ -1458,7 +1482,8 @@ export class AiLabel {
     if (singing && singer.length === 0) throw new Error("the singer's close-ups are not filmed yet");
     const pinned = await this.syncCloseUps(song, singer, seconds, shots);
     await (this.deps.filmedVideo ?? ((input) => renderFilmedVideo(this.deps.ffmpeg, input)))({ audio: song.file, clips, seconds, artist: artist.name, title: song.title, out, ...(pinned.length ? { pinned } : {}) });
-    rmSync(shots, { recursive: true, force: true });
+    // Paid shots are kept until the video is whole (every close-up synced): a re-cut films only what is missing.
+    if (!singing || pinned.length >= plan.singer) rmSync(shots, { recursive: true, force: true });
     return { version: FILMED, ...(singing ? { singer: pinned.length ? "synced" as const : "unsynced" as const } : {}) };
   }
 
@@ -1563,20 +1588,20 @@ export class AiLabel {
     // the portraits: they would pull the whole band into every scene.
     // The singer first: a day's few Veo requests go to what the video is for, then the story and the band.
     const plan = [
-      ...(this.deps.lipsync ? veoPrompts(artist, song, singers, counts.singer, "singer").map((prompt, i) => ({ prompt, file: join(keep, `singer-${i}.mp4`), into: singer, refs: singerRefs })) : []),
-      ...storyFiles.map((file, i) => ({ prompt: storyPrompts[i] ?? "", file, into: story, refs: [] as Buffer[] })),
-      ...veoPrompts(artist, song, players, counts.band).map((prompt, i) => ({ prompt, file: join(keep, `shot-${i}.mp4`), into: band, refs: playerRefs })),
+      ...(this.deps.lipsync ? veoPrompts(artist, song, singers, counts.singer, "singer").map((prompt, i) => ({ prompt, file: join(keep, `singer-${i}.mp4`), into: singer, refs: singerRefs, seconds: SINGER_SECONDS })) : []),
+      ...storyFiles.map((file, i) => ({ prompt: storyPrompts[i] ?? "", file, into: story, refs: [] as Buffer[], seconds: SHOT_SECONDS })),
+      ...veoPrompts(artist, song, players, counts.band).map((prompt, i) => ({ prompt, file: join(keep, `shot-${i}.mp4`), into: band, refs: playerRefs, seconds: SHOT_SECONDS })),
     ];
-    for (const [i, { prompt, file, into, refs }] of plan.entries()) {
+    for (const [i, { prompt, file, into, refs, seconds }] of plan.entries()) {
       try {
-        if (statSync(file).size > 10_000) { into.push({ path: file, seconds: 8 }); continue; }
+        if (statSync(file).size > 10_000) { into.push({ path: file, seconds }); continue; }
       } catch { /* not filmed yet */ }
       if (!prompt) continue;
       try {
         // nixamp.com briefly away (a deploy: 502/503) or the network: twice more, a minute apart.
         let bytes: Buffer | null = null;
         for (let attempt = 0; ; attempt++) {
-          try { bytes = await veo({ prompt, seconds: 8, references: refs }); break; } catch (error) {
+          try { bytes = await veo({ prompt, seconds, references: refs }); break; } catch (error) {
             if (attempt >= 2 || error instanceof VeoUnavailable || !TRANSIENT.test((error as Error).message)) throw error;
             await new Promise((done) => setTimeout(done, this.deps.retryMs ?? 60_000));
           }
@@ -1584,7 +1609,7 @@ export class AiLabel {
         const partial = `${file}.part`;
         writeFileSync(partial, bytes!);
         renameSync(partial, file);
-        into.push({ path: file, seconds: 8 });
+        into.push({ path: file, seconds });
       } catch (error) {
         if (error instanceof VeoUnavailable) {
           this.veoSpentIn = new Date(this.now()).toISOString().slice(0, 7);

package/src/main.ts

@@ -10,6 +10,7 @@ import { t as uiMessage, i18n, terminalUiLanguage, uiLanguage } from "./i18n.ts"
 import { USAGE as STATION_USAGE } from "./station-usage.ts";
 import { LIBRARY_COMMANDS, LIBRARY_USAGE } from "./library-usage.ts";
 import { MUSIC_USAGE } from "./music-cli.ts";
+import { SCHOOL_USAGE } from "./school-cli.ts";
 import { createApp, themes, type BrailleCanvas, type Container, type KeyEvent, type Theme } from "@profullstack/hqtui";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
@@ -237,6 +238,7 @@ keeps serving its browser remote. One per user.
   nixamp admin    who is connected, and re-stream to them
   nixamp station  make a folder into a station others can join (see: nixamp station help)
   nixamp music    the AI label's songs as files: catalog, buy (10¢, $1, $2), what you bought (nixamp music help)
+  nixamp school   classes on backtoschool.help: teach a station live, check, prune (nixamp school help)
 
 From inside the player, d hands the music to a daemon without stopping it.
 `,
@@ -402,6 +404,7 @@ export function helpFor(topic: string | undefined): string {
   if (topic === "station" || topic === "stations") return STATION_USAGE;
   if (topic === "library") return LIBRARY_USAGE;
   if (topic === "music") return MUSIC_USAGE;
+  if (topic === "school") return SCHOOL_USAGE;
   return (topic ? TOPICS[topic] : undefined) ?? HELP;
 }
 
@@ -566,6 +569,11 @@ export async function main(): Promise<void> {
     process.exitCode = await music(rest);
     return;
   }
+  if (first === "school" || first === "class" || first === "classes") {
+    const { school } = await import("./school-cli.ts");
+    process.exitCode = await school(rest);
+    return;
+  }
   if (first === "station" || first === "stations") {
     const { station } = await import("./station-cli.ts");
     process.exitCode = await station(rest);

package/src/mcp.ts

@@ -33,6 +33,7 @@ import { personaLines, readPersona, readVoices, writePersona } from "./profile.t
 import { STATION_TOOLS, callStationTool, isStationTool, type StationToolOptions } from "./station-mcp.ts";
 import { PUBLIC_TOOLS, callPublicTool, isPublicTool, type PublicToolOptions } from "./directory-mcp.ts";
 import { LIBRARY_TOOLS, callLibraryTool, isLibraryTool } from "./library-mcp.ts";
+import { SCHOOL_TOOLS, callSchoolTool, isSchoolTool } from "./school-mcp.ts";
 
 export const PROTOCOL_VERSION = "2025-06-18";
 
@@ -271,6 +272,7 @@ export const TOOLS: ToolDefinition[] = [
   ...STATION_TOOLS,
   ...(PUBLIC_TOOLS as unknown as ToolDefinition[]),
   ...LIBRARY_TOOLS,
+  ...SCHOOL_TOOLS,
 ];
 
 interface TrollboxLine {
@@ -303,6 +305,8 @@ export interface McpOptions {
   /** How a file is described for its record; the tests hand in a fake. */
   describe?: (path: string) => Promise<Described>;
   say?: (line: string) => void;
+  /** Where the class tools go; backtoschool.help (or NIXAMP_SCHOOL_URL) otherwise. */
+  school?: string;
 }
 
 /** A kept transcript, as a tool answers it. */
@@ -365,6 +369,14 @@ export async function callTool(name: string, args: Record<string, unknown>, opti
       return failed((error as Error).message);
     }
   }
+  // backtoschool.help classes: the same token, sent to the school's host.
+  if (isSchoolTool(name)) {
+    return callSchoolTool(name, args, {
+      ...(options.fetcher ? { fetcher: options.fetcher } : {}),
+      ...(options.session !== undefined ? { token: options.session?.token ?? null } : {}),
+      ...(options.school ? { site: options.school } : {}),
+    });
+  }
   // Stations first: on this machine they need the daemon, not a sign-in.
   if (isStationTool(name) || isLibraryTool(name)) {
     const local = { ...(options.fetcher ? { fetcher: options.fetcher } : {}), ...(options.session !== undefined ? { session: options.session } : {}), ...(options.stations ?? {}) };
@@ -653,9 +665,9 @@ export async function handleMessage(message: Request, options: McpOptions = {}):
     return reply({
       protocolVersion: PROTOCOL_VERSION,
       capabilities: { tools: { listChanged: false } },
-      serverInfo: { name: "nixamp", title: "nixamp: stations, watch parties, rooms and transcripts", version: "2" },
+      serverInfo: { name: "nixamp", title: "nixamp: stations, classes, watch parties, rooms and transcripts", version: "2" },
       instructions:
-        "Watch parties on nixamp: a party lives on the site hosting the film and is bridged here as a room every nixamp client can join; codes are the ones that site shows, positions are seconds into the film. Rooms: say and read trollbox lines, hear a recording. Transcripts: a file, a link or a live is written down once by nixamp.com's own ear and kept under what it is; ask for it in another language and it is translated once and kept too.",
+        "Watch parties on nixamp: a party lives on the site hosting the film and is bridged here as a room every nixamp client can join; codes are the ones that site shows, positions are seconds into the film. Rooms: say and read trollbox lines, hear a recording. Classes on backtoschool.help: classes_list and class_get for anybody; class_teach puts a station link on the air as a class in one call, classes_check finds live classes whose broadcast stopped playing. Transcripts: a file, a link or a live is written down once by nixamp.com's own ear and kept under what it is; ask for it in another language and it is translated once and kept too.",
     });
   }
   // Notifications carry no id and are answered with silence, which is what

package/src/school-cli.ts

@@ -0,0 +1,131 @@
+/**
+ * `nixamp school`: classes on backtoschool.help from the terminal.
+ *
+ * A class is a live event on nixamp's accounts, so `nixamp login` is the
+ * sign-in here too. `teach` is the short path: a station link in, a class on
+ * the air out. `check` and `prune` exist because a class stays live after
+ * its broadcast is gone, and the page then shows a player that never plays.
+ */
+import {
+  broadcastHealth, checkClasses, classUrl, createClass, deleteClass, getClass, listClasses, moveClass, teach, updateClass,
+  type SchoolClass,
+} from "./school-client.ts";
+
+export const SCHOOL_USAGE = `nixamp school: classes on backtoschool.help (sign in with \`nixamp login\`)
+
+  nixamp school [list] [--status live|scheduled|draft|ended] [--mine]
+  nixamp school show SLUG                 one class, and whether its broadcast plays
+  nixamp school teach LINK --title T [--description D] [--topic T] [--unlisted|--private]
+                                          make a class of a broadcast and start it now
+  nixamp school create --title T [LINK] [--starts 2026-11-01T17:00:00Z] [--description D] [--topic T]
+  nixamp school update SLUG [--title T] [--description D] [--topic T] [--link URL] [--public|--unlisted|--private]
+  nixamp school start SLUG
+  nixamp school end SLUG
+  nixamp school delete SLUG
+  nixamp school check                     your live classes, and which ones no longer play
+  nixamp school prune [--end|--delete]    end or delete the ones that no longer play (prints them without a flag)
+
+LINK is what plays: a station link (\`nixamp station show ID\`), a nixamp.com share link, a
+Pairux room, or an https .m3u8/.mp4/.mp3. SLUG is the class's slug or its /live/ link.
+  --json   machine-readable      NIXAMP_SCHOOL_URL   another site (backtoschool.help by default)
+`;
+
+function flag(argv: string[], name: string): string | undefined {
+  const at = argv.indexOf(name);
+  return at === -1 ? undefined : argv[at + 1];
+}
+
+/** The first argument after the command that is not a flag or a flag's value. */
+function positional(argv: string[]): string | undefined {
+  const valued = new Set(["--title", "--description", "--topic", "--starts", "--link", "--status"]);
+  for (let at = 1; at < argv.length; at += 1) {
+    const one = argv[at]!;
+    if (valued.has(one)) { at += 1; continue; }
+    if (!one.startsWith("--")) return one;
+  }
+  return undefined;
+}
+
+function fields(argv: string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, key] of [["--title", "title"], ["--description", "description"], ["--topic", "topic"], ["--starts", "startsAt"], ["--link", "broadcastUrl"]] as const) {
+    const value = flag(argv, name);
+    if (value !== undefined) out[key] = value;
+  }
+  for (const visibility of ["public", "unlisted", "private"]) if (argv.includes(`--${visibility}`)) out["visibility"] = visibility;
+  return out;
+}
+
+function print(item: SchoolClass): void {
+  console.log(`${item.status.padEnd(9)} ${item.title}\n          ${classUrl(item)}${item.broadcastUrl ? `\n          plays ${item.broadcastUrl}` : ""}`);
+}
+
+export async function school(argv: string[]): Promise<number> {
+  const [sub = "list"] = argv;
+  const json = argv.includes("--json");
+  const slug = positional(argv);
+  const out = (value: unknown, human: () => void): void => { if (json) console.log(JSON.stringify(value, null, 2)); else human(); };
+  try {
+    if (sub === "help" || argv.includes("--help")) {
+      console.log(SCHOOL_USAGE);
+      return 0;
+    }
+    if (sub === "list") {
+      const status = flag(argv, "--status");
+      const items = await listClasses({ ...(status ? { status } : {}), mine: argv.includes("--mine") });
+      out(items, () => { if (items.length === 0) console.log("No classes match."); for (const one of items) print(one); });
+      return 0;
+    }
+    if (sub === "check" || sub === "prune") {
+      const checked = await checkClasses();
+      const broken = checked.filter((one) => one.health.ok === false);
+      const act = sub === "prune" ? (argv.includes("--delete") ? "delete" : argv.includes("--end") ? "end" : "") : "";
+      for (const { item } of act ? broken : []) {
+        if (act === "delete") await deleteClass(item.id);
+        else await moveClass(item.id, "end");
+      }
+      out(checked.map(({ item, health }) => ({ slug: item.slug, ok: health.ok, reason: health.reason, ...(act && health.ok === false ? { done: act } : {}) })), () => {
+        if (checked.length === 0) console.log("You have no live classes.");
+        for (const { item, health } of checked) console.log(`${health.ok === true ? "plays " : health.ok === false ? "BROKEN" : "  ?   "}  ${item.slug}  (${health.reason})`);
+        if (sub === "prune" && broken.length > 0) console.log(act ? `\n${act === "delete" ? "Deleted" : "Ended"} ${broken.length}.` : `\n${broken.length} no longer play. --end or --delete them.`);
+      });
+      return 0;
+    }
+    if (sub === "teach" || sub === "create") {
+      const input = fields(argv);
+      if (slug) input["broadcastUrl"] = slug;
+      if (!input["title"]) { console.error(`nixamp school ${sub} needs --title`); return 2; }
+      if (sub === "teach" && !input["broadcastUrl"]) { console.error("nixamp school teach needs the LINK that plays"); return 2; }
+      const item = sub === "teach" ? await teach(input) : await createClass(input);
+      out(item, () => { print(item); if (sub === "create") console.log(`\nnixamp school start ${item.slug} puts it on the air.`); });
+      return 0;
+    }
+    if (!slug) { console.error(`nixamp school ${sub} needs a class (its slug or /live/ link)\n\n${SCHOOL_USAGE}`); return 2; }
+    if (sub === "show") {
+      const item = await getClass(slug);
+      const health = await broadcastHealth(item.broadcastUrl);
+      out({ ...item, broadcast: health }, () => { print(item); console.log(`          broadcast: ${health.ok === true ? "playing" : health.ok === false ? "NOT playing" : "unknown"} (${health.reason})`); });
+      return 0;
+    }
+    if (sub === "update") {
+      const item = await updateClass(slug, fields(argv));
+      out(item, () => print(item));
+      return 0;
+    }
+    if (sub === "start" || sub === "end") {
+      const item = await moveClass(slug, sub);
+      out(item, () => print(item));
+      return 0;
+    }
+    if (sub === "delete" || sub === "rm") {
+      await deleteClass(slug);
+      out({ ok: true, slug }, () => console.log(`Deleted ${slug}.`));
+      return 0;
+    }
+    console.error(`nixamp school: no command "${sub}".\n\n${SCHOOL_USAGE}`);
+    return 2;
+  } catch (error) {
+    console.error(`nixamp school: ${(error as Error).message}`);
+    return 1;
+  }
+}

package/src/school-client.ts

@@ -0,0 +1,180 @@
+/**
+ * backtoschool.help as a client: its classes are nixamp's live events, served
+ * by the same process on another host, so one nixamp token signs in to both.
+ *
+ * The CLI (school-cli.ts) and the MCP tools (school-mcp.ts) are both this
+ * file; neither talks HTTP itself.
+ *
+ * `broadcastHealth` is the reason this exists as much as the CRUD: a class
+ * stays "live" until somebody ends it, long after the channel it points at
+ * was stopped, and the page then shows a player that never plays. It asks the
+ * broadcast itself, with only what the public link already carries.
+ */
+import { readSession } from "./session.ts";
+
+export const SCHOOL_SITE = "https://backtoschool.help";
+
+type Fetcher = typeof fetch;
+
+export interface SchoolOptions {
+  /** backtoschool.help unless NIXAMP_SCHOOL_URL says otherwise; the tests hand in a local server. */
+  site?: string;
+  /** The session on disk (or NIXAMP_TOKEN) unless given; null means signed out. */
+  token?: string | null;
+  fetcher?: Fetcher;
+}
+
+export interface SchoolClass {
+  id: string;
+  slug: string;
+  title: string;
+  status: string;
+  visibility: string;
+  kind: string;
+  version: number;
+  ownerId: string;
+  broadcastUrl?: string | null;
+  description?: string;
+  topic?: string;
+  hostName?: string;
+  startsAt?: string | null;
+  [key: string]: unknown;
+}
+
+export class SchoolError extends Error {
+  constructor(message: string, readonly status = 0) {
+    super(message);
+  }
+}
+
+export function schoolSite(options: SchoolOptions = {}): string {
+  return (options.site ?? process.env["NIXAMP_SCHOOL_URL"] ?? SCHOOL_SITE).replace(/\/+$/, "");
+}
+
+export function classUrl(item: Pick<SchoolClass, "slug">, options: SchoolOptions = {}): string {
+  return `${schoolSite(options)}/live/${item.slug}`;
+}
+
+function tokenOf(options: SchoolOptions): string | null {
+  if (options.token !== undefined) return options.token;
+  return readSession()?.token ?? null;
+}
+
+async function call(path: string, init: { method?: string; body?: unknown; auth?: boolean } = {}, options: SchoolOptions = {}): Promise<Record<string, unknown>> {
+  const token = tokenOf(options);
+  if (init.auth && !token) throw new SchoolError("Not signed in. Run `nixamp login`, or set NIXAMP_TOKEN.", 401);
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (token) headers["authorization"] = `Bearer ${token}`;
+  if (init.body !== undefined) headers["content-type"] = "application/json";
+  const response = await (options.fetcher ?? fetch)(`${schoolSite(options)}${path}`, {
+    method: init.method ?? "GET",
+    headers,
+    ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+  });
+  const body = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+  if (!response.ok) throw new SchoolError(String(body["error"] ?? `backtoschool.help answered ${response.status}`), response.status);
+  return body;
+}
+
+const eventOf = (body: Record<string, unknown>): SchoolClass => (body["event"] ?? body) as SchoolClass;
+const ref = (value: string): string => encodeURIComponent(value.replace(/^.*\/live\//, "").replace(/[?#].*$/, ""));
+
+export async function listClasses(query: { status?: string; kind?: string; mine?: boolean; limit?: number } = {}, options: SchoolOptions = {}): Promise<SchoolClass[]> {
+  const params = new URLSearchParams();
+  if (query.status) params.set("status", query.status);
+  if (query.kind) params.set("kind", query.kind);
+  if (query.mine) params.set("mine", "true");
+  params.set("limit", String(query.limit ?? 60));
+  const body = await call(`/api/v1/events?${params}`, { auth: query.mine === true }, options);
+  return (body["events"] as SchoolClass[]) ?? [];
+}
+
+/** A class by its slug, id, or the /live/<slug> link. */
+export async function getClass(slug: string, options: SchoolOptions = {}): Promise<SchoolClass> {
+  return eventOf(await call(`/api/v1/events/${ref(slug)}`, {}, options));
+}
+
+export async function createClass(input: Record<string, unknown>, options: SchoolOptions = {}): Promise<SchoolClass> {
+  return eventOf(await call("/api/v1/events", { method: "POST", body: { kind: "class", visibility: "public", ...input }, auth: true }, options));
+}
+
+export async function updateClass(slug: string, patch: Record<string, unknown>, options: SchoolOptions = {}): Promise<SchoolClass> {
+  const current = await getClass(slug, options);
+  return eventOf(await call(`/api/v1/events/${ref(current.id)}`, { method: "PATCH", body: { ...patch, version: current.version }, auth: true }, options));
+}
+
+/** start, end, doors, encore, cancel or archive. Each wants the version it saw, so it is read first. */
+export async function moveClass(slug: string, action: "start" | "end" | "doors" | "encore" | "cancel" | "archive", options: SchoolOptions = {}): Promise<SchoolClass> {
+  const current = await getClass(slug, options);
+  return eventOf(await call(`/api/v1/events/${ref(current.id)}/${action}`, { method: "POST", body: { version: current.version }, auth: true }, options));
+}
+
+export async function deleteClass(slug: string, options: SchoolOptions = {}): Promise<void> {
+  await call(`/api/v1/events/${ref(slug)}`, { method: "DELETE", auth: true }, options);
+}
+
+/** Make a class of a broadcast and put it on the air in one go. */
+export async function teach(input: Record<string, unknown>, options: SchoolOptions = {}): Promise<SchoolClass> {
+  const made = await createClass(input, options);
+  return moveClass(made.slug, "start", options);
+}
+
+export interface Health {
+  ok: boolean | null;
+  reason: string;
+}
+
+/**
+ * Does this broadcast play? true and false are answers; null is "cannot tell
+ * from here" (a Pairux room), which a prune must leave alone.
+ */
+export async function broadcastHealth(link: string | null | undefined, fetcher: Fetcher = fetch, timeoutMs = 8000): Promise<Health> {
+  if (!link) return { ok: false, reason: "no broadcast link" };
+  let url: URL;
+  try {
+    url = new URL(link);
+  } catch {
+    return { ok: false, reason: "not a link" };
+  }
+  const get = (target: string, headers: Record<string, string> = {}): Promise<Response> =>
+    fetcher(target, { headers, signal: AbortSignal.timeout(timeoutMs) });
+  try {
+    // A station page: its own token opens its state.
+    const station = /^\/station\/([a-z0-9]{10})\/?$/.exec(url.pathname)?.[1];
+    if (station && url.hostname.endsWith(".nixamp.com")) {
+      const response = await get(`${url.origin}/api/v1/stations/${station}/state?t=${encodeURIComponent(url.searchParams.get("t") ?? "")}`);
+      if (!response.ok) return { ok: false, reason: `station ${station} answered ${response.status}` };
+      const state = (await response.json()) as { state?: string };
+      return state.state === "live" ? { ok: true, reason: `station ${station} is live` } : { ok: false, reason: `station ${station} is ${state.state ?? "not live"}` };
+    }
+    // nixamp.com/?url=<server>/view/<listen key>&play=channel:<id>: the listen key reads the server's channels.
+    if ((url.hostname === "nixamp.com" || url.hostname === "www.nixamp.com") && url.searchParams.get("url")) {
+      const server = new URL(url.searchParams.get("url")!);
+      const key = /\/view\/([^/?#]+)/.exec(server.pathname)?.[1] ?? "";
+      const play = url.searchParams.get("play") ?? "live";
+      const response = await get(`${server.origin}/api/streams?k=${encodeURIComponent(key)}`);
+      if (!response.ok) return { ok: false, reason: `${server.host} answered ${response.status}` };
+      const streams = (await response.json()) as { server?: { live?: boolean }; channels?: Array<{ id: string }> };
+      if (play.startsWith("channel:")) {
+        const id = play.slice("channel:".length);
+        return (streams.channels ?? []).some((one) => one.id === id)
+          ? { ok: true, reason: `channel ${id} is on ${server.hostname}` }
+          : { ok: false, reason: `channel ${id} is no longer on ${server.hostname}` };
+      }
+      if (play === "live") return streams.server?.live ? { ok: true, reason: `${server.hostname} is live` } : { ok: false, reason: `${server.hostname} is not live` };
+      return { ok: true, reason: `${server.hostname} is up` };
+    }
+    if (url.hostname === "pairux.com" || url.hostname === "www.pairux.com") return { ok: null, reason: "a Pairux room; cannot tell from here" };
+    // Direct media: one byte is enough to know it is there.
+    const response = await get(url.href, { range: "bytes=0-0" });
+    return response.ok ? { ok: true, reason: `${url.hostname} serves it` } : { ok: false, reason: `${url.hostname} answered ${response.status}` };
+  } catch (error) {
+    return { ok: false, reason: `unreachable: ${(error as Error).message}` };
+  }
+}
+
+/** Your live classes, each with whether its broadcast plays. */
+export async function checkClasses(options: SchoolOptions = {}, status = "live"): Promise<Array<{ item: SchoolClass; health: Health }>> {
+  const items = await listClasses({ mine: true, status }, options);
+  return Promise.all(items.map(async (item) => ({ item, health: await broadcastHealth(item.broadcastUrl, options.fetcher ?? fetch) })));
+}