nixamp 0.68.2 → 0.70.0

package/dist/ai-label.d.ts

@@ -170,6 +170,8 @@ export interface TimedWord {
 }
 /** ElevenLabs forced alignment: the song and its words in, each word's time out. */
 export declare function elevenLabsAligner(key: string, fetcher?: typeof fetch): (audio: string, text: string) => Promise<TimedWord[]>;
+/** ElevenLabs voice isolation: a few seconds of the song in, the voice alone out (what a lip sync follows best). */
+export declare function elevenLabsIsolator(key: string, fetcher?: typeof fetch): (audio: Buffer) => Promise<Buffer>;
 /** The sung lines of a song's words: section tags ([Chorus]) and blank lines are not sung. */
 export declare function sungLines(lyrics: string): string[];
 /**
@@ -181,8 +183,13 @@ export declare function syncLines(lyrics: string, timed: TimedWord[]): SyncedLin
 export declare function writeStoryboard(artist: Pick<LabelArtist, "name" | "genre" | "sound"> & {
     cast?: string;
 }, album: Pick<LabelAlbum, "title" | "concept">, song: Pick<LabelSong, "title" | "style" | "lyrics">, scenes: number, ask?: typeof askJson): Promise<string[]>;
-/** A single's story scenes for Veo: a short film from its words, nobody singing, people by look not name. */
-export declare function writeVeoStory(artist: Pick<LabelArtist, "genre" | "sound">, members: Array<Pick<Member, "role" | "look">>, album: Pick<LabelAlbum, "title" | "concept">, song: Pick<LabelSong, "title" | "style" | "lyrics">, scenes: number, ask?: typeof askJson): Promise<string[]>;
+/** A story scene for Veo: the prompt and the roles of the band members in it (their portraits go with it). */
+export interface StoryScene {
+    prompt: string;
+    cast: string[];
+}
+/** A single's story scenes for Veo: a short film from its words starring the band as they look, nobody singing. */
+export declare function writeVeoStory(artist: Pick<LabelArtist, "genre" | "sound">, members: Array<Pick<Member, "role" | "look">>, album: Pick<LabelAlbum, "title" | "concept">, song: Pick<LabelSong, "title" | "style" | "lyrics">, scenes: number, ask?: typeof askJson): Promise<StoryScene[]>;
 /** Thrown by a Veo dependency when this month's budget is spent: no more shots until next month. */
 export declare class VeoUnavailable extends Error {
 }
@@ -225,7 +232,7 @@ export declare const VIDEO_USD = 8;
  * 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 declare function shotPlan(_seconds: number, singing: boolean, usd?: number): {
+export declare function shotPlan(seconds: number, singing: boolean, usd?: number): {
     story: number;
     band: number;
     singer: number;
@@ -249,9 +256,10 @@ export declare function closeUpTimes(seconds: number, lines: Array<{
  * The version of a video cut from Veo footage: story scenes and the band playing with
  * nobody singing, the singer only in close-ups lip-synced to the song. Anything older
  * is not shown: a slideshow, 4 (singers out of sync) or 5 (all stage, the singer at
- * the mic in the wide shots).
+ * the mic in the wide shots). 6 and 7 (strangers in the story scenes, footage looped)
+ * stay up until filmed again.
  */
-export declare const FILMED = 7;
+export declare const FILMED = 8;
 /** The oldest version still shown while its single waits to be filmed again: 6, story and band with a close-up, but footage looped and little singing. */
 export declare const SHOWN = 6;
 /** Google's answer when the project's daily Veo requests are used up (HTTP 429). */
@@ -341,6 +349,8 @@ export interface AiLabelDeps {
             seconds: number;
         }>;
     }) => Promise<void>;
+    /** The voice alone from a few seconds of a song (ElevenLabs by default when its key is set); null for none. */
+    isolate?: ((audio: Buffer) => Promise<Buffer>) | null;
     /** A singer's close-up with the mouth redrawn to these seconds of the song (nixamp.com, fal.ai); VeoUnavailable when the month is spent. */
     lipsync?: ((input: {
         video: Buffer;

package/dist/ai-label.js

@@ -441,6 +441,20 @@ export function elevenLabsAligner(key, fetcher = fetch) {
             .filter((one) => one.text && Number.isFinite(one.start) && Number.isFinite(one.end));
     };
 }
+/** ElevenLabs voice isolation: a few seconds of the song in, the voice alone out (what a lip sync follows best). */
+export function elevenLabsIsolator(key, fetcher = fetch) {
+    return async (audio) => {
+        const form = new FormData();
+        form.append("audio", new Blob([new Uint8Array(audio)], { type: "audio/mpeg" }), "lines.mp3");
+        const response = await fetcher("https://api.elevenlabs.io/v1/audio-isolation", { method: "POST", headers: { "xi-api-key": key }, body: form, signal: AbortSignal.timeout(2 * 60_000) });
+        if (!response.ok)
+            throw new Error(`the voice isolation answered HTTP ${response.status}`);
+        const voice = Buffer.from(await response.arrayBuffer());
+        if (voice.length < 1000)
+            throw new Error("the voice isolation answered with no audio");
+        return voice;
+    };
+}
 /** The sung lines of a song's words: section tags ([Chorus]) and blank lines are not sung. */
 export function sungLines(lyrics) {
     return lyrics.split("\n").map((line) => line.trim()).filter((line) => line && !/^\[[^\]]*\]$/.test(line));
@@ -493,32 +507,41 @@ export async function writeStoryboard(artist, album, song, scenes, ask = askJson
     return prompts;
 }
 const VEO_STORY_SYSTEM = [
-    "You write the story scenes of a music video for an original song, as prompts for a video model that films 8-second moving shots.",
-    "Tell the song's story in cinematic scenes away from any stage: characters, places, action, weather, small details. Keep the same main character(s), setting and color palette across scenes so it reads as one short film; vary the shots (wide, tracking, close detail, aerial) and say how the camera moves.",
-    "Describe people by how they look, never by name. Nobody sings, speaks or lip-syncs, and nobody holds a microphone. Each prompt at most 350 characters. No text, letters, logos, real people or real brands.",
-    "Answer as JSON: {\"scenes\": [\"prompt\", ...]}.",
+    "You write the story scenes of a music video for an original song, as prompts for a video model that films short moving shots.",
+    "Tell the song's story in cinematic scenes away from any stage. The main characters are ONLY the band members listed (by role); every scene with a person in it features one to three of them, and each one keeps exactly the look given. Other people may appear only in the background, faces unseen.",
+    "Keep the same settings and color palette across scenes so it reads as one short film; vary the shots (wide, tracking, close detail, aerial) and say how the camera moves. Nobody sings, speaks or lip-syncs, and nobody holds a microphone.",
+    "Describe people by role and look, never by name. Each prompt at most 350 characters. No text, letters, logos, real people or real brands.",
+    "Answer as JSON: {\"scenes\": [{\"prompt\": \"...\", \"cast\": [\"lead vocals\", ...]}, ...]} where cast lists the roles (exactly as given) of the members in that scene, [] for none.",
 ].join(" ");
-/** A single's story scenes for Veo: a short film from its words, nobody singing, people by look not name. */
+/** A single's story scenes for Veo: a short film from its words starring the band as they look, nobody singing. */
 export async function writeVeoStory(artist, members, album, song, scenes, ask = askJson) {
-    const cast = members.slice(0, 4).map((one) => `${one.role}: ${one.look.replace(/\b[A-Z][a-z]+ [A-Z][a-z]+\b/g, "")}`).join("; ");
+    const cast = members.slice(0, 5).map((one) => `${one.role}: ${one.look.replace(/\b[A-Z][a-z]+ [A-Z][a-z]+\b/g, "")}`).join("; ");
     const answer = await ask({
         system: VEO_STORY_SYSTEM,
         prompt: [
             `Song: "${song.title}" (${artist.genre}; ${artist.sound}), from "${album.title}"${album.concept ? `: ${album.concept}` : ""}`,
-            cast ? `The band may appear as characters, described by look: ${cast}` : "",
+            cast ? `The band (the only main characters), by role and look: ${cast}` : "",
             `Mood and arrangement: ${song.style}`,
             song.lyrics ? `Lyrics:\n${song.lyrics.slice(0, 1800)}` : "",
             `Exactly ${scenes} scenes.`,
         ].filter(Boolean).join("\n"),
-        maxTokens: 2500,
-        timeoutMs: 90_000,
+        maxTokens: 4000,
+        timeoutMs: 120_000,
     });
+    const roles = new Set(members.map((one) => one.role.toLowerCase()));
     const list = Array.isArray(answer.value["scenes"]) ? answer.value["scenes"] : [];
-    const prompts = list.map((one) => clean(one, 400)).filter((one) => one.length > 10).slice(0, scenes);
-    if (prompts.length < 1)
+    const out = list.map((one) => {
+        const item = (typeof one === "object" && one ? one : { prompt: one });
+        const who = Array.isArray(item.cast) ? item.cast.map((role) => String(role).toLowerCase().trim()).filter((role) => roles.has(role)) : [];
+        return { prompt: clean(item.prompt, 400), cast: [...new Set(who)].slice(0, 3) };
+    }).filter((one) => one.prompt.length > 10).slice(0, scenes);
+    if (out.length < 1)
         throw new Error("the model wrote no story");
-    return prompts.map((scene) => `Music video for a fictional ${artist.genre} song. ${scene} Mood: ${song.style}`.slice(0, 900)
-        + " Nobody sings, speaks or lip-syncs on camera. Cinematic, 35mm film look. No text, no logos.");
+    return out.map((scene) => ({
+        cast: scene.cast,
+        prompt: `Music video for a fictional ${artist.genre} song. ${scene.prompt} Mood: ${song.style}`.slice(0, 900)
+            + " Nobody sings, speaks or lip-syncs on camera. Cinematic, 35mm film look, high detail. No text, no logos.",
+    }));
 }
 /** Thrown by a Veo dependency when this month's budget is spent: no more shots until next month. */
 export class VeoUnavailable extends Error {
@@ -671,13 +694,17 @@ export const VIDEO_USD = 8;
  * 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, singing, usd = VIDEO_USD) {
+export function shotPlan(seconds, singing, usd = VIDEO_USD) {
     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));
+    const length = Math.max(30, seconds);
+    // About one lip-synced close-up every 30 s of song, as many as leave room for at least two shots.
+    let singer = singing ? Math.max(1, Math.min(6, Math.round(length / 30))) : 0;
+    while (singer > 1 && usd < singer * closeUp + 2 * shot)
+        singer -= 1;
+    // Then shots enough to cover the rest of the song once (nothing shown twice), as far as the money goes.
+    const cover = Math.ceil(Math.max(0, length - singer * SINGER_SECONDS) / SHOT_SECONDS);
+    const shots = Math.max(2, Math.min(cover, Math.floor((usd - singer * closeUp) / shot + 1e-9)));
+    const band = Math.max(1, Math.round(shots / 4));
     return { story: Math.max(1, shots - band), band, singer };
 }
 /** What a plan costs on nixamp.com, in dollars. */
@@ -714,9 +741,10 @@ export function closeUpTimes(seconds, lines, count, length = 8) {
  * The version of a video cut from Veo footage: story scenes and the band playing with
  * nobody singing, the singer only in close-ups lip-synced to the song. Anything older
  * is not shown: a slideshow, 4 (singers out of sync) or 5 (all stage, the singer at
- * the mic in the wide shots).
+ * the mic in the wide shots). 6 and 7 (strangers in the story scenes, footage looped)
+ * stay up until filmed again.
  */
-export const FILMED = 7;
+export const FILMED = 8;
 /** The oldest version still shown while its single waits to be filmed again: 6, story and band with a close-up, but footage looped and little singing. */
 export const SHOWN = 6;
 /** Google's answer when the project's daily Veo requests are used up (HTTP 429). */
@@ -1357,10 +1385,15 @@ export class AiLabel {
                 // The shot made small enough to send (1080p, no sound) and the song's same 8 seconds.
                 await runLow(this.deps.ffmpeg, [...this.deps.ffmpeg.slice(1), "-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-i", singer[i].path, "-an", "-c:v", "libx264", "-preset", "veryfast", "-crf", "21", "-t", "8", shot], 5 * 60_000, "the close-up did not shrink");
                 await runLow(this.deps.ffmpeg, [...this.deps.ffmpeg.slice(1), "-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-ss", at.toFixed(2), "-t", "8", "-i", song.file, "-c:a", "libmp3lame", "-b:a", "192k", audio], 60_000, "the song's seconds did not cut");
+                // The mouth follows the voice alone better than the whole mix; the video keeps the whole mix.
+                let voice = readFileSync(audio);
+                const isolate = this.deps.isolate !== undefined ? this.deps.isolate : (aiKey("ELEVENLABS_API_KEY") ? elevenLabsIsolator(aiKey("ELEVENLABS_API_KEY")) : null);
+                if (isolate)
+                    voice = await isolate(voice).catch((error) => { this.log(`voice isolation for "${song.title}": ${error.message}; the whole mix instead`); return voice; });
                 let bytes = null;
                 for (let attempt = 0;; attempt++) {
                     try {
-                        bytes = await lipsync({ video: readFileSync(shot), audio: readFileSync(audio), seconds: 8 });
+                        bytes = await lipsync({ video: readFileSync(shot), audio: voice, seconds: 8 });
                         break;
                     }
                     catch (error) {
@@ -1410,19 +1443,26 @@ export class AiLabel {
         const voice = (member) => /vocal|sing/i.test(member.role);
         const players = members.filter((member) => !voice(member));
         const singers = members.filter(voice).length ? members.filter(voice) : members.slice(0, 1);
+        const shrunk = new Map();
         const portraits = async (list) => {
             const out = [];
             for (const member of list.slice(0, 3)) {
-                const portrait = join(this.folderOf(artist), "members", `${member.slug}.jpg`);
-                const small = join(dir, `ref-${member.slug}.jpg`);
-                try {
-                    // 512 px is plenty for a face and keeps the request small.
-                    await runLow(this.deps.ffmpeg, [...this.deps.ffmpeg.slice(1), "-hide_banner", "-loglevel", "error", "-y", "-i", portrait, "-vf", "scale=512:-2", "-q:v", "4", small], 60_000, "the portrait did not shrink");
-                    out.push(readFileSync(small));
-                }
-                catch {
-                    // A member without a portrait is described in words only.
+                if (!shrunk.has(member.slug)) {
+                    const portrait = join(this.folderOf(artist), "members", `${member.slug}.jpg`);
+                    const small = join(dir, `ref-${member.slug}.jpg`);
+                    try {
+                        // 768 px keeps a face's detail and the request small.
+                        await runLow(this.deps.ffmpeg, [...this.deps.ffmpeg.slice(1), "-hide_banner", "-loglevel", "error", "-y", "-i", portrait, "-vf", "scale=768:-2", "-q:v", "3", small], 60_000, "the portrait did not shrink");
+                        shrunk.set(member.slug, readFileSync(small));
+                    }
+                    catch {
+                        // A member without a portrait is described in words only.
+                        shrunk.set(member.slug, null);
+                    }
                 }
+                const bytes = shrunk.get(member.slug);
+                if (bytes)
+                    out.push(bytes);
             }
             return out;
         };
@@ -1441,12 +1481,22 @@ export class AiLabel {
                 this.log(`no story for "${song.title}" yet: ${error.message}`);
             }
         }
-        // The singer's close-ups only where they can be lip-synced afterwards. Story scenes go without
-        // the portraits: they would pull the whole band into every scene.
+        // The singer's close-ups only where they can be lip-synced afterwards. Each story scene is filmed
+        // with the portraits of the members in it, and their looks in words, so they are the same people
+        // in every shot; a scene with nobody in it goes without.
+        const byRole = new Map(members.map((member) => [member.role.toLowerCase(), member]));
+        const storyCast = await Promise.all(storyPrompts.map(async (scene) => {
+            const who = scene.cast.map((role) => byRole.get(role)).filter((member) => Boolean(member));
+            const named = who.map((member, i) => `the ${member.role} from reference image ${i + 1} (${member.look.replace(/\b[A-Z][a-z]+ [A-Z][a-z]+\b/g, "")})`).join("; ");
+            return {
+                prompt: who.length ? `${scene.prompt} The people are exactly the ones in the reference images, same faces, hair and clothes: ${named}.` : scene.prompt,
+                refs: await portraits(who),
+            };
+        }));
         // 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, seconds: SINGER_SECONDS })) : []),
-            ...storyFiles.map((file, i) => ({ prompt: storyPrompts[i] ?? "", file, into: story, refs: [], seconds: SHOT_SECONDS })),
+            ...storyFiles.map((file, i) => ({ prompt: storyCast[i]?.prompt ?? "", file, into: story, refs: storyCast[i]?.refs ?? [], 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, seconds }] of plan.entries()) {

package/dist/main.js

@@ -10,6 +10,7 @@ import { t as uiMessage, i18n, terminalUiLanguage, uiLanguage } from "./i18n.js"
 import { USAGE as STATION_USAGE } from "./station-usage.js";
 import { LIBRARY_COMMANDS, LIBRARY_USAGE } from "./library-usage.js";
 import { MUSIC_USAGE } from "./music-cli.js";
+import { SCHOOL_USAGE } from "./school-cli.js";
 import { createApp, themes } from "@profullstack/hqtui";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
@@ -211,6 +212,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.
 `,
@@ -378,6 +380,8 @@ export function helpFor(topic) {
         return LIBRARY_USAGE;
     if (topic === "music")
         return MUSIC_USAGE;
+    if (topic === "school")
+        return SCHOOL_USAGE;
     return (topic ? TOPICS[topic] : undefined) ?? HELP;
 }
 /**
@@ -540,6 +544,11 @@ export async function main() {
         process.exitCode = await music(rest);
         return;
     }
+    if (first === "school" || first === "class" || first === "classes") {
+        const { school } = await import("./school-cli.js");
+        process.exitCode = await school(rest);
+        return;
+    }
     if (first === "station" || first === "stations") {
         const { station } = await import("./station-cli.js");
         process.exitCode = await station(rest);

package/dist/mcp.d.ts

@@ -37,6 +37,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 tool answer, in the shape MCP wants: content blocks, and a flag for failure. */
 export interface ToolResult {

package/dist/mcp.js

@@ -33,6 +33,7 @@ import { personaLines, readPersona, readVoices, writePersona } from "./profile.j
 import { STATION_TOOLS, callStationTool, isStationTool } from "./station-mcp.js";
 import { PUBLIC_TOOLS, callPublicTool, isPublicTool } from "./directory-mcp.js";
 import { LIBRARY_TOOLS, callLibraryTool, isLibraryTool } from "./library-mcp.js";
+import { SCHOOL_TOOLS, callSchoolTool, isSchoolTool } from "./school-mcp.js";
 export const PROTOCOL_VERSION = "2025-06-18";
 const STRING = { type: "string" };
 export const TOOLS = [
@@ -244,6 +245,7 @@ export const TOOLS = [
     ...STATION_TOOLS,
     ...PUBLIC_TOOLS,
     ...LIBRARY_TOOLS,
+    ...SCHOOL_TOOLS,
 ];
 function said(line) {
     return `${line.createdAt}  ${line.handle}: ${line.body}`;
@@ -302,6 +304,14 @@ export async function callTool(name, args, options = {}) {
             return failed(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 ?? {}) };
@@ -612,8 +622,8 @@ export async function handleMessage(message, options = {}) {
         return reply({
             protocolVersion: PROTOCOL_VERSION,
             capabilities: { tools: { listChanged: false } },
-            serverInfo: { name: "nixamp", title: "nixamp: stations, 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.",
+            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. 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/dist/school-cli.d.ts

@@ -0,0 +1,2 @@
+export declare const SCHOOL_USAGE = "nixamp school: classes on backtoschool.help (sign in with `nixamp login`)\n\n  nixamp school [list] [--status live|scheduled|draft|ended] [--mine]\n  nixamp school show SLUG                 one class, and whether its broadcast plays\n  nixamp school teach LINK --title T [--description D] [--topic T] [--unlisted|--private]\n                                          make a class of a broadcast and start it now\n  nixamp school create --title T [LINK] [--starts 2026-11-01T17:00:00Z] [--description D] [--topic T]\n  nixamp school update SLUG [--title T] [--description D] [--topic T] [--link URL] [--public|--unlisted|--private]\n  nixamp school start SLUG\n  nixamp school end SLUG\n  nixamp school delete SLUG\n  nixamp school check                     your live classes, and which ones no longer play\n  nixamp school prune [--end|--delete]    end or delete the ones that no longer play (prints them without a flag)\n\nLINK is what plays: a station link (`nixamp station show ID`), a nixamp.com share link, a\nPairux room, or an https .m3u8/.mp4/.mp3. SLUG is the class's slug or its /live/ link.\n  --json   machine-readable      NIXAMP_SCHOOL_URL   another site (backtoschool.help by default)\n";
+export declare function school(argv: string[]): Promise<number>;

package/dist/school-cli.js

@@ -0,0 +1,151 @@
+/**
+ * `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, } from "./school-client.js";
+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, name) {
+    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) {
+    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) {
+    const out = {};
+    for (const [name, key] of [["--title", "title"], ["--description", "description"], ["--topic", "topic"], ["--starts", "startsAt"], ["--link", "broadcastUrl"]]) {
+        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) {
+    console.log(`${item.status.padEnd(9)} ${item.title}\n          ${classUrl(item)}${item.broadcastUrl ? `\n          plays ${item.broadcastUrl}` : ""}`);
+}
+export async function school(argv) {
+    const [sub = "list"] = argv;
+    const json = argv.includes("--json");
+    const slug = positional(argv);
+    const out = (value, human) => { 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.message}`);
+        return 1;
+    }
+}

package/dist/school-client.d.ts

@@ -0,0 +1,61 @@
+export declare 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 declare class SchoolError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare function schoolSite(options?: SchoolOptions): string;
+export declare function classUrl(item: Pick<SchoolClass, "slug">, options?: SchoolOptions): string;
+export declare function listClasses(query?: {
+    status?: string;
+    kind?: string;
+    mine?: boolean;
+    limit?: number;
+}, options?: SchoolOptions): Promise<SchoolClass[]>;
+/** A class by its slug, id, or the /live/<slug> link. */
+export declare function getClass(slug: string, options?: SchoolOptions): Promise<SchoolClass>;
+export declare function createClass(input: Record<string, unknown>, options?: SchoolOptions): Promise<SchoolClass>;
+export declare function updateClass(slug: string, patch: Record<string, unknown>, options?: SchoolOptions): Promise<SchoolClass>;
+/** start, end, doors, encore, cancel or archive. Each wants the version it saw, so it is read first. */
+export declare function moveClass(slug: string, action: "start" | "end" | "doors" | "encore" | "cancel" | "archive", options?: SchoolOptions): Promise<SchoolClass>;
+export declare function deleteClass(slug: string, options?: SchoolOptions): Promise<void>;
+/** Make a class of a broadcast and put it on the air in one go. */
+export declare function teach(input: Record<string, unknown>, options?: SchoolOptions): Promise<SchoolClass>;
+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 declare function broadcastHealth(link: string | null | undefined, fetcher?: Fetcher, timeoutMs?: number): Promise<Health>;
+/** Your live classes, each with whether its broadcast plays. */
+export declare function checkClasses(options?: SchoolOptions, status?: string): Promise<Array<{
+    item: SchoolClass;
+    health: Health;
+}>>;
+export {};