@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/sound/lipsync.ts

@@ -0,0 +1,24 @@
+// Optional, precomputed cues only apply to the exact final audio analysed by the prototype.
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import type { WorldFiles } from '../world/files.ts';
+import { MOUTHS, type LipSync, type MouthCue } from '../play/lipsync.ts';
+
+export function lipSyncData(files: WorldFiles): Record<string, LipSync> {
+  const file = files.path('sound', 'lipsync.json');
+  if (!fs.existsSync(file)) return {};
+  try {
+    const manifest = JSON.parse(fs.readFileSync(file, 'utf8')) as { version: number; byFile: Record<string, LipSync & { sha256: string }> };
+    if (manifest.version !== 1) return {};
+    return Object.fromEntries(Object.entries(manifest.byFile).filter(([audio, data]) => {
+      if (!data || typeof data !== 'object') return false;
+      if (data.step !== undefined && (!Number.isFinite(data.step) || data.step <= 0)) return false;
+      if (data.envelope !== undefined && (!Array.isArray(data.envelope) || !data.envelope.every(v => Number.isFinite(v) && v >= 0 && v <= 1))) return false;
+      if (!audio.startsWith('sound/voice/') || audio.includes('..') || !fs.existsSync(files.path(audio))) return false;
+      if (createHash('sha256').update(fs.readFileSync(files.path(audio))).digest('hex') !== data.sha256) return false;
+      return Array.isArray(data.cues) && data.cues.length > 0 && data.cues.every((cue: MouthCue, i: number) =>
+        !!cue && MOUTHS.includes(cue.value) && Number.isFinite(cue.start) && Number.isFinite(cue.end) && cue.start >= 0 && cue.end > cue.start
+        && (!i || cue.start >= data.cues[i - 1].end));
+    }).map(([audio, { cues, envelope, step }]) => [audio, { cues, envelope, step }]));
+  } catch { return {}; } // An old or unfinished prototype never prevents a world from playing.
+}

package/app/src/sound/make.ts

@@ -0,0 +1,229 @@
+// Turns a sound plan into files: generates each take, checks it, makes loops seamless, cuts footsteps,
+// levels everything, and writes sound/<id>.mp3 plus sound/sounds.json for the runtime.
+import { z } from 'zod';
+import fs from 'node:fs';
+import path from 'node:path';
+import { emit } from '../registry.ts';
+import { inputHash, type Memo } from '../meta/memo.ts';
+import { sharedDir, soundQuality } from './cost.ts';
+import { audioProblem, decode, encodeMp3, hiss, loopProblem, tonalShare, normalise, seamless, seconds, steps, trim, type Pcm } from './pcm.ts';
+import { soundIds, type SoundPlan } from './plan.ts';
+import { elevenKey, elevenMusic, forgetEffect, musicgen, MUSICGEN_MODEL, soundEffect, type EffectAsk } from './sources.ts';
+import type { SoundFixes } from './fixes.ts';
+
+export const Kind = z.enum(['music', 'bed', 'loop', 'step', 'shot']);
+export type Kind = z.infer<typeof Kind>;
+
+export const SoundEntry = z.object({
+  file: z.string(),
+  kind: Kind,
+  level: z.number().default(2),
+  seconds: z.number(),
+  /** Footsteps: [start, duration] of each single step inside the file. */
+  slices: z.array(z.tuple([z.number(), z.number()])).optional(),
+  source: z.string(),
+  prompt: z.string(),
+  flags: z.array(z.string()).default([]),
+  /** Made in draft or final quality; sounds made before qualities existed were full length. */
+  quality: z.enum(['draft', 'final']).default('final'),
+  /** How ambience was mixed: below MIX it is made again (from the memo, at no cost) with the current levels and hiss check. */
+  mix: z.number().optional(),
+  validation: z.number().optional(),
+});
+export const SoundManifest = z.object({ sounds: z.record(z.string(), SoundEntry), failures: z.record(z.string(), z.string()).default({}) });
+export type SoundEntry = z.infer<typeof SoundEntry>;
+export type SoundManifest = z.infer<typeof SoundManifest>;
+
+/** Loudness each kind is levelled to before the mixer's own gains, dBFS RMS. */
+// Ambience sits well under the music: at -24 a bed of wind and leaves was a constant hiss over the whole game.
+const TARGET_DB: Record<Kind, number> = { music: -20, bed: -31, loop: -28, step: -16, shot: -17 };
+/** Ambience made with the levels and the hiss check above; older beds and loops are made again. */
+export const MIX = 3;
+export const AUDIO_VALIDATION = 1;
+/** Above this a bed or loop is mostly hiss (energy of the sample-to-sample change over the energy: white noise is 2, music 0.06). */
+export const HISS = 0.4;
+const NO_HISS = '. Not wind, not rustling, no hiss or air noise: soft distant life and warm low tones';
+/** Mostly hiss: high-frequency energy that is noise. Crickets, birdsong and other tones are not hiss, however bright. */
+export const hissy = (pcm: Pcm) => hiss(pcm) > HISS && tonalShare(pcm) < 0.3;
+/** Sounds that are hiss by nature (a waterfall's roar, rain, surf): three takes of one were all "mostly hiss" and it stayed silent. */
+export const HISS_BY_NATURE = /\b(waterfalls?|cascades?|rain|downpour|drizzle|sea|ocean|surf|waves?|breakers|rapids|river|torrent|spray|shower|sizzl\w*|steam)\b/i;
+/** What is wrong with a bed or loop being hiss: nothing for a loop on a thing that hisses by nature. A bed under the whole game still may not. */
+export const hissProblem = (pcm: Pcm, kind: Kind, prompt: string) => (!(kind === 'loop' && HISS_BY_NATURE.test(prompt)) && hissy(pcm) ? 'mostly hiss' : '');
+/**
+ * What the next take asks for, from what was wrong with the last one: only a hissy take is asked for no hiss. Asking
+ * a quiet one to be "gentle and quiet" (or even "clearly audible": the level does not follow the words) does not help.
+ */
+export function retakePrompt(prompt: string, take: number, problem: string): string {
+  if (take === 1) return prompt;
+  return prompt + STEADY + (/hiss/.test(problem) ? NO_HISS : '');
+}
+const LENGTH: Record<Exclude<Kind, 'shot'>, number> = { music: 30, bed: 20, loop: 10, step: 6 };
+/** Draft lengths: ElevenLabs bills effects by the second, and a seamless loop repeats fine at half the length. */
+const DRAFT: Record<Exclude<Kind, 'shot'>, number> = { music: 30, bed: 10, loop: 6, step: 4 };
+const length = (kind: Exclude<Kind, 'shot'>) => (soundQuality() === 'final' ? LENGTH : DRAFT)[kind];
+
+/** Sounds that do not belong to one world: footsteps per surface and the UI one-shots. Drafts reuse them across worlds. */
+const GENERIC = /^(step-.+|shot-(take|click|talk|ending))$/;
+const libraryFile = (id: string, prompt: string, ext: string) => sharedDir('library', `${id}-${inputHash(prompt)}.${ext}`);
+
+function fromLibrary(job: Job): Made | undefined {
+  const { id, prompt, kind, level } = job;
+  if (!GENERIC.test(id)) return undefined;
+  try {
+    const entry = JSON.parse(fs.readFileSync(libraryFile(id, prompt, 'json'), 'utf8')) as Made['entry'];
+    if (entry.prompt !== prompt || entry.kind !== kind || entry.validation !== AUDIO_VALIDATION
+      || (soundQuality() === 'final' && entry.quality !== 'final')) return undefined;
+    return { mp3: fs.readFileSync(libraryFile(id, prompt, 'mp3')), entry: { ...entry, level, source: `library (${entry.source})` } };
+  } catch { return undefined; }
+}
+
+/** A world's own generic sound joins the library too, so the next world in draft reuses it. */
+export function seedLibrary(id: string, entry: SoundEntry, mp3: Buffer) {
+  if (entry.validation === AUDIO_VALIDATION) toLibrary(id, { mp3, entry });
+}
+
+function toLibrary(id: string, made: Made) {
+  if (!GENERIC.test(id) || made.entry.flags.length || made.entry.source.startsWith('library')) return;
+  fs.mkdirSync(path.dirname(libraryFile(id, made.entry.prompt, 'mp3')), { recursive: true });
+  fs.writeFileSync(libraryFile(id, made.entry.prompt, 'mp3'), made.mp3);
+  fs.writeFileSync(libraryFile(id, made.entry.prompt, 'json'), JSON.stringify(made.entry));
+}
+const STEADY = ', continuous and steady throughout, no single standout events, no silence, seamless loop';
+
+/** `retake`: rounds of takes asked for again (sound_redo); each round asks for new takes instead of replaying cached ones. */
+export type Job = { id: string; kind: Kind; prompt: string; seconds: number; level: number; retake?: number };
+
+/** The sounds a plan asks for, with the person's hints (sound/fixes.json) added to their prompts. */
+export function jobsOf(plan: SoundPlan, fixes: SoundFixes = {}): Job[] {
+  return planJobs(plan).map((j) => {
+    const fix = fixes[j.id];
+    return fix ? { ...j, ...(fix.hint && { prompt: `${j.prompt}. ${fix.hint}` }), ...(fix.take && { retake: fix.take }) } : j;
+  });
+}
+
+function planJobs(plan: SoundPlan): Job[] {
+  const jobs: Job[] = [{ id: soundIds.music(), kind: 'music', prompt: plan.music.prompt, seconds: length('music'), level: 2 }];
+  for (const [place, p] of Object.entries(plan.places)) {
+    jobs.push({ id: soundIds.bed(place), kind: 'bed', prompt: p.bed, seconds: length('bed'), level: 2 });
+    for (const loop of p.loops) jobs.push({ id: soundIds.loop(place, loop.thing), kind: 'loop', prompt: loop.prompt, seconds: length('loop'), level: loop.level });
+  }
+  for (const [surface, prompt] of Object.entries(plan.steps)) jobs.push({ id: soundIds.step(surface), kind: 'step', prompt, seconds: length('step'), level: 2 });
+  for (const shot of plan.shots) jobs.push({ id: soundIds.shot(shot.on), kind: 'shot', prompt: shot.prompt, seconds: shot.seconds, level: shot.level });
+  return jobs;
+}
+
+type Made = { mp3: Buffer; entry: Omit<SoundEntry, 'file'> };
+
+async function makeOne(memo: Memo, job: Job, music: { python?: string }): Promise<Made> {
+  const flags: string[] = [];
+  const entry = (pcm: Pcm, source: string, extra: Partial<SoundEntry> = {}): Made => ({
+    mp3: encodeMp3(pcm, job.kind === 'step' || job.kind === 'shot' ? 160 : 128),
+    entry: { kind: job.kind, level: job.level, seconds: Math.round(seconds(pcm) * 1000) / 1000, source, prompt: job.prompt, flags, quality: soundQuality(), validation: AUDIO_VALIDATION, ...extra },
+  });
+
+  if (job.kind === 'music') {
+    // Meta's MusicGen when Python is set up for it; otherwise ElevenLabs music.
+    const raw = music.python
+      ? await musicgen(memo, job.id, job.prompt, job.seconds, music.python)
+      : await elevenMusic(memo, job.id, job.prompt, job.seconds);
+    const decoded = decode(raw);
+    const problem = audioProblem(decoded);
+    if (problem) throw new Error(`music rejected: ${problem}`);
+    const pcm = normalise(seamless(decoded, 3), TARGET_DB.music);
+    return entry(pcm, music.python ? MUSICGEN_MODEL : 'elevenlabs-music');
+  }
+
+  if (job.kind === 'bed' || job.kind === 'loop') {
+    let problem = '';
+    const round = 3 * (job.retake ?? 0);
+    for (let take = 1; take <= 3; take++) {
+      const prompt = retakePrompt(job.prompt, take, problem);
+      const ask: EffectAsk = { label: `${job.id}-${round + take}`, prompt, seconds: job.seconds, loop: true, take: round + take };
+      const pcm = decode(await soundEffect(memo, ask));
+      problem = audioProblem(pcm) ?? loopProblem(pcm, { beats: job.kind === 'loop' }) ?? hissProblem(pcm, job.kind, job.prompt);
+      if (problem) forgetEffect(memo, ask);
+      if (!problem) return entry(normalise(seamless(pcm, job.kind === 'bed' ? 1.5 : 0.8), TARGET_DB[job.kind]), 'elevenlabs', { mix: MIX });
+    }
+    throw new Error(`loop rejected after 3 takes: ${problem}`);
+  }
+
+  if (job.kind === 'step') {
+    const round = 2 * (job.retake ?? 0);
+    let pcm = decode(await soundEffect(memo, { label: job.id, prompt: job.prompt, seconds: job.seconds, loop: false, ...(round ? { take: round + 1 } : {}) }));
+    let slices = audioProblem(pcm) ? [] : steps(pcm);
+    if (slices.length < 3) {
+      const retry = decode(await soundEffect(memo, { label: `${job.id}-${round + 2}`, prompt: `${job.prompt}, clearly separated single footsteps with short pauses`, seconds: job.seconds, loop: false, take: round + 2 }));
+      const again = audioProblem(retry) ? [] : steps(retry);
+      flags.push(`first take had ${slices.length} separate steps${again.length > slices.length ? ', second take used' : ''}`);
+      if (again.length > slices.length) [pcm, slices] = [retry, again];
+    }
+    if (slices.length < 2) throw new Error(`footsteps rejected: only ${slices.length} separate steps`);
+    const problem = audioProblem(pcm);
+    if (problem) throw new Error(`footsteps rejected: ${problem}`);
+    return entry(normalise(pcm, TARGET_DB.step), 'elevenlabs', { slices });
+  }
+
+  let problem = '';
+  for (let take = 1; take <= 2; take++) {
+    const t = 2 * (job.retake ?? 0) + take;
+    const ask: EffectAsk = { label: `${job.id}-${t}`, prompt: job.prompt, seconds: job.seconds, loop: false, take: t };
+    const pcm = trim(decode(await soundEffect(memo, ask)));
+    problem = audioProblem(pcm) ?? '';
+    if (problem) forgetEffect(memo, ask);
+    if (!problem) return entry(normalise(pcm, TARGET_DB.shot), 'elevenlabs');
+  }
+  throw new Error(`effect rejected: ${problem}`);
+}
+
+/** Runs `jobs` a few at a time. */
+async function pool<T, R>(items: T[], size: number, run: (item: T) => Promise<R>): Promise<R[]> {
+  const out: R[] = new Array(items.length);
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(size, items.length) }, async () => {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await run(items[i]);
+    }
+  }));
+  return out;
+}
+
+/**
+ * Makes the plan's sounds. A sound the world already has (same id, kind and prompt, file present, at least this
+ * quality) is kept as it is: a rebuild pays only for what the plan changed.
+ */
+export async function makeSounds(memo: Memo, plan: SoundPlan, write: (id: string, mp3: Buffer) => string, opts: { python?: string; only?: Kind[]; ids?: string[]; fixes?: SoundFixes; log?: (line: string) => void; have?: (entry: SoundEntry) => boolean; old?: Record<string, SoundEntry>; failedBefore?: Record<string, string> }): Promise<SoundManifest> {
+  if (!elevenKey()) throw new Error('no ElevenLabs key: set ELEVENLABS_API_KEY to generate sounds (the plan is written without it)');
+  const sounds: Record<string, SoundEntry> = {};
+  const failures: Record<string, string> = {};
+  const jobs = jobsOf(plan, opts.fixes).filter((j) => (!opts.only || opts.only.includes(j.kind)) && (!opts.ids || opts.ids.includes(j.id))).filter((j) => {
+    const old = opts.old?.[j.id];
+    // A sound asked for by id (sound_redo) is made again even when its prompt did not change.
+    const keep = !opts.ids && old && old.validation === AUDIO_VALIDATION && old.kind === j.kind && old.prompt === j.prompt && (old.quality === 'final' || soundQuality() === 'draft') && ((j.kind !== 'bed' && j.kind !== 'loop') || (old.mix ?? 0) >= MIX) && opts.have?.(old);
+    if (keep) sounds[j.id] = old;
+    return !keep;
+  });
+  if (Object.keys(sounds).length) opts.log?.(`  ${Object.keys(sounds).length} sounds kept from the last run (prompt unchanged)`);
+  // Rejected last time: say so, since this run asks for new takes (the rejected ones were forgotten) and pays again.
+  const again = jobs.filter((j) => opts.failedBefore?.[j.id]);
+  if (again.length) opts.log?.(`  ${again.length} sounds rejected last time, asked for new takes: ${again.map((j) => `${j.id} (${opts.failedBefore![j.id]})`).join('; ')}`);
+  let completed = 0;
+  const kept = Object.keys(sounds).length;
+  const progress = () => emit('work.progress', { kind: 'sounds', completed, total: jobs.length, failed: Object.keys(failures).length, kept });
+  progress();
+  await pool(jobs, 3, async (job) => {
+    try {
+      const made = fromLibrary(job) ?? (await makeOne(memo, job, { python: opts.python }));
+      toLibrary(job.id, made);
+      sounds[job.id] = { file: write(job.id, made.mp3), ...made.entry };
+      opts.log?.(`  ${job.id.padEnd(34)} ${made.entry.seconds.toFixed(1).padStart(5)} s${made.entry.slices ? `, ${made.entry.slices.length} steps` : ''}${made.entry.flags.length ? `  flag: ${made.entry.flags.join('; ')}` : ''}`);
+    } catch (error) {
+      failures[job.id] = error instanceof Error ? error.message : String(error);
+      opts.log?.(`  ${job.id.padEnd(34)} FAILED, stays silent: ${error instanceof Error ? error.message : error}`);
+    } finally {
+      completed++;
+      progress();
+    }
+  });
+  return { sounds, failures };
+}

package/app/src/sound/musicgen.py

@@ -0,0 +1,20 @@
+# MusicGen (Meta, open weights) on CPU: python musicgen.py <model> "<prompt>" <seconds> <out.wav>
+# Needs torch, transformers and scipy; the sound step runs it through DIORAMA_PYTHON.
+import sys
+
+import scipy.io.wavfile
+import torch
+from transformers import AutoProcessor, MusicgenForConditionalGeneration
+
+model_id, prompt, seconds, out = sys.argv[1], sys.argv[2], float(sys.argv[3]), sys.argv[4]
+torch.manual_seed(7)
+processor = AutoProcessor.from_pretrained(model_id)
+model = MusicgenForConditionalGeneration.from_pretrained(model_id)
+inputs = processor(text=[prompt], padding=True, return_tensors="pt")
+# MusicGen makes about 50 tokens per second of audio.
+tokens = int(seconds * model.config.audio_encoder.frame_rate)
+with torch.no_grad():
+    audio = model.generate(**inputs, do_sample=True, guidance_scale=3.0, max_new_tokens=tokens)
+rate = model.config.audio_encoder.sampling_rate
+scipy.io.wavfile.write(out, rate=rate, data=audio[0, 0].numpy())
+print(f"musicgen: {audio.shape[-1] / rate:.1f} s at {rate} Hz -> {out}", file=sys.stderr)

package/app/src/sound/pcm.ts

@@ -0,0 +1,280 @@
+// Audio as plain samples: ffmpeg decodes and encodes, everything else (loop checks, seams, slicing steps) is code.
+import { execFileSync } from 'node:child_process';
+
+export const RATE = 44100;
+
+/** Interleaved stereo float samples at RATE. */
+export type Pcm = { left: Float32Array; right: Float32Array };
+
+function ffmpeg(args: string[], input: Buffer): Buffer {
+  try {
+    return execFileSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', ...args], { input, maxBuffer: 1 << 30 });
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') throw new Error('the sound step needs ffmpeg on PATH (brew install ffmpeg / apt install ffmpeg)');
+    throw error;
+  }
+}
+
+export function decode(audio: Buffer): Pcm {
+  const raw = ffmpeg(['-i', 'pipe:0', '-f', 'f32le', '-ac', '2', '-ar', String(RATE), 'pipe:1'], audio);
+  const all = new Float32Array(raw.buffer, raw.byteOffset, raw.byteLength / 4);
+  const n = all.length / 2;
+  const left = new Float32Array(n);
+  const right = new Float32Array(n);
+  for (let i = 0; i < n; i++) (left[i] = all[2 * i]), (right[i] = all[2 * i + 1]);
+  return { left, right };
+}
+
+export function encodeMp3(pcm: Pcm, kbps = 128): Buffer {
+  const n = pcm.left.length;
+  const all = new Float32Array(n * 2);
+  for (let i = 0; i < n; i++) (all[2 * i] = pcm.left[i]), (all[2 * i + 1] = pcm.right[i]);
+  return ffmpeg(['-f', 'f32le', '-ac', '2', '-ar', String(RATE), '-i', 'pipe:0', '-c:a', 'libmp3lame', '-b:a', `${kbps}k`, '-f', 'mp3', 'pipe:1'], Buffer.from(all.buffer));
+}
+
+/**
+ * Raises (or lowers) the pitch by `semitones` and keeps the length: a young adult voice read a few semitones up
+ * sounds like a child, which no stock voice does.
+ */
+export function pitchShift(pcm: Pcm, semitones: number): Pcm {
+  if (!semitones) return pcm;
+  const r = 2 ** (semitones / 12);
+  const n = pcm.left.length;
+  const all = new Float32Array(n * 2);
+  for (let i = 0; i < n; i++) (all[2 * i] = pcm.left[i]), (all[2 * i + 1] = pcm.right[i]);
+  const out = ffmpeg(['-f', 'f32le', '-ac', '2', '-ar', String(RATE), '-i', 'pipe:0', '-af', `asetrate=${Math.round(RATE * r)},aresample=${RATE},atempo=${(1 / r).toFixed(5)}`, '-f', 'f32le', '-ac', '2', '-ar', String(RATE), 'pipe:1'], Buffer.from(all.buffer));
+  const f = new Float32Array(out.buffer, out.byteOffset, out.byteLength / 4);
+  const m = f.length / 2;
+  const left = new Float32Array(m);
+  const right = new Float32Array(m);
+  for (let i = 0; i < m; i++) (left[i] = f[2 * i]), (right[i] = f[2 * i + 1]);
+  return { left, right };
+}
+
+export const seconds = (pcm: Pcm) => pcm.left.length / RATE;
+
+/** Objective recording defects, before normalisation can disguise silence or clipping. */
+export function audioProblem(pcm: Pcm): string | undefined {
+  if (pcm.left.length !== pcm.right.length || seconds(pcm) < 0.08) return 'empty or too short';
+  let energy = 0, clipped = 0;
+  for (const channel of [pcm.left, pcm.right]) for (const v of channel) {
+    if (!Number.isFinite(v)) return 'non-finite audio samples';
+    energy += v * v;
+    if (Math.abs(v) >= 0.999) clipped++;
+  }
+  const count = pcm.left.length * 2;
+  if (Math.sqrt(energy / count) < 0.0001) return 'nearly silent';
+  if (clipped / count > 0.01) return 'clipped recording';
+  return undefined;
+}
+
+/**
+ * The median pitch of a voice in Hz (autocorrelation over voiced 40 ms frames): about 100-130 for a man,
+ * 180-230 for a woman, 260 and up for a child. 0 when nothing voiced is found.
+ */
+export function pitchHz(pcm: Pcm): number {
+  const step = 3; // 44.1 kHz down to 14.7 kHz is plenty for 70-500 Hz
+  const sr = RATE / step;
+  const x = new Float32Array(Math.floor(pcm.left.length / step)).map((_, i) => (pcm.left[i * step] + pcm.right[i * step]) / 2);
+  const w = Math.round(sr * 0.04);
+  const lo = Math.floor(sr / 500);
+  const hi = Math.ceil(sr / 70);
+  const found: number[] = [];
+  for (let at = 0; at + w + hi < x.length; at += w >> 1) {
+    let energy = 0;
+    for (let i = 0; i < w; i++) energy += x[at + i] ** 2;
+    if (Math.sqrt(energy / w) < 0.02) continue;
+    let best = 0;
+    let lag = 0;
+    for (let k = lo; k <= hi; k++) {
+      let sum = 0;
+      for (let i = 0; i < w; i++) sum += x[at + i] * x[at + i + k];
+      if (sum > best) (best = sum), (lag = k);
+    }
+    if (lag && best > 0.4 * energy) found.push(sr / lag);
+  }
+  return Math.round(quantile(found, 0.5));
+}
+
+/** RMS per window of `ms`, both channels. */
+export function envelope(pcm: Pcm, ms: number): number[] {
+  const w = Math.max(1, Math.round((RATE * ms) / 1000));
+  const out: number[] = [];
+  for (let at = 0; at + w <= pcm.left.length; at += w) {
+    let sum = 0;
+    for (let i = at; i < at + w; i++) sum += pcm.left[i] ** 2 + pcm.right[i] ** 2;
+    out.push(Math.sqrt(sum / (2 * w)));
+  }
+  return out;
+}
+
+function quantile(values: number[], q: number) {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))] ?? 0;
+}
+
+/**
+ * Whether a take meant to loop is really one event (a crash, a single gust) with silence around it.
+ * A loop needs sound all the way through: its quiet windows stay near its loud ones, and neither end dies out.
+ */
+export function loopProblem(pcm: Pcm, opts: { beats?: boolean } = {}): string | undefined {
+  const env = envelope(pcm, 100);
+  if (env.length < 10) return 'shorter than a second';
+  const median = quantile(env, 0.5);
+  // ElevenLabs makes a room hum or distant birds at -50..-65 dBFS; levelling raises them to the bed's loudness, so only
+  // takes with nothing in them fail here (a classroom hum peaking at 0.002 was a usable bed, not silence).
+  if (Math.max(...env) < 0.0005) return 'nearly silent';
+  // A thing's own loop may be a beat (a clock ticking, a drip, a blinker): even events with quiet between are its sound.
+  if (opts.beats && regularBeats(pcm)) return undefined;
+  // Most of the take far under its loudest moments: an event in silence, not a bed.
+  const steady = median / quantile(env, 0.98);
+  if (steady < 0.06) return `one event and silence, not a bed (median/peak ${steady.toFixed(2)})`;
+  const ends = Math.max(3, Math.round(env.length * 0.1));
+  const head = env.slice(0, ends).reduce((a, b) => a + b, 0) / ends;
+  const tail = env.slice(-ends).reduce((a, b) => a + b, 0) / ends;
+  if (tail < median * 0.25) return `dies out at the end (${(tail / median).toFixed(2)} of its median)`;
+  if (head < median * 0.25) return `fades in from silence (${(head / median).toFixed(2)} of its median)`;
+  return undefined;
+}
+
+/** Four or more clear events at an even pace (gaps within 30% of their mean): ticking, not one event in silence. */
+export function regularBeats(pcm: Pcm): boolean {
+  const env = envelope(pcm, 20);
+  const peak = quantile(env, 0.98);
+  if (peak < 0.003) return false;
+  const onsets: number[] = [];
+  let armed = true;
+  env.forEach((v, i) => {
+    if (armed && v > peak * 0.4) {
+      onsets.push(i);
+      armed = false;
+    } else if (v < peak * 0.15) armed = true;
+  });
+  if (onsets.length < 4) return false;
+  const gaps = onsets.slice(1).map((o, i) => o - onsets[i]);
+  const mean = gaps.reduce((a, b) => a + b, 0) / gaps.length;
+  const spread = Math.sqrt(gaps.reduce((a, g) => a + (g - mean) ** 2, 0) / gaps.length);
+  return mean >= 5 && spread / mean < 0.3;
+}
+
+/** How much of the sound is hiss: the energy of the change from sample to sample over the energy (white noise 2, music about 0.06). */
+export function hiss(pcm: Pcm): number {
+  let e = 0, d = 0;
+  for (let i = 1; i < pcm.left.length; i++) {
+    const x = (pcm.left[i] + pcm.right[i]) / 2;
+    const y = (pcm.left[i - 1] + pcm.right[i - 1]) / 2;
+    e += x * x;
+    d += (x - y) ** 2;
+  }
+  return e > 0 ? d / e : 0;
+}
+
+/**
+ * How much of the sound's high end is tones rather than noise: the share of loud 12 ms frames whose sample-to-sample
+ * change repeats itself (autocorrelation over 2-80 samples above 0.5). Crickets, birdsong and a whistle are tones and
+ * score high; hiss, air and rustle have no period and score near 0. `hiss` alone cannot tell them apart: a cricket
+ * at 4.5 kHz changes from sample to sample as much as white noise does.
+ */
+export function tonalShare(pcm: Pcm): number {
+  const N = 512;
+  const frames: Array<{ e: number; tonal: boolean }> = [];
+  for (let at = 1; at + N <= pcm.left.length; at += N) {
+    const d = new Float32Array(N);
+    for (let i = 0; i < N; i++) d[i] = (pcm.left[at + i] + pcm.right[at + i] - pcm.left[at + i - 1] - pcm.right[at + i - 1]) / 2;
+    let e = 0;
+    for (const v of d) e += v * v;
+    if (e <= 0) continue;
+    let best = 0;
+    for (let lag = 2; lag <= 80; lag++) {
+      let r = 0;
+      for (let i = lag; i < N; i++) r += d[i] * d[i - lag];
+      best = Math.max(best, r / e);
+    }
+    frames.push({ e, tonal: best > 0.5 });
+  }
+  if (!frames.length) return 0;
+  // Only frames that carry the sound count: the quiet gaps between chirps are noise floor.
+  const loud = frames.filter((f) => f.e >= frames.map((x) => x.e).sort((a, b) => a - b)[Math.floor(frames.length / 2)]);
+  return loud.filter((f) => f.tonal).length / loud.length;
+}
+
+/** Takes off what is above `hz`: two passes of a one-pole low-pass, each way. */
+export function lowpass(pcm: Pcm, hz: number): Pcm {
+  const a = Math.exp((-2 * Math.PI * hz) / RATE);
+  const pass = (ch: Float32Array) => {
+    const out = Float32Array.from(ch);
+    for (let k = 0; k < 2; k++) {
+      let y = out[0];
+      for (let i = 0; i < out.length; i++) out[i] = y = (1 - a) * out[i] + a * y;
+      y = out[out.length - 1];
+      for (let i = out.length - 1; i >= 0; i--) out[i] = y = (1 - a) * out[i] + a * y;
+    }
+    return out;
+  };
+  return { left: pass(pcm.left), right: pass(pcm.right) };
+}
+
+/** Folds the last `fade` seconds over the start with an equal-power crossfade, so the take repeats without a seam. */
+export function seamless(pcm: Pcm, fade = 1): Pcm {
+  const f = Math.min(Math.round(fade * RATE), Math.floor(pcm.left.length / 3));
+  const len = pcm.left.length - f;
+  const fold = (ch: Float32Array) => {
+    const out = new Float32Array(len);
+    out.set(ch.subarray(0, len));
+    // The tail [len, len+f) fades out over the head [0, f): playing out[len-1] then out[0] continues the original.
+    for (let i = 0; i < f; i++) {
+      const t = (i + 0.5) / f;
+      out[i] = ch[i] * Math.sin((t * Math.PI) / 2) + ch[len + i] * Math.cos((t * Math.PI) / 2);
+    }
+    return out;
+  };
+  return { left: fold(pcm.left), right: fold(pcm.right) };
+}
+
+/** Scales to a target RMS (dBFS) and keeps peaks under -1 dBFS, so every sound starts at a known level. */
+export function normalise(pcm: Pcm, targetDb: number): Pcm {
+  const env = envelope(pcm, 50).filter((v) => v > 1e-4);
+  const rms = env.length ? Math.sqrt(env.reduce((a, b) => a + b * b, 0) / env.length) : 0;
+  if (!rms) return pcm;
+  let peak = 0;
+  for (let i = 0; i < pcm.left.length; i++) peak = Math.max(peak, Math.abs(pcm.left[i]), Math.abs(pcm.right[i]));
+  const gain = Math.min(10 ** (targetDb / 20) / rms, 0.89 / peak);
+  return { left: pcm.left.map((v) => v * gain), right: pcm.right.map((v) => v * gain) };
+}
+
+/** Trims silence from both ends, leaving a few ms. */
+export function trim(pcm: Pcm, floor = 0.01): Pcm {
+  const env = envelope(pcm, 5);
+  const max = Math.max(...env, 1e-9);
+  const first = env.findIndex((v) => v > max * floor);
+  const last = env.length - 1 - [...env].reverse().findIndex((v) => v > max * floor);
+  const w = Math.round(RATE * 0.005);
+  const from = Math.max(0, (first - 2) * w);
+  const to = Math.min(pcm.left.length, (last + 3) * w);
+  return { left: pcm.left.slice(from, to), right: pcm.right.slice(from, to) };
+}
+
+/**
+ * Single footsteps in a take of several: onsets where the 10 ms envelope jumps above a share of its peak,
+ * each cut until just before the next one (at most `max` seconds). Returns [start, duration] in seconds.
+ */
+export function steps(pcm: Pcm, max = 0.45): Array<[number, number]> {
+  const ms = 10;
+  const env = envelope(pcm, ms);
+  const peak = Math.max(...env, 1e-9);
+  const onsets: number[] = [];
+  let last = -Infinity;
+  for (let i = 1; i < env.length; i++) {
+    const rising = env[i] > peak * 0.25 && env[i] > env[i - 1] * 1.8;
+    if (rising && i - last > 200 / ms) {
+      onsets.push(i);
+      last = i;
+    }
+  }
+  return onsets.map((on, k) => {
+    const start = Math.max(0, on - 2) * ms / 1000;
+    const next = k + 1 < onsets.length ? (onsets[k + 1] - 3) * ms / 1000 : seconds(pcm);
+    return [Math.round(start * 1000) / 1000, Math.round(Math.min(max, next - start) * 1000) / 1000] as [number, number];
+  }).filter(([, d]) => d >= 0.12);
+}