nixamp 0.68.2 → 0.70.0

package/dist/school-mcp.js

@@ -0,0 +1,143 @@
+/**
+ * backtoschool.help classes as MCP tools: what `nixamp school` does, for an agent.
+ *
+ * Reading what is on needs nobody; making, starting, ending and deleting a
+ * class needs the token the rest of nixamp uses, because a class is a live
+ * event on the same accounts. `class_teach` is the one-call path from a
+ * station link (station_list / station_create) to a class on the air.
+ */
+import { broadcastHealth, checkClasses, classUrl, createClass, deleteClass, getClass, listClasses, moveClass, teach, updateClass, } from "./school-client.js";
+const STRING = { type: "string" };
+const SLUG = { ...STRING, description: "The class's slug, id, or its backtoschool.help/live/<slug> link." };
+const BROADCAST = { ...STRING, description: "What plays: a nixamp station link (https://<server>.nixamp.com:4321/station/<id>?t=<token>), a nixamp.com share link, a Pairux room, or an https .m3u8/.mp4/.mp3 URL." };
+const FIELDS = {
+    title: STRING,
+    description: STRING,
+    topic: STRING,
+    visibility: { type: "string", enum: ["public", "unlisted", "private"] },
+    startsAt: { ...STRING, description: "ISO 8601; leave out to start now (class_teach) or keep it a draft (class_create)." },
+    chatEnabled: { type: "boolean" },
+    handRaiseEnabled: { type: "boolean" },
+};
+export const SCHOOL_PUBLIC_TOOLS = [
+    {
+        name: "classes_list",
+        description: "Classes on backtoschool.help: live now, scheduled, drafts or ended. Each with its link, status and what it broadcasts. No sign-in needed (mine=true needs one).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                status: { type: "string", enum: ["draft", "scheduled", "starting", "live", "encore", "ended", "cancelled", "archived"] },
+                mine: { type: "boolean", description: "Only the classes this account hosts." },
+                limit: { type: "integer" },
+            },
+        },
+    },
+    {
+        name: "class_get",
+        description: "One class in full, and whether its broadcast is playing right now.",
+        inputSchema: { type: "object", properties: { slug: SLUG }, required: ["slug"] },
+    },
+];
+export const SCHOOL_TOOLS = [
+    ...SCHOOL_PUBLIC_TOOLS,
+    {
+        name: "class_teach",
+        description: "Make a class of a broadcast and put it on the air now: the one call from a station link to a live class. Returns the class link.",
+        inputSchema: { type: "object", properties: { broadcastUrl: BROADCAST, ...FIELDS }, required: ["title", "broadcastUrl"] },
+    },
+    {
+        name: "class_create",
+        description: "Make a class without starting it: a draft, or scheduled when startsAt is given.",
+        inputSchema: { type: "object", properties: { broadcastUrl: BROADCAST, ...FIELDS }, required: ["title"] },
+    },
+    {
+        name: "class_update",
+        description: "Change a class you host: title, description, topic, broadcast, visibility, time, chat or raised hands.",
+        inputSchema: { type: "object", properties: { slug: SLUG, broadcastUrl: BROADCAST, ...FIELDS }, required: ["slug"] },
+    },
+    {
+        name: "class_start",
+        description: "Put a class you host on the air.",
+        inputSchema: { type: "object", properties: { slug: SLUG }, required: ["slug"] },
+    },
+    {
+        name: "class_end",
+        description: "End a class you host. It stays listed as ended; a repeating class schedules its next session.",
+        inputSchema: { type: "object", properties: { slug: SLUG }, required: ["slug"] },
+    },
+    {
+        name: "class_delete",
+        description: "Delete a class you host, for good.",
+        inputSchema: { type: "object", properties: { slug: SLUG }, required: ["slug"] },
+    },
+    {
+        name: "classes_check",
+        description: "Your live classes, each with whether its broadcast still plays. A class stays live until ended, so this finds the ones showing a dead player; end or delete those.",
+        inputSchema: { type: "object", properties: {} },
+    },
+];
+export function isSchoolTool(name) {
+    return SCHOOL_TOOLS.some((tool) => tool.name === name);
+}
+export function isSchoolPublicTool(name) {
+    return SCHOOL_PUBLIC_TOOLS.some((tool) => tool.name === name);
+}
+const say = (text, isError = false) => ({ content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) });
+function line(item, options) {
+    return `${item.status.padEnd(9)} ${item.title}\n  ${classUrl(item, options)}${item.broadcastUrl ? `\n  plays ${item.broadcastUrl}` : ""}`;
+}
+function fieldsOf(args) {
+    const keys = ["title", "description", "topic", "visibility", "startsAt", "chatEnabled", "handRaiseEnabled", "broadcastUrl"];
+    return Object.fromEntries(keys.filter((key) => args[key] !== undefined).map((key) => [key, args[key]]));
+}
+export async function callSchoolTool(name, args, options = {}) {
+    const slug = typeof args["slug"] === "string" ? args["slug"] : "";
+    try {
+        if (name === "classes_list") {
+            const items = await listClasses({
+                ...(typeof args["status"] === "string" ? { status: args["status"] } : {}),
+                ...(args["mine"] === true ? { mine: true } : {}),
+                ...(typeof args["limit"] === "number" ? { limit: args["limit"] } : {}),
+            }, options);
+            return say(items.length ? items.map((one) => line(one, options)).join("\n\n") : "No classes match.");
+        }
+        if (name === "classes_check") {
+            const checked = await checkClasses(options);
+            if (checked.length === 0)
+                return say("You have no live classes.");
+            return say(checked.map(({ item, health }) => `${health.ok === true ? "plays " : health.ok === false ? "BROKEN" : "unknown"}  ${item.slug}: ${health.reason}`).join("\n"));
+        }
+        if (!slug && name !== "class_teach" && name !== "class_create")
+            return say("Which class? Pass its slug (classes_list).", true);
+        if (name === "class_get") {
+            const item = await getClass(slug, options);
+            const health = await broadcastHealth(item.broadcastUrl, options.fetcher ?? fetch);
+            return say(`${JSON.stringify(item, null, 2)}\n\nbroadcast: ${health.ok === true ? "playing" : health.ok === false ? "NOT playing" : "unknown"} (${health.reason})`);
+        }
+        if (name === "class_teach") {
+            const item = await teach(fieldsOf(args), options);
+            return say(`On the air: ${classUrl(item, options)}`);
+        }
+        if (name === "class_create") {
+            const item = await createClass(fieldsOf(args), options);
+            return say(`Made (${item.status}): ${classUrl(item, options)}\nclass_start ${item.slug} puts it on the air.`);
+        }
+        if (name === "class_update") {
+            const { slug: _slug, ...rest } = args;
+            const item = await updateClass(slug, fieldsOf(rest), options);
+            return say(line(item, options));
+        }
+        if (name === "class_start" || name === "class_end") {
+            const item = await moveClass(slug, name === "class_start" ? "start" : "end", options);
+            return say(line(item, options));
+        }
+        if (name === "class_delete") {
+            await deleteClass(slug, options);
+            return say(`Deleted ${slug}.`);
+        }
+    }
+    catch (error) {
+        return say(error.message, true);
+    }
+    return say(`No such tool: ${name}`, true);
+}

package/dist/server.js

@@ -30,6 +30,7 @@ import { Ingest, normaliseFormat } from "./ingest.js";
 import { BACKLOG_SECONDS, Channels, cleanId, generatedId, rememberChannels, rememberedChannels, rememberedNow, } from "./channels.js";
 import { RtmpListeners } from "./rtmp-in.js";
 import { Accounts, clearedCookie, sessionCookie, tokenFrom } from "./accounts.js";
+import { handleSchoolDiscovery, isSchoolSite } from "./school-discovery.js";
 import { RESET_INVALID, RESET_MESSAGE, resendPasswordReset } from "./password-reset.js";
 import { passwordResetPage } from "./password-reset-page.js";
 import { anonymousHandle, Handles } from "./handles.js";
@@ -3113,6 +3114,15 @@ export function createHandler(engine, options) {
             json(response, 200, { name: "nixamp", version: options.version, media: options.media });
             return;
         }
+        // backtoschool.help's own llms.txt, OpenAPI and class MCP, ahead of nixamp's (school-discovery.ts).
+        if (options.accounts && webSite && isSchoolSite(webSite.site)) {
+            const accounts = options.accounts;
+            if (await handleSchoolDiscovery(request, response, path, {
+                site: webSite.site, accountSite: options.site ?? "https://nixamp.com", version: options.version,
+                whoIs: (token) => accounts.whoIs(token), token: tokenFrom(request.headers), readBody, json,
+            }))
+                return;
+        }
         // Every way into nixamp, for agents and stores: llms.txt, OpenAPI, health, desktop downloads (discovery.ts).
         if (options.accounts && options.site && await handleDiscovery(request, response, path, { site: options.site, version: options.version, release, json }))
             return;

package/dist/station-cli.js

@@ -540,6 +540,7 @@ async function labelCommand(argv, call, show) {
                 resetDay: number("--reset-day"),
                 veo: has(argv, "--veo") ? true : has(argv, "--no-veo") ? false : undefined,
                 veoShots: number("--veo-shots"),
+                videoUsd: number("--video-usd"),
                 lipsyncShots: number("--lipsync-shots"),
                 storyShots: number("--story-shots"),
                 genreOrder: flag(argv, "--genres"),

package/dist/station-mcp.d.ts

@@ -2,6 +2,7 @@ export declare const STATION_TOOLS: ({
     name: string;
     description: string;
     inputSchema: {
+        required?: undefined;
         type: string;
         properties: {
             server: {
@@ -72,7 +73,6 @@ export declare const STATION_TOOLS: ({
             id?: undefined;
             private?: undefined;
         };
-        required?: undefined;
     };
 } | {
     name: string;
@@ -531,6 +531,7 @@ export declare const STATION_TOOLS: ({
     name: string;
     description: string;
     inputSchema: {
+        required?: undefined;
         type: string;
         properties: {
             playlist?: undefined;
@@ -615,12 +616,12 @@ export declare const STATION_TOOLS: ({
             id?: undefined;
             private?: undefined;
         };
-        required?: undefined;
     };
 } | {
     name: string;
     description: string;
     inputSchema: {
+        required?: undefined;
         type: string;
         properties: {
             playlist?: undefined;
@@ -718,12 +719,12 @@ export declare const STATION_TOOLS: ({
             id?: undefined;
             private?: undefined;
         };
-        required?: undefined;
     };
 } | {
     name: string;
     description: string;
     inputSchema: {
+        required?: undefined;
         type: string;
         properties: {
             playlist?: undefined;
@@ -862,12 +863,12 @@ export declare const STATION_TOOLS: ({
             id?: undefined;
             private?: undefined;
         };
-        required?: undefined;
     };
 } | {
     name: string;
     description: string;
     inputSchema: {
+        required?: undefined;
         type: string;
         properties: {
             playlist?: undefined;
@@ -960,12 +961,12 @@ export declare const STATION_TOOLS: ({
             license?: undefined;
             private?: undefined;
         };
-        required?: undefined;
     };
 } | {
     name: string;
     description: string;
     inputSchema: {
+        required?: undefined;
         type: string;
         properties: {
             playlist?: undefined;
@@ -1060,7 +1061,6 @@ export declare const STATION_TOOLS: ({
             };
             private?: undefined;
         };
-        required?: undefined;
     };
 } | {
     name: string;

package/dist/veo-studio.d.ts

@@ -61,7 +61,7 @@ export declare class VeoStudio {
     get canLipsync(): boolean;
     /**
      * A singer's close-up with the mouth redrawn to `audio` (the same seconds of
-     * the song): Sync's lipsync-2 on fal.ai. Veo's singers mouth a melody of their
+     * the song): Sync's lipsync-2-pro on fal.ai. Veo's singers mouth a melody of their
      * own; this makes them sing ours. Paid under the same monthly cap.
      */
     lipsync(input: {

package/dist/veo-studio.js

@@ -176,7 +176,7 @@ export class VeoStudio {
     get canLipsync() { return Boolean(this.options.falKey); }
     /**
      * A singer's close-up with the mouth redrawn to `audio` (the same seconds of
-     * the song): Sync's lipsync-2 on fal.ai. Veo's singers mouth a melody of their
+     * the song): Sync's lipsync-2-pro on fal.ai. Veo's singers mouth a melody of their
      * own; this makes them sing ours. Paid under the same monthly cap.
      */
     async lipsync(input) {
@@ -197,7 +197,7 @@ export class VeoStudio {
     }
     async sync(key, video, audio) {
         const [videoUrl, audioUrl] = await Promise.all([this.falUpload(key, video, "video/mp4", "shot.mp4"), this.falUpload(key, audio, "audio/mpeg", "vocal.mp3")]);
-        return await this.falJob(key, "fal-ai/sync-lipsync/v2", { video_url: videoUrl, audio_url: audioUrl }, "the lip sync");
+        return await this.falJob(key, "fal-ai/sync-lipsync/v2/pro", { video_url: videoUrl, audio_url: audioUrl }, "the lip sync");
     }
     async make(prompt, seconds, references) {
         const send = this.options.fetcher ?? fetch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.68.2",
+  "version": "0.70.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

@@ -586,6 +586,19 @@ export function elevenLabsAligner(key: string, fetcher: typeof fetch = fetch): (
   };
 }
 
+/** ElevenLabs voice isolation: a few seconds of the song in, the voice alone out (what a lip sync follows best). */
+export function elevenLabsIsolator(key: string, fetcher: typeof fetch = fetch): (audio: Buffer) => Promise<Buffer> {
+  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: string): string[] {
   return lyrics.split("\n").map((line) => line.trim()).filter((line) => line && !/^\[[^\]]*\]$/.test(line));
@@ -645,13 +658,17 @@ export async function writeStoryboard(
 }
 
 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 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 async function writeVeoStory(
   artist: Pick<LabelArtist, "genre" | "sound">,
   members: Array<Pick<Member, "role" | "look">>,
@@ -659,25 +676,33 @@ export async function writeVeoStory(
   song: Pick<LabelSong, "title" | "style" | "lyrics">,
   scenes: number,
   ask: typeof askJson = askJson,
-): Promise<string[]> {
-  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("; ");
+): Promise<StoryScene[]> {
+  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) 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.");
+  const out = list.map((one): StoryScene => {
+    const item = (typeof one === "object" && one ? one : { prompt: one }) as { prompt?: unknown; cast?: unknown };
+    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 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. */
@@ -826,13 +851,16 @@ 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: number, singing: boolean, usd = VIDEO_USD): { story: number; band: number; singer: number } {
+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));
+  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 };
 }
 
@@ -870,9 +898,10 @@ export function closeUpTimes(seconds: number, lines: Array<{ start: number }>, c
  * 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;
 
@@ -1026,6 +1055,8 @@ export interface AiLabelDeps {
   retryMs?: number;
   /** Cuts a single's filmed shots to its song; ffmpeg by default (renderFilmedVideo). */
   filmedVideo?: (input: { audio: string; clips: Array<{ path: string; seconds: number }>; seconds: number; artist: string; title: string; out: string; pinned?: Array<{ path: string; at: number; 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; audio: Buffer; seconds: number }) => Promise<Buffer>) | null;
   /** Renders a storyboard music video; ffmpeg by default (renderStoryVideo). */
@@ -1510,9 +1541,13 @@ 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: Buffer = 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: unknown) => { this.log(`voice isolation for "${song.title}": ${(error as Error).message}; the whole mix instead`); return voice; });
         let bytes: Buffer | null = null;
         for (let attempt = 0; ; attempt++) {
-          try { bytes = await lipsync({ video: readFileSync(shot), audio: readFileSync(audio), seconds: 8 }); break; } catch (error) {
+          try { bytes = await lipsync({ video: readFileSync(shot), audio: voice, seconds: 8 }); break; } catch (error) {
             if (attempt >= 2 || !TRANSIENT.test((error as Error).message)) throw error;
             await new Promise((done) => setTimeout(done, this.deps.retryMs ?? 60_000));
           }
@@ -1555,18 +1590,24 @@ export class AiLabel {
     const voice = (member: Member): boolean => /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<string, Buffer | null>();
     const portraits = async (list: Member[]): Promise<Buffer[]> => {
       const out: Buffer[] = [];
       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;
     };
@@ -1576,7 +1617,7 @@ export class AiLabel {
     const singer: Array<{ path: string; seconds: number }> = [];
     // The story is written only while some of its scenes are still to film.
     const storyFiles = Array.from({ length: counts.story }, (_, i) => join(keep, `story-${i}.mp4`));
-    let storyPrompts: string[] = [];
+    let storyPrompts: StoryScene[] = [];
     if (storyFiles.some((file) => !existsSync(file)) && this.canAsk()) {
       try {
         storyPrompts = await writeVeoStory(artist, members, album, song, storyFiles.length, this.deps.ask ?? askJson);
@@ -1584,12 +1625,22 @@ export class AiLabel {
         this.log(`no story for "${song.title}" yet: ${(error as 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): member is 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: [] as Buffer[], 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/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