@audiofool/moondog 0.3.0-beta.1 → 0.3.0-beta.10

package/src/integrations/stable-audio/local-generator.mjs

@@ -1,7 +1,8 @@
 // Makes music on this Mac with a local Stable Audio 3 install (Stability AI's optimized MLX
 // build). The listener turns it on once, in Settings or with /generation; until then nothing
 // runs. Each track is a WAV and a receipt in Moondog's state directory, and nothing leaves the
-// machine: weights are never downloaded here, and the receipt keeps no absolute path.
+// machine: a run never downloads anything, and the receipt keeps no absolute path. Moondog's own
+// install (setup.mjs) downloads only when the listener asks, from the pinned official sources.
 import { spawn } from "node:child_process";
 import { randomBytes, randomInt, randomUUID } from "node:crypto";
 import { unwatchFile, watchFile } from "node:fs";
@@ -12,10 +13,12 @@ import path from "node:path";
 import { resolveMoondogStateDirectory } from "../../core/state-directory.mjs";
 import { streamVariation } from "../../profile/taste-compiler.mjs";
 import { resolveMoondogAuthFile } from "../../runtime/pi/persistent-credential-store.mjs";
+import { readLoudness } from "./cover.mjs";
+import { DEFAULT_STABLE_AUDIO_MODEL, isStableAudioModel, SHARED_WEIGHTS, STABLE_AUDIO_MODELS } from "./sources.mjs";
 
-// The weights Stable Audio 3 Medium needs for text to music: the text encoder, the model and its decoder.
-const MEDIUM_WEIGHTS = ["t5gemma_f16.npz", "dit_medium_f16.npz", "same_l_decoder_f32.npz"];
-// Medium was trained on up to 380 seconds; very short clips come out rough.
+// The weights a model needs for text to music: the text encoder, the model and its decoder.
+export const stableAudioWeights = (model = DEFAULT_STABLE_AUDIO_MODEL) => [...SHARED_WEIGHTS, ...STABLE_AUDIO_MODELS[model].weights];
+// Medium and Small Music were trained on up to 380 seconds; very short clips come out rough.
 export const GENERATION_SECONDS = Object.freeze({ min: 15, max: 380, default: 120 });
 // A cold start reads about 4.8 GB of weights before the first step; a 380-second track then takes about 35 seconds.
 const generationTimeoutMs = 10 * 60_000;
@@ -29,6 +32,11 @@ export function defaultStableAudioRoot() {
   return path.join(homedir(), "Developer", "stable-audio-3", "optimized", "mlx");
 }
 
+/** The install Moondog downloads and manages itself; the MLX build is in its mlx folder. */
+export function resolveStableAudioManagedRoot(environment = process.env) {
+  return path.join(resolveMoondogStateDirectory(environment), "stable-audio-3");
+}
+
 // Kept next to the playback preference, apart from runtime settings.
 export function resolveGenerationSettingsFile(environment = process.env) {
   return path.join(path.dirname(resolveMoondogAuthFile(environment)), "generation.json");
@@ -47,41 +55,92 @@ function literalFolder(value) {
   return path.isAbsolute(expanded) ? path.resolve(expanded) : null;
 }
 
+export async function readSavedSettings(environment) {
+  try {
+    const document = JSON.parse(await readFile(resolveGenerationSettingsFile(environment), "utf8"));
+    return document?.version === 1 ? document : {};
+  } catch {
+    return {}; // Not set up yet.
+  }
+}
+
 /**
- * The listener's choice: { enabled, path, source }. Generation is off until they turn it on;
- * MOONDOG_SA3_DIR can point at another install but never turns it on.
+ * The listener's choice: { enabled, path, source, model, folder }. Generation is off until they
+ * turn it on; MOONDOG_SA3_DIR can point at another install but never turns it on. source is
+ * "managed" for Moondog's own install, "settings" or "default" for the listener's own folder
+ * (folder, which Moondog only reads), or "environment". model picks the weights in either.
  * A missing or unreadable file reads as off, so an older or newer file never stops the room.
  */
-export async function readGenerationSettings(environment = process.env) {
-  let document = null;
-  try {
-    document = JSON.parse(await readFile(resolveGenerationSettingsFile(environment), "utf8"));
-  } catch { /* Not set up yet. */ }
-  const saved = document?.version === 1 ? document : {};
+export async function readGenerationSettings(environment = process.env, { platform = process.platform, arch = process.arch } = {}) {
+  const saved = await readSavedSettings(environment);
   const fromEnvironment = literalFolder(environment.MOONDOG_SA3_DIR);
   const fromFile = literalFolder(saved.path);
+  const managed = !fromEnvironment && saved.source === "managed";
+  const folder = fromFile ?? defaultStableAudioRoot();
+  let model = isStableAudioModel(saved.model) ? saved.model : DEFAULT_STABLE_AUDIO_MODEL;
+  // A folder Moondog doesn't manage (MOONDOG_SA3_DIR, a typed folder, ~/Developer) runs the saved model
+  // only if it has it, otherwise the first model it can run; a model chosen for Moondog's own install
+  // waits until that install is chosen again. A folder that runs nothing keeps the saved model.
+  if (!managed) {
+    for (const name of [...new Set([model, DEFAULT_STABLE_AUDIO_MODEL, ...Object.keys(STABLE_AUDIO_MODELS)])]) {
+      if ((await checkStableAudioInstall(fromEnvironment ?? folder, { model: name, platform, arch })).state === "ready") { model = name; break; }
+    }
+  }
   return {
     enabled: saved.enabled === true,
-    path: fromEnvironment ?? fromFile ?? defaultStableAudioRoot(),
-    source: fromEnvironment ? "environment" : fromFile ? "settings" : "default",
+    path: fromEnvironment ?? (managed ? path.join(resolveStableAudioManagedRoot(environment), "mlx") : folder),
+    source: fromEnvironment ? "environment" : managed ? "managed" : fromFile ? "settings" : "default",
+    model,
+    folder,
   };
 }
 
-export async function writeGenerationSettings({ enabled, path: folder } = {}, environment = process.env) {
-  const current = await readGenerationSettings(environment);
+/**
+ * Saves what the listener changed: enabled; path, their own folder, which also switches to it;
+ * source "managed" or "settings" to switch between Moondog's install and their folder; model.
+ * A model chosen without a folder or a source switches to Moondog's install, which holds it.
+ * Older Moondogs read the same version 1 file and see only enabled and path.
+ */
+export async function writeGenerationSettings({ enabled, path: folder, source, model } = {}, environment = process.env, { platform = process.platform, arch = process.arch } = {}) {
+  // The file's own view: a folder MOONDOG_SA3_DIR pins in this process is never written into it.
+  const current = await readGenerationSettings({ ...environment, MOONDOG_SA3_DIR: "" }, { platform, arch });
+  const saved = await readSavedSettings(environment);
   const typed = folder === undefined ? undefined : literalFolder(folder);
   if (folder !== undefined && folder !== null && !typed) {
     throw Object.assign(new Error("Give the Stable Audio 3 folder as a full path, or one starting with ~/."), { code: "generation_path_invalid" });
   }
+  if (model !== undefined && !isStableAudioModel(model)) {
+    throw Object.assign(new Error("Choose medium or small-music."), { code: "generation_model_invalid" });
+  }
+  const savedFolder = typed ?? literalFolder(saved.path);
+  const managed = typed ? false
+    : source === "managed" ? true
+      : source === "settings" ? false
+        : model !== undefined ? true
+          : saved.source === "managed";
+  // Switching to the listener's own folder without a model keeps the model only if that folder has it;
+  // otherwise the first model it can run, so a working install is never checked for weights it lacks.
+  let chosen = model ?? current.model;
+  if (model === undefined && !managed && (typed || source === "settings")) {
+    const folderRoot = savedFolder ?? current.folder;
+    const candidates = [current.model, DEFAULT_STABLE_AUDIO_MODEL, ...Object.keys(STABLE_AUDIO_MODELS)];
+    // A folder that runs nothing yet gets Medium, the model the install steps Moondog shows download.
+    chosen = DEFAULT_STABLE_AUDIO_MODEL;
+    for (const name of [...new Set(candidates)]) {
+      if ((await checkStableAudioInstall(folderRoot, { model: name, platform, arch })).state === "ready") { chosen = name; break; }
+    }
+  }
   const document = {
     version: 1,
     enabled: enabled === undefined ? current.enabled : enabled === true,
-    ...(typed ? { path: typed } : current.source === "settings" ? { path: current.path } : {}),
+    ...(savedFolder ? { path: savedFolder } : {}),
+    ...(managed ? { source: "managed" } : {}),
+    model: chosen,
   };
   const file = resolveGenerationSettingsFile(environment);
   await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
   await writeFile(file, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-  return readGenerationSettings(environment);
+  return readGenerationSettings(environment, { platform, arch });
 }
 
 const isFile = async (file, { executable = false, minimumBytes = 0 } = {}) => {
@@ -97,16 +156,16 @@ const isFile = async (file, { executable = false, minimumBytes = 0 } = {}) => {
 };
 
 /**
- * Whether an install can make music now, without running it: "ready", "unsupported" (MLX needs
- * Apple silicon), "missing" (no install at the folder) or "incomplete" (no Python environment
- * or no Medium weights, which Stability's ./install.sh fetches).
+ * Whether an install can make music now with a model, without running it: "ready", "unsupported"
+ * (MLX needs Apple silicon), "missing" (no install at the folder) or "incomplete" (no Python
+ * environment or not that model's weights, which Moondog's setup or Stability's ./install.sh fetches).
  */
-export async function checkStableAudioInstall(root, { platform = process.platform, arch = process.arch } = {}) {
+export async function checkStableAudioInstall(root, { model = DEFAULT_STABLE_AUDIO_MODEL, platform = process.platform, arch = process.arch } = {}) {
   if (platform !== "darwin" || arch !== "arm64") return { state: "unsupported" };
   if (!root || !path.isAbsolute(root)) return { state: "missing" };
   if (!(await isFile(path.join(root, "scripts", "sa3_mlx.py")))) return { state: "missing" };
   if (!(await isFile(path.join(root, ".venv", "bin", "python"), { executable: true }))) return { state: "incomplete", missing: "environment" };
-  for (const weight of MEDIUM_WEIGHTS) {
+  for (const weight of stableAudioWeights(isStableAudioModel(model) ? model : DEFAULT_STABLE_AUDIO_MODEL)) {
     if (!(await isFile(path.join(root, "models", "mlx", weight), { minimumBytes: 1024 }))) return { state: "incomplete", missing: "weights" };
   }
   return { state: "ready" };
@@ -170,8 +229,10 @@ export function createLocalGenerator({
   arch = process.arch,
   spawnImpl = spawn,
   now = () => new Date(),
+  // Whether the listener's library holds a made track: a stream never drops the audio of one they kept.
+  keeps = () => false,
 } = {}) {
-  let current = { state: "unknown", enabled: false, install: "unknown", path: null, source: null };
+  let current = { state: "unknown", enabled: false, install: "unknown", path: null, source: null, model: DEFAULT_STABLE_AUDIO_MODEL, managed: false };
   let running = null;
   // The tracks made here, newest last, with what happened each time they played: the loop back
   // from listening reads them. Each track's outcomes.jsonl keeps them; the receipt never changes.
@@ -196,8 +257,8 @@ export function createLocalGenerator({
   const check = () => {
     checking ??= (async () => {
       try {
-        const settings = await readGenerationSettings(environment);
-        const install = await checkStableAudioInstall(settings.path, { platform, arch });
+        const settings = await readGenerationSettings(environment, { platform, arch });
+        const install = await checkStableAudioInstall(settings.path, { model: settings.model, platform, arch });
         return publish({
           state: !settings.enabled ? "off" : install.state,
           enabled: settings.enabled,
@@ -205,6 +266,8 @@ export function createLocalGenerator({
           ...(install.missing ? { missing: install.missing } : {}),
           path: settings.path,
           source: settings.source,
+          model: settings.model,
+          managed: settings.source === "managed",
         });
       } finally {
         checking = null;
@@ -233,13 +296,13 @@ export function createLocalGenerator({
   };
 
   const stopped = () => Object.assign(new Error("Making the track was stopped."), { name: "AbortError", code: "generation_stopped" });
-  const run = ({ root, prompt, seconds, seed, out }, { signal, onProgress }) => new Promise((resolve, reject) => {
+  const run = ({ root, model, prompt, seconds, seed, out }, { signal, onProgress }) => new Promise((resolve, reject) => {
     // A stop that came while the install was checked starts nothing.
     if (signal?.aborted) return reject(stopped());
     // The Python script itself, not Stability's ./sa3 wrapper: the wrapper wants uv on PATH and a
     // terminal, and its exec would leave a shell between this process and the one to stop.
     const child = spawnImpl(path.join(root, ".venv", "bin", "python"), [
-      "scripts/sa3_mlx.py", "--prompt", prompt, "--dit", "medium", "--decoder", "same-l",
+      "scripts/sa3_mlx.py", "--prompt", prompt, "--dit", STABLE_AUDIO_MODELS[model].dit, "--decoder", STABLE_AUDIO_MODELS[model].decoder,
       "--seconds", String(seconds), "--seed", String(seed), "--steps", "8", "--out", out,
     ], {
       cwd: root,
@@ -376,6 +439,9 @@ export function createLocalGenerator({
           close(false);
           playing = { id: track.id, heardMs: 0, since: Date.now() };
         } else if (playing.since === null) playing.since = Date.now();
+      } else if (event?.type === "playing" && playing && track && track.generated !== true) {
+        // A song from the catalog after a made track in a library playlist: the made track's play ended there.
+        close(false);
       } else if (event?.type === "paused" && playing && playing.since !== null) {
         playing.heardMs += Date.now() - playing.since;
         playing.since = null;
@@ -391,9 +457,11 @@ export function createLocalGenerator({
     /** Waits for the outcomes still being written, as a room does before it closes. */
     flush: () => Promise.allSettled([...writing]),
     // A replay of the track playing now starts it over; that is not a skip.
-    // A stream keeps only its newest tracks' audio; the receipt and outcomes of the rest stay.
+    // A stream keeps only its newest tracks' audio; the receipt and outcomes of the rest stay. A track in the
+    // listener's library keeps its audio, and a library that can't be read keeps it too.
     async removeAudio(id) {
       if (!isGeneratedTrackId(id)) return;
+      try { if (keeps(id)) return; } catch { return; }
       await rm(path.join(tracksDirectory(), id, "track.wav"), { force: true }).catch(() => {});
       const entry = made.get(id);
       if (entry) entry.audio_kept = false;
@@ -401,9 +469,10 @@ export function createLocalGenerator({
     restart(id) {
       if (playing?.id === id) playing = null;
     },
-    // A play Moondog cut off as it began, as a stream past its time limit does, says nothing about the listener.
+    // A play Moondog cut off as it began, as a stream past its time limit does, says nothing about the
+    // listener. Without an id, whatever made track plays now, as when a stream's first track replaces it.
     discard(id) {
-      if (playing?.id === id) playing = null;
+      if (playing && (id === undefined || playing.id === id)) playing = null;
     },
     recordReplay(id, by) {
       this.restart(id);
@@ -413,7 +482,7 @@ export function createLocalGenerator({
     busy: () => running !== null,
     check,
     async save(settings) {
-      await writeGenerationSettings(settings, environment);
+      await writeGenerationSettings(settings, environment, { platform, arch });
       return check();
     },
     subscribe(listener) {
@@ -468,10 +537,13 @@ export function createLocalGenerator({
         await mkdir(temporary, { mode: 0o700 });
         const wav = path.join(temporary, "track.wav");
         onProgress?.({ stage: "starting" });
-        const measured = await run({ root: status.path, prompt, seconds, seed, out: wav }, { signal, onProgress });
+        const model = isStableAudioModel(status.model) ? status.model : DEFAULT_STABLE_AUDIO_MODEL;
+        const measured = await run({ root: status.path, model, prompt, seconds, seed, out: wav }, { signal, onProgress });
         const audio = await wavInfo(wav).catch(() => null);
         if (!audio || audio.duration_seconds <= 0) throw generationError("generation_failed", "Stable Audio 3 finished but wrote no playable track.");
         await chmod(wav, 0o600);
+        // How loud it runs from start to end, which its cover draws (cover.mjs); kept after a stream drops the audio.
+        const loudness = await readLoudness(wav).catch(() => null);
         const elapsed = Date.now() - started;
         const document = {
           receipt_version: "moondog-generated-track/1",
@@ -481,11 +553,11 @@ export function createLocalGenerator({
           title,
           ...receipt,
           generator: {
-            adapter: "stable-audio-3", adapter_version: 1, model: "sa3-medium-ARC", decoder: "same-l",
+            adapter: "stable-audio-3", adapter_version: 1, model: STABLE_AUDIO_MODELS[model].receipt, decoder: STABLE_AUDIO_MODELS[model].decoder,
             prompt, seconds, seed, steps: 8, cfg: 1, elapsed_ms: elapsed, ...(measured ? { measured } : {}),
             license: "Stability AI Community License; outputs belong to the listener",
           },
-          audio: { file: "track.wav", ...audio },
+          audio: { file: "track.wav", ...audio, ...(loudness ? { loudness } : {}) },
         };
         await writeFile(path.join(temporary, "receipt.json"), `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
         await rename(temporary, path.join(folder, id));
@@ -508,21 +580,85 @@ export function createLocalGenerator({
 // background. Stopping the player, other music, or the time limit ends it. One stream per room, on
 // the room's one generator; only its newest tracks keep their audio, and every receipt stays.
 const STREAM_SKIP_MS = 30_000;
+// How long a later track waits for its own name before it takes a numbered one.
+const NAMING_TIMEOUT_MS = 10_000;
 export function createAtmosphereStream({ generator, player, now = Date.now, keepAudio = 3 }) {
   let stream = null;
+  // What the surfaces see (view()) and hear (subscribe): the phase, and the end with its reason.
+  const listeners = new Set();
+  let shown = "null";
+  // Events wait their turn, so a listener that stops the stream from inside one never reorders them.
+  const events = [];
+  let delivering = false;
+  const deliver = (event) => {
+    events.push(event);
+    if (delivering) return;
+    delivering = true;
+    try {
+      while (events.length) {
+        const next = events.shift();
+        for (const listener of [...listeners]) {
+          try { listener(structuredClone(next)); } catch { /* A surface's redraw cannot stop the stream. */ }
+        }
+      }
+    } finally {
+      delivering = false;
+    }
+  };
+  const viewOf = (current) => current ? {
+    // Nothing of it plays yet; it waits in the dry gap for its next track; it makes the next behind one loaded; or it only plays.
+    phase: !current.current ? "starting" : current.waiting ? "waiting" : current.making ? "making" : "playing",
+    started_at: new Date(current.startedAt).toISOString(), ends_at: new Date(current.endsAt).toISOString(), tracks_made: current.made.length,
+  } : null;
+  // Called after anything that may change the view; only a real change reaches the listeners.
+  const changed = () => {
+    const view = viewOf(stream);
+    const key = JSON.stringify(view);
+    if (key === shown) return;
+    shown = key;
+    deliver({ view, ended: null });
+  };
+  // The tracks of a stream that gave way to Moondog's next one, while the player may still hold one of
+  // them; a listener's stop before the new stream's first track plays stops them too.
+  let heldOver = null;
   const end = (reason) => {
     const ending = stream;
     if (!ending) return null;
     stream = null;
     ending.controller.abort();
     ending.ended = reason;
+    heldOver = reason === "replaced" && (ending.current || heldOver)
+      ? new Set([...(heldOver ?? []), ...ending.made.map((made) => made.id)]) : null;
+    shown = "null";
+    deliver({ view: null, ended: reason });
     return ending;
   };
   const trackFor = (ending, position) => {
     const variation = streamVariation(ending.compiled, position, ending.leaveOut);
-    return { variation, prompt: stableAudioPrompt(variation), title: `${ending.title} · ${position + 1}`,
+    // The first track carries the stream's own name; a later one is named as it is made (nameFor), or numbered.
+    return { variation, prompt: stableAudioPrompt(variation), title: position === 0 ? ending.title : `${ending.title} · ${position + 1}`,
       receipt: { ...ending.receipt, shaped_by: variation.descriptors, ...(variation.bpm ? { bpm: variation.bpm } : {}),
-        stream: { started_at: new Date(ending.startedAt).toISOString(), position: position + 1, featured: variation.featured } } };
+        stream: { name: ending.title, started_at: new Date(ending.startedAt).toISOString(), position: position + 1, featured: variation.featured } } };
+  };
+  // A name of its own for a later track, asked of the stream's namer within a few seconds. One that
+  // fails, is slow, or repeats a name this stream gave keeps the numbered name.
+  const nameFor = async (ending, variation, numbered) => {
+    if (typeof ending.nameTrack !== "function") return numbered;
+    const timeout = AbortSignal.timeout(NAMING_TIMEOUT_MS);
+    try {
+      const name = await Promise.race([
+        ending.nameTrack({
+          stream: ending.title, featured: variation.featured,
+          sound: variation.descriptors.map((descriptor) => descriptor.term).filter((term) => !variation.featured.includes(term)),
+          ...(variation.bpm ? { bpm: variation.bpm } : {}), earlier: [...ending.names],
+        }, { signal: AbortSignal.any([timeout, ending.controller.signal]) }),
+        new Promise((resolve) => { timeout.addEventListener("abort", () => resolve(null), { once: true }); }),
+      ]);
+      const text = typeof name === "string" ? name.trim() : "";
+      return text && !ending.names.some((earlier) => earlier.toLocaleLowerCase() === text.toLocaleLowerCase()) ? text : numbered;
+    } catch {
+      return numbered;
+    }
   };
   // The tracks that started playing keep their audio, the newest few; the rest keep their receipts.
   const prune = (current) => {
@@ -564,8 +700,12 @@ export function createAtmosphereStream({ generator, player, now = Date.now, keep
     const current = stream;
     if (!current || current.making || current.next || !fits(current)) return;
     current.making = true;
+    changed();
     try {
-      const { prompt, title, receipt, variation } = trackFor(current, current.made.length);
+      const { prompt, title: numbered, receipt, variation } = trackFor(current, current.made.length);
+      const title = await nameFor(current, variation, numbered);
+      if (stream !== current) return;
+      current.names.push(title);
       const made = await generator.generate({ prompt, seconds: current.seconds, title, receipt }, { signal: current.controller.signal });
       if (stream !== current) return;
       const file = await generator.trackFile(made.id);
@@ -574,6 +714,8 @@ export function createAtmosphereStream({ generator, player, now = Date.now, keep
       if (current.waiting && expired(current)) { end("time"); return; }
       current.made.push({ id: made.id, featured: variation.featured, started: false, seconds: made.duration_seconds });
       current.next = made.id;
+      // Made, so what the player reports from here on sees the stream as only playing.
+      current.making = false;
       const track = { id: made.id, title: made.title, seconds: made.duration_seconds, file };
       // A queue that ran dry while this was made starts again with it.
       if (current.waiting) { current.waiting = false; player.playGenerated(track); } else player.enqueueGenerated(track);
@@ -583,6 +725,52 @@ export function createAtmosphereStream({ generator, player, now = Date.now, keep
       if (stream === current && error?.code !== "generation_stopped") end("failed");
     } finally {
       current.making = false;
+      changed();
+    }
+  };
+  // What the room's player reports moves the stream along or ends it.
+  const move = (event) => {
+    const current = stream;
+    // Until its first track plays, what the player reports is about the music before it.
+    if (!current || !current.current) return;
+    const track = event?.track;
+    const ours = (id) => current.made.some((made) => made.id === id);
+    // A queue or a song that is not one of the stream's tracks is other music, which ends the stream.
+    if (event?.type === "queue" || event?.type === "playing") {
+      const items = Array.isArray(event.tracks) ? event.tracks : track ? [track] : [];
+      if (items.some((item) => !item?.generated || (item.id && !ours(item.id)))) { end("other_music"); return; }
+    }
+    const isCurrent = track?.id && track.id === current.current.id;
+    if (event?.type === "playing" && track?.id && track.id === current.next) {
+      // The window may already have moved on to it when the time limit had passed. The generator
+      // has begun counting it, and Moondog's own stop must not read as the listener's skip.
+      if (expired(current)) { generator.discard?.(track.id); endInTime(); return; }
+      leftEarly(current);
+      const made = current.made.find((entry) => entry.id === track.id);
+      current.current = { id: track.id, heardMs: 0, since: now(), finished: false, seconds: made?.seconds };
+      if (made) made.started = true;
+      current.next = null;
+      current.waiting = false;
+      prune(current);
+      void makeNext();
+    } else if (event?.type === "paused" && isCurrent && current.current.since !== null) {
+      current.current.heardMs += now() - current.current.since;
+      current.current.since = null;
+    } else if (event?.type === "playing" && isCurrent && current.current.since === null) {
+      current.current.since = now();
+    } else if (event?.type === "skipped" && isCurrent) {
+      // A skip past the end of the queue moves on to the next track once it is made.
+      leftEarly(current);
+      current.current.finished = true;
+      if (!current.next) ranDry(current);
+      else if (expired(current)) endInTime();
+    } else if ((event?.type === "finished" || event?.type === "failed") && isCurrent) {
+      // A track that could not play says nothing about the listener; it is passed over like one that ended.
+      current.current.finished = true;
+      if (!current.next) ranDry(current);
+      else if (expired(current)) endInTime();
+    } else if (event?.type === "stopped" && !current.waiting && !current.starting) {
+      end("stopped");
     }
   };
   return {
@@ -593,17 +781,25 @@ export function createAtmosphereStream({ generator, player, now = Date.now, keep
       return { tracks_made: stream.made.length, started_at: new Date(stream.startedAt).toISOString(),
         ends_at: new Date(stream.endsAt).toISOString(), steering_away_from: [...stream.leaveOut] };
     },
+    /** For the surfaces: { phase, started_at, ends_at, tracks_made }, or null when no stream runs. */
+    view: () => viewOf(stream),
+    /** Hears { view, ended } once for each change: the start, each phase, each track made, and the end with its reason. */
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
     /**
      * Starts a stream from a compiled taste and plays its first track; the next is made at once.
      * beforePlay runs once the first track exists, so other music pauses only when there is one to
-     * play. Returns the first track. A stream already running gives way to the new one.
+     * play. Returns the first track. A stream already running gives way to the new one, and its track
+     * plays on until the first new one takes over, so nothing goes silent while that is made.
      */
-    async start({ compiled, title, seconds, minutes, receipt = {} }, { signal, onProgress, onTrack, beforePlay } = {}) {
-      const previous = end("replaced");
-      if (previous?.current) player.stop?.();
+    async start({ compiled, title, seconds, minutes, receipt = {} }, { signal, onProgress, onTrack, beforePlay, nameTrack } = {}) {
+      end("replaced");
       const current = { compiled, title, seconds, receipt, onTrack, startedAt: now(), endsAt: now() + minutes * 60_000,
-        made: [], leaveOut: new Set(), current: null, next: null, waiting: false, making: true, controller: new AbortController() };
+        made: [], names: [title], nameTrack, leaveOut: new Set(), current: null, next: null, waiting: false, making: true, controller: new AbortController() };
       stream = current;
+      changed();
       const stopped = () => Object.assign(new Error("The stream was stopped before it began."), { code: "generation_stopped" });
       try {
         const { prompt, title: first, receipt: firstReceipt, variation } = trackFor(current, 0);
@@ -617,67 +813,43 @@ export function createAtmosphereStream({ generator, player, now = Date.now, keep
         current.made.push({ id: made.id, featured: variation.featured, started: true, seconds: made.duration_seconds });
         current.current = { id: made.id, heardMs: 0, since: now(), finished: false, seconds: made.duration_seconds };
         current.making = false;
+        // The made track it replaces, a single one or the last stream's, was cut off by Moondog, not
+        // left by the listener: counted as a skip, it would steer later tracks away from its sound.
+        generator.discard?.();
         // Whatever was playing stops for the first track; that stop is not the listener's.
         current.starting = true;
         try { player.playGenerated({ id: made.id, title: made.title, seconds: made.duration_seconds, file }); } finally { current.starting = false; }
+        heldOver = null;
         onTrack?.(made);
         void makeNext();
+        changed();
         return { made, prompt, variation };
       } catch (error) {
-        if (stream === current) end("failed");
+        // A reply stopped while the first track was made is the listener's own stop, not a failure.
+        if (stream === current) end(error?.code === "generation_stopped" ? "asked" : "failed");
+        // Why it ended tells the listener turning it off apart from a stop of the reply.
+        if (error?.code === "generation_stopped" && error.ended === undefined) error.ended = current.ended ?? null;
         throw error;
       }
     },
     stop(reason = "asked") {
+      const held = heldOver;
       const ending = end(reason);
-      // Before its first track plays, the player still holds the music from before the stream, which stays.
-      if (ending?.current) player.stop?.();
+      // Before its first track plays, the player still holds the music from before the stream, which
+      // stays, unless that is the track of the stream it replaced. A stream replaced by Moondog's next
+      // track or stream plays on until that one takes over.
+      if (ending && reason !== "replaced" && (ending.current || held)) player.stop?.();
       return ending ? { tracks_made: ending.made.length } : null;
     },
     /** What the room's player reports, which moves the stream along or ends it. */
     observe(event) {
-      const current = stream;
-      // Until its first track plays, what the player reports is about the music before it.
-      if (!current || !current.current) return;
-      const track = event?.track;
-      const ours = (id) => current.made.some((made) => made.id === id);
-      // A queue or a song that is not one of the stream's tracks is other music, which ends the stream.
-      if (event?.type === "queue" || event?.type === "playing") {
-        const items = Array.isArray(event.tracks) ? event.tracks : track ? [track] : [];
-        if (items.some((item) => !item?.generated || (item.id && !ours(item.id)))) { end("other_music"); return; }
-      }
-      const isCurrent = track?.id && track.id === current.current.id;
-      if (event?.type === "playing" && track?.id && track.id === current.next) {
-        // The window may already have moved on to it when the time limit had passed. The generator
-        // has begun counting it, and Moondog's own stop must not read as the listener's skip.
-        if (expired(current)) { generator.discard?.(track.id); endInTime(); return; }
-        leftEarly(current);
-        const made = current.made.find((entry) => entry.id === track.id);
-        current.current = { id: track.id, heardMs: 0, since: now(), finished: false, seconds: made?.seconds };
-        if (made) made.started = true;
-        current.next = null;
-        current.waiting = false;
-        prune(current);
-        void makeNext();
-      } else if (event?.type === "paused" && isCurrent && current.current.since !== null) {
-        current.current.heardMs += now() - current.current.since;
-        current.current.since = null;
-      } else if (event?.type === "playing" && isCurrent && current.current.since === null) {
-        current.current.since = now();
-      } else if (event?.type === "skipped" && isCurrent) {
-        // A skip past the end of the queue moves on to the next track once it is made.
-        leftEarly(current);
-        current.current.finished = true;
-        if (!current.next) ranDry(current);
-        else if (expired(current)) endInTime();
-      } else if ((event?.type === "finished" || event?.type === "failed") && isCurrent) {
-        // A track that could not play says nothing about the listener; it is passed over like one that ended.
-        current.current.finished = true;
-        if (!current.next) ranDry(current);
-        else if (expired(current)) endInTime();
-      } else if (event?.type === "stopped" && !current.waiting && !current.starting) {
-        end("stopped");
+      // Other music, or a stop, means the player no longer holds the replaced stream's tracks.
+      if (heldOver) {
+        const items = Array.isArray(event?.tracks) ? event.tracks : event?.track ? [event.track] : [];
+        if (event?.type === "stopped" || ((event?.type === "queue" || event?.type === "playing") && items.some((item) => !heldOver.has(item?.id)))) heldOver = null;
       }
+      move(event);
+      changed();
     },
   };
 }