@crievo/omni 0.0.0-stage → 0.1.0

package/tools/sound.mjs

@@ -0,0 +1,1323 @@
+#!/usr/bin/env node
+/* ============================================================================
+   Sound effects: on beats, on transitions, and the video's bed.
+
+     node tools/sound.mjs capture [n]                     prints the capture code (Chrome)
+     node tools/sound.mjs download videos/<slug> <url> [name] [--search <term>]
+     node tools/sound.mjs download kit <url> <name> --role <role> [--search <term>]
+     node tools/sound.mjs kit [role|text]                 lists the global kit by role
+     node tools/sound.mjs kit adopt videos/<slug> <name> --role <role> [--as <name-in-kit>]
+                                                          moves an effect captured for the video into the kit
+     node tools/sound.mjs effects videos/<slug> [text]    lists the effects captured for the video
+     node tools/sound.mjs videos/<slug>                   prepares the video's sound/
+
+   Every effect comes from Epidemic Sound, through one of two registries: the
+   global kit (sound.kit in the config, kit/sfx/kit.json), curated once and used
+   by every video, each effect with a role (click, pop, tick, typing, confirm,
+   whoosh, transition, riser, impact, glitch, bed, texture); and the video's
+   sfx/ (sfx/sources.json), for what the kit lacks. No other audio saved on the
+   computer gets in. With a search open in Chrome (sound.source.search in the
+   config), the `capture` code plays the previews and returns each one's URL
+   (audiocdn.epidemicsound.com/lqmp3/<id>.mp3); `download` writes the MP3 to
+   the kit or the video's sfx/ and records the origin. An effect outside both
+   registries is refused. The name is looked up in the video first, then in the
+   kit. From the kit, the effect brings its role's volume (sound.roles in the
+   config, or its own `db` in kit.json), added to the sound's `db`.
+
+   Where sound goes in scenes.json:
+     beat.sound               at the beat's instant
+     scene.transition.sound   at the cut that opens the scene ({ "sound": … }, with or without continues)
+     bed                      at the root: one track under the video (music or texture)
+
+   `sound` is a file name in sfx/, an object with adjustments, or a list of
+   them (layers at the same instant):
+
+     "sound": "clique-seco.mp3"
+     "sound": { "name": "whoosh-curto.mp3", "offset": 0.3, "db": -3 }
+     "sound": [{ "name": "whoosh.mp3", "anchor": "start", "dur": 1.8 },
+               { "name": "impacto.mp3", "offset": 1.8 }]
+
+     name       file in sfx/
+     anchor     "peak" (default) or "start": which point of the effect lands on the instant
+     offset     seconds after the instant (negative: before)
+     db         adjustment over the default level (sound.level_db)
+     trim       [from, to] in seconds inside the file; `to` null = up to the
+                audible tail (the default is the whole file up to it)
+     fade       [in, out] in seconds
+     dur        stretches or shrinks the trim to last this long (pitch kept)
+     speed      speed factor (1.5 = faster); `dur` takes precedence
+     pitch      semitones (+ higher, − lower), without changing duration
+     duck       dB of ducking under the voice for this effect only (false: none)
+
+   bed: { "name", "db", "from", "to", "trim", "fade", "loop", "duck", "speed" }:
+   `from`/`to` in seconds of video (default: the whole video), `loop` repeats
+   the trim until it covers (texture; not music), `speed` (0.5 to 2) plays the
+   music faster with its pitch kept; it is the bed's own, apart from the
+   export speed, which never touches the bed.
+
+   Volume: the effect is measured after being trimmed and processed, by
+   perceived loudness (BS.1770 K-weighting over a sound.window_s window), not
+   by peak. With `db` 0 it sits sound.level_db below the video voice's
+   integrated loudness; the bed, sound.bed.level_db below, measured by its own
+   integrated loudness. While the voice speaks, effects drop sound.ducking.db
+   and the bed sound.bed.ducking_db. Since assembly normalizes the mix by the
+   voice, the final effect level is the same from one video to another.
+
+   Per-line level: with sound.voice_target_lufs, each line is measured
+   (integrated loudness) and brought to that level by a gain applied in the mix
+   (assembly, preview and sound/preview.wav); the file in voice/ does not change.
+   The gain is limited to ±sound.voice_max_gain_db and never pushes the peak above
+   sound.max_peak_db. This keeps Fish, Cartesia and VoiceStudio, or a redone line,
+   at the same loudness inside the video; assembly's −14 LUFS stays a single gain at the end.
+
+   Writes sound/<id>.wav for each effect, already trimmed, processed, leveled
+   and ducked (id: <scene>-<element>, <scene>-transition, -2, -3… for layers),
+   sound/bed.wav, and sound/plan.json with the second each one starts. Premiere
+   only places them (premiere.mjs assemble, track `sound.premiere_track`, the
+   bed on the next one). sound/preview.wav mixes voice, effects and bed in final
+   timing. From the command line, preparing sound/ waits for the machine's
+   queue turn (tools/job-queue.mjs).
+   ============================================================================ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve, basename, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadVideo, beatTime } from "./timing.mjs";
+import { animationStart, animationInstant, voiceSpans, lineClips, sanitizeClips } from "./soundtrack.mjs";
+import { turn } from "./job-queue.mjs";
+import { isNarrated } from "./lib/narration.mjs";
+import { keepPrevious } from "./history.mjs";
+import { normalizeCuts, removedDuration, toEdited } from "./cuts.mjs";
+import { CODE_ROOT, isMainModule, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
+const S = {
+  level_db: -14,
+  default_voice_lufs: -18,
+  voice_target_lufs: null,
+  voice_max_gain_db: 6,
+  window_s: 0.2,
+  max_peak_db: -1,
+  ...CFG.sound,
+  ducking: { db: -6, before: 0.06, after: 0.25, min_gap: 0.35, ...CFG.sound?.ducking },
+  bed: { level_db: -24, ducking_db: -8, fade: [1, 1.5], ...CFG.sound?.bed },
+};
+/* role of each kit effect: the default volume (added to the sound's `db`) and
+   whether it can be stretched (whoosh yes, impact no) */
+const ROLES = {
+  click: { db: -4 },
+  pop: { db: -4 },
+  tick: { db: -8 },
+  typing: { db: -8 },
+  confirm: { db: -4 },
+  whoosh: { db: 0, stretchable: true },
+  transition: { db: 0, stretchable: true },
+  riser: { db: 0, stretchable: true },
+  impact: { db: -2 },
+  glitch: { db: -4 },
+  bed: { db: 0 },
+  texture: { db: 0, stretchable: true },
+  ...CFG.sound?.roles,
+};
+const KIT = resolve(ROOT, CFG.sound?.kit ?? "kit/sfx");
+const CDN = /^https:\/\/audiocdn\.epidemicsound\.com\/lqmp3\/([0-9A-Za-z]+)\.mp3$/;
+const NAME = /^[a-z0-9][a-z0-9._-]*\.mp3$/i;
+const MUSIC_S = 30; /* above this it is a soundtrack, not an effect (the bed may) */
+const RATE = 48000;
+
+function run(bin, args, binary = false) {
+  const r = spawnSync(bin, args, { maxBuffer: 1 << 30, encoding: binary ? "buffer" : "utf8" });
+  if (r.status !== 0) throw new Error(`${bin}: ${String(r.stderr).slice(-500)}`);
+  return r.stdout;
+}
+
+/* --- decode --------------------------------------------------------------------
+   Interleaved stereo, 48 kHz, float: the same format as the WAV that goes to
+   the timeline (with less bandwidth, a click's high transient disappears and the
+   "peak" becomes the body of the sound, tens of ms later). Trim with atrim, never
+   -ss before -i: seeking in an MP3 discards the encoder delay differently from
+   decoding from the start, and the peak lands ~23 ms off. */
+function atempo(f) {
+  const out = [];
+  while (f > 2) {
+    out.push(2);
+    f /= 2;
+  }
+  while (f < 0.5) {
+    out.push(0.5);
+    f /= 0.5;
+  }
+  if (Math.abs(f - 1) > 1e-4) out.push(f);
+  return out.map(x => `atempo=${+x.toFixed(6)}`);
+}
+
+/* cached by file, mtime and adjustments (the studio timeline replans on every
+   change); callers never modify the buffer in place, trimming always copies */
+const decodeCache = new Map();
+function decode(file, options = {}) {
+  const k = `${file}@${statSync(file).mtimeMs}@${JSON.stringify(options)}`;
+  if (decodeCache.has(k)) {
+    const x = decodeCache.get(k);
+    decodeCache.delete(k);
+    decodeCache.set(k, x);
+    return x;
+  }
+  const x = decodeNow(file, options);
+  decodeCache.set(k, x);
+  if (decodeCache.size > 48) decodeCache.delete(decodeCache.keys().next().value);
+  return x;
+}
+
+function decodeNow(file, { from = 0, to = null, speed = 1, pitch = 0 } = {}) {
+  const r = 2 ** (pitch / 12);
+  const af = [`aresample=${RATE}`];
+  if (from > 0 || to != null) af.push(`atrim=start=${from}${to != null ? `:end=${to}` : ""}`, "asetpts=PTS-STARTPTS");
+  if (pitch) af.push(`asetrate=${Math.round(RATE * r)}`, `aresample=${RATE}`);
+  af.push(...atempo(speed / r));
+  const raw = run(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-i",
+      file,
+      "-af",
+      af.join(","),
+      "-ac",
+      "2",
+      "-ar",
+      String(RATE),
+      "-f",
+      "f32le",
+      "-",
+    ],
+    true,
+  );
+  return new Float32Array(raw.buffer.slice(raw.byteOffset, raw.byteOffset + Math.floor(raw.length / 4) * 4));
+}
+
+/* --- perceived loudness (BS.1770) -------------------------------------------------
+   K-weighting at 48 kHz, power per frame summed over both channels. */
+const K = [
+  { b: [1.53512485958697, -2.69169618940638, 1.19839281085285], a: [-1.69065929318241, 0.73248077421585] },
+  { b: [1, -2, 1], a: [-1.99004745483398, 0.99007225036621] },
+];
+function kPower(x) {
+  const n = x.length >> 1;
+  const p = new Float64Array(n);
+  for (let c = 0; c < 2; c++) {
+    let y = new Float64Array(n);
+    for (let i = 0; i < n; i++) y[i] = x[2 * i + c];
+    for (const { b, a } of K) {
+      const z = new Float64Array(n);
+      let x1 = 0,
+        x2 = 0,
+        y1 = 0,
+        y2 = 0;
+      for (let i = 0; i < n; i++) {
+        const v = b[0] * y[i] + b[1] * x1 + b[2] * x2 - a[0] * y1 - a[1] * y2;
+        x2 = x1;
+        x1 = y[i];
+        y2 = y1;
+        y1 = v;
+        z[i] = v;
+      }
+      y = z;
+    }
+    for (let i = 0; i < n; i++) p[i] += y[i] * y[i];
+  }
+  return p;
+}
+const lufs = ms => (ms > 0 ? -0.691 + 10 * Math.log10(ms) : -Infinity);
+
+/* loudest sliding window; a sound shorter than the window counts as followed by
+   silence, which is how the ear integrates a click */
+function maxLoudness(x, window = S.window_s) {
+  const p = kPower(x);
+  const w = Math.max(1, Math.round(window * RATE));
+  let sum = 0,
+    max = 0;
+  for (let i = 0; i < p.length; i++) {
+    sum += p[i];
+    if (i >= w) sum -= p[i - w];
+    if (sum > max) max = sum;
+  }
+  return lufs(max / w);
+}
+
+/* integrated loudness: 400 ms blocks with 100 ms step, −70 LUFS and −10 LU gates */
+function integratedLoudness(x) {
+  const p = kPower(x);
+  const w = Math.round(0.4 * RATE),
+    step = Math.round(0.1 * RATE);
+  const blocks = [];
+  for (let i = 0; i + w <= p.length; i += step) {
+    let s = 0;
+    for (let k = i; k < i + w; k++) s += p[k];
+    blocks.push(s / w);
+  }
+  if (!blocks.length) return maxLoudness(x, 0.4);
+  const abs = blocks.filter(b => lufs(b) > -70);
+  if (!abs.length) return -Infinity;
+  const rel = lufs(abs.reduce((s, b) => s + b, 0) / abs.length) - 10;
+  const kept = abs.filter(b => lufs(b) > rel);
+  return lufs(kept.reduce((s, b) => s + b, 0) / kept.length);
+}
+
+/* --- per-line level (see the header) ----------------------------------------------- */
+const levelCache = new Map();
+export function lineGain(file) {
+  const target = S.voice_target_lufs;
+  if (!Number.isFinite(target) || !existsSync(file)) return 0;
+  const k = `${file}@${statSync(file).mtimeMs}`;
+  if (!levelCache.has(k)) {
+    const x = decode(file);
+    levelCache.set(k, { lufs: integratedLoudness(x), peak_db: 20 * Math.log10(peakOf(x).amp) });
+  }
+  const { lufs: v, peak_db } = levelCache.get(k);
+  if (!Number.isFinite(v)) return 0;
+  const max = S.voice_max_gain_db;
+  const g = Math.min(Math.max(-max, Math.min(max, target - v)), Math.max(0, S.max_peak_db - peak_db));
+  return +g.toFixed(2);
+}
+
+function peakOf(x) {
+  let ip = 0;
+  for (let i = 1; i < x.length; i++) if (Math.abs(x[i]) > Math.abs(x[ip])) ip = i;
+  return { s: Math.floor(ip / 2) / RATE, amp: Math.abs(x[ip]) || 1e-9 };
+}
+
+/* --- measure an effect file ---------------------------------------------------
+   peak: the instant of the largest sample. useful_end: after it the sound stays
+   40 dB below the peak until the end (inaudible tail). volume: the loudest
+   perceived level (sound.window_s window) up to the useful end. */
+const cache = new Map();
+export function measureEffect(file) {
+  if (cache.has(file)) return cache.get(file);
+  const fmt = JSON.parse(run("ffprobe", ["-v", "error", "-print_format", "json", "-show_format", file])).format;
+  const duration = +fmt.duration;
+  const title = fmt.tags?.title ?? fmt.tags?.TITLE ?? "";
+  if (duration > MUSIC_S) {
+    const m = { duration, title, music: true };
+    cache.set(file, m);
+    return m;
+  }
+  const x = decode(file);
+  const { s: peak_s, amp } = peakOf(x);
+  let end = x.length - 1;
+  while (end > peak_s * RATE * 2 && Math.abs(x[end]) < amp * 0.01) end--;
+  const useful_end_s = +Math.min(duration, Math.floor(end / 2) / RATE + 0.05).toFixed(3);
+  const m = {
+    duration,
+    title,
+    music: false,
+    peak_s: +peak_s.toFixed(4),
+    peak_db: +(20 * Math.log10(amp)).toFixed(1),
+    useful_end_s,
+    volume_lufs: +maxLoudness(x.subarray(0, Math.round(useful_end_s * RATE) * 2)).toFixed(1),
+  };
+  cache.set(file, m);
+  return m;
+}
+
+/* --- where an effect comes from --------------------------------------------------
+   Only from Epidemic, through two registries: the global kit (sound.kit in the
+   config, kit/sfx/ with kit.json), curated once and used by every video, and
+   the video's sfx/ (sfx/sources.json), for sound the kit lacks. The name is
+   looked up in the video first, then in the kit. */
+const effectsDir = dir => join(resolve(dir), "sfx");
+const readJson = f => (existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : {});
+const sources = dir => readJson(join(effectsDir(dir), "sources.json"));
+const kitSources = () => readJson(join(KIT, "kit.json"));
+
+export function effectFile(dir, name) {
+  if (typeof name !== "string" || !NAME.test(name) || basename(name) !== name)
+    return { error: `efeito “${name}”: o nome é um MP3 do sfx/ do vídeo ou do kit (ex.: clique-seco.mp3)` };
+  const [from, source, where] = sources(dir)[name]
+    ? [effectsDir(dir), sources(dir)[name], "sfx/sources.json"]
+    : kitSources()[name]
+      ? [KIT, kitSources()[name], "o kit"]
+      : [];
+  if (!from)
+    return {
+      error: `efeito “${name}” não está no kit nem foi capturado da Epidemic para este vídeo (falta em sfx/sources.json): use um do kit (sound.mjs kit) ou capture com sound.mjs capture e download`,
+    };
+  const file = join(from, name);
+  if (!existsSync(file))
+    return { error: `efeito “${name}” está em ${where}, mas o arquivo sumiu: rode sound.mjs download de novo` };
+  return { file, kit: from === KIT ? source : null };
+}
+
+/* `download` destination: a video dir or the kit ("kit", with --role) */
+function destination(videoDir, role) {
+  if (videoDir === "kit") {
+    if (!ROLES[role]) throw new Error(`no kit, --role é obrigatório: ${Object.keys(ROLES).join(", ")}`);
+    return { dir: KIT, registry: join(KIT, "kit.json"), extra: { role } };
+  }
+  const dir = resolve(videoDir ?? "");
+  if (!existsSync(join(dir, "scenes.json")))
+    throw new Error(`${dir} não é a pasta de um vídeo (falta scenes.json) nem "kit"`);
+  return { dir: effectsDir(dir), registry: join(effectsDir(dir), "sources.json"), extra: {} };
+}
+
+async function download(videoDir, url, name, search, role) {
+  const { dir, registry, extra } = destination(videoDir, role);
+  const m = CDN.exec(url ?? "");
+  if (!m)
+    throw new Error(
+      `só URL da Epidemic capturada no player (https://audiocdn.epidemicsound.com/lqmp3/<id>.mp3), não “${url}”`,
+    );
+  name = `${(name ?? m[1]).replace(/\.mp3$/i, "")}.mp3`;
+  if (!NAME.test(name)) throw new Error(`nome “${name}”: letras, números, ponto, hífen e sublinhado`);
+  const list = readJson(registry);
+  const whereAlready = dir === KIT ? "no kit" : "no vídeo";
+  const other = Object.entries(list).find(([n, f]) => f.id === m[1] && n !== name);
+  if (other) throw new Error(`esse efeito já está ${whereAlready} como “${other[0]}”`);
+  if (list[name] && list[name].id !== m[1])
+    throw new Error(
+      `já existe “${name}” ${whereAlready} com outro efeito (${list[name].title || list[name].id}): escolha outro nome`,
+    );
+  if (dir !== KIT && kitSources()[name]) console.log(`   ⚠ o kit já tem um “${name}”; o do vídeo passa na frente dele`);
+
+  const r = await fetch(url);
+  if (!r.ok) throw new Error(`a Epidemic respondeu ${r.status} para ${url}`);
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, name);
+  writeFileSync(file, Buffer.from(await r.arrayBuffer()));
+  cache.delete(file);
+  const med = measureEffect(file);
+  list[name] = {
+    source: "epidemic",
+    id: m[1],
+    url,
+    title: med.title,
+    search: search ?? null,
+    downloaded_at: new Date().toISOString().slice(0, 10),
+    ...extra,
+  };
+  writeFileSync(registry, JSON.stringify(list, null, 1) + "\n");
+  console.log(`${name} ← ${med.title || m[1]}${extra.role ? ` · kit, papel ${extra.role}` : ""}`);
+  console.log(
+    med.music
+      ? `   ⚠ ${med.duration.toFixed(0)}s: é trilha, não efeito; só serve de música de fundo`
+      : `   ${describe(med)}`,
+  );
+}
+
+const describe = m =>
+  `${m.duration.toFixed(2)}s · pico em ${m.peak_s}s (${m.peak_db} dB) · útil até ${m.useful_end_s}s · volume ${m.volume_lufs} LUFS`;
+
+function effects(videoDir, filter) {
+  const dir = resolve(videoDir ?? "");
+  const list = Object.entries(sources(dir));
+  if (!list.length) {
+    console.log(`nenhum efeito capturado em ${effectsDir(dir)}`);
+    return;
+  }
+  const f = filter?.toLowerCase();
+  for (const [name, source] of list) {
+    if (f && !`${name} ${source.title}`.toLowerCase().includes(f)) continue;
+    const { file, error } = effectFile(dir, name);
+    if (error) {
+      console.log(`${name}\n   ⚠ ${error}`);
+      continue;
+    }
+    const m = measureEffect(file);
+    console.log(
+      `${name}\n   ${m.music ? `${m.duration.toFixed(0)}s · trilha (só música de fundo)` : describe(m)} · ${source.title || source.id}`,
+    );
+  }
+}
+
+/* moves an effect already captured from Epidemic for a video into the kit, with its origin */
+function adopt(videoDir, name, role, as) {
+  const dir = resolve(videoDir ?? "");
+  if (!ROLES[role]) throw new Error(`--role é obrigatório: ${Object.keys(ROLES).join(", ")}`);
+  const source = sources(dir)[name];
+  if (!source) throw new Error(`“${name}” não está em ${join(effectsDir(dir), "sources.json")}`);
+  const newName = `${(as ?? name).replace(/\.mp3$/i, "")}.mp3`;
+  if (!NAME.test(newName)) throw new Error(`nome “${newName}”: letras, números, ponto, hífen e sublinhado`);
+  const list = kitSources();
+  const other = Object.entries(list).find(([, e]) => e.id === source.id);
+  if (other) throw new Error(`esse efeito já está no kit como “${other[0]}”`);
+  if (list[newName])
+    throw new Error(`o kit já tem “${newName}” (${list[newName].title || list[newName].id}): use --as <outro-nome>`);
+  mkdirSync(KIT, { recursive: true });
+  writeFileSync(join(KIT, newName), readFileSync(join(effectsDir(dir), name)));
+  list[newName] = { ...source, role, adopted_from: basename(dir) };
+  writeFileSync(join(KIT, "kit.json"), JSON.stringify(list, null, 1) + "\n");
+  console.log(`${newName} ← ${source.title || source.id} · kit, papel ${role}`);
+}
+
+/* the kit grouped by role; `filter` is a role or a piece of the name/title */
+function kit(filter) {
+  const list = Object.entries(kitSources());
+  if (!list.length) {
+    console.log(`o kit está vazio (${KIT}): baixe com sound.mjs download kit <url> <nome> --role <papel>`);
+    return;
+  }
+  const f = filter?.toLowerCase();
+  for (const role of Object.keys(ROLES)) {
+    const ofRole = list.filter(
+      ([n, e]) => e.role === role && (!f || f === role || `${n} ${e.title}`.toLowerCase().includes(f)),
+    );
+    if (!ofRole.length) continue;
+    const p = ROLES[role];
+    console.log(`${role} (db ${p.db}${p.stretchable ? ", estica" : ""})`);
+    for (const [name, e] of ofRole) {
+      const file = join(KIT, name);
+      if (!existsSync(file)) {
+        console.log(`   ${name}  ⚠ arquivo sumiu`);
+        continue;
+      }
+      const m = measureEffect(file);
+      console.log(
+        `   ${name.padEnd(28)} ${m.music ? `${m.duration.toFixed(0)}s · trilha` : describe(m)}${e.db != null ? ` · db próprio ${e.db}` : ""}`,
+      );
+    }
+  }
+}
+
+function capture(n) {
+  const code = readFileSync(join(CODE_ROOT, "tools", "epidemic-capture.js"), "utf8");
+  console.log(
+    code
+      .slice(code.indexOf("=== */") + 6)
+      .trim()
+      .replace("__N__", String(n)),
+  );
+}
+
+/* --- voice: reference loudness and where it speaks ----------------------------------- */
+/* cached by the lines' files and mtimes: the studio timeline replans on every adjustment */
+const voiceCache = new Map();
+function voiceOf(dir, video) {
+  const files = [];
+  for (const scene of video.scenes)
+    for (const line of scene.lines ?? []) {
+      if (line.wav && existsSync(join(dir, line.wav))) files.push(join(dir, line.wav));
+    }
+  if (!files.length) return { lufs: S.default_voice_lufs, measured: false };
+  const key = `${S.voice_target_lufs}|` + files.map(a => `${a}@${statSync(a).mtimeMs}`).join("|");
+  if (voiceCache.has(key)) return voiceCache.get(key);
+  /* the effects' reference loudness is the voice as it will be heard, already leveled */
+  const gains = files.map(a => lineGain(a));
+  const parts = files.map((a, i) => {
+    const x = decode(a);
+    return gains[i] ? x.map(v => v * 10 ** (gains[i] / 20)) : x;
+  });
+  const x = new Float32Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) {
+    x.set(p, o);
+    o += p.length;
+  }
+  const v = integratedLoudness(x);
+  const r = Number.isFinite(v)
+    ? { lufs: +v.toFixed(1), measured: true, gains }
+    : { lufs: S.default_voice_lufs, measured: false, gains };
+  voiceCache.set(key, r);
+  return r;
+}
+
+/* spans where the voice speaks, in seconds of video: by words when already
+   aligned (gaps longer than ducking.min_gap release the ducking), otherwise the
+   whole line */
+function voiceSegments(video) {
+  const t = [];
+  /* each span moves with the voice piece it falls in (editor clips) */
+  for (const scene of video.scenes)
+    for (const line of scene.lines ?? []) {
+      if (line.words?.length) for (const w of line.words) t.push(...voiceSpans(scene, line, w.s, w.e));
+      else t.push(...voiceSpans(scene, line, 0, line.end - line.start));
+    }
+  t.sort((a, b) => a[0] - b[0]);
+  const out = [];
+  for (const [a, b] of t) {
+    const u = out.at(-1);
+    if (u && a - u[1] < S.ducking.min_gap) u[1] = Math.max(u[1], b);
+    else out.push([a, b]);
+  }
+  return out.map(([a, b]) => [+a.toFixed(3), +b.toFixed(3)]);
+}
+
+/* ducking depth (0 to 1) at each ms of video: goes down over `before` seconds
+   until the voice starts, comes back up over `after` seconds once it stops */
+function duckingCurve(segments, total) {
+  const n = Math.ceil(total * 1000) + 2;
+  const d = new Float32Array(n);
+  const { before, after } = S.ducking;
+  for (const [a, b] of segments) {
+    const i0 = Math.max(0, Math.floor((a - before) * 1000)),
+      i1 = Math.min(n - 1, Math.ceil((b + after) * 1000));
+    for (let i = i0; i <= i1; i++) {
+      const t = i / 1000;
+      const f = t < a ? (before > 0 ? 1 - (a - t) / before : 1) : t > b ? (after > 0 ? 1 - (t - b) / after : 0) : 1;
+      if (f > d[i]) d[i] = f;
+    }
+  }
+  return t => {
+    const x = Math.max(0, Math.min(n - 1.001, t * 1000)),
+      i = Math.floor(x);
+    return d[i] + (d[i + 1] - d[i]) * (x - i);
+  };
+}
+
+/* --- WAV ------------------------------------------------------------------------- */
+function writeWav(file, x) {
+  const n = x.length;
+  const buf = Buffer.alloc(44 + n * 2);
+  buf.write("RIFF", 0);
+  buf.writeUInt32LE(36 + n * 2, 4);
+  buf.write("WAVE", 8);
+  buf.write("fmt ", 12);
+  buf.writeUInt32LE(16, 16);
+  buf.writeUInt16LE(1, 20);
+  buf.writeUInt16LE(2, 22);
+  buf.writeUInt32LE(RATE, 24);
+  buf.writeUInt32LE(RATE * 4, 28);
+  buf.writeUInt16LE(4, 32);
+  buf.writeUInt16LE(16, 34);
+  buf.write("data", 36);
+  buf.writeUInt32LE(n * 2, 40);
+  for (let i = 0; i < n; i++) buf.writeInt16LE(Math.round(Math.max(-1, Math.min(1, x[i])) * 32767), 44 + i * 2);
+  writeFileSync(file, buf);
+}
+
+/* gain, fades and ducking applied in place; `t0` is the video second of the first sample */
+function apply(x, { gain_db, fade, duck_db, t0, ducking }) {
+  const n = x.length >> 1;
+  const g = 10 ** (gain_db / 20);
+  const fi = Math.round(fade[0] * RATE),
+    fo = Math.round(fade[1] * RATE);
+  for (let i = 0; i < n; i++) {
+    let v = g;
+    if (i < fi) v *= i / fi;
+    if (n - i <= fo) v *= (n - i) / fo;
+    if (duck_db) v *= 10 ** ((duck_db * ducking(t0 + i / RATE)) / 20);
+    x[2 * i] *= v;
+    x[2 * i + 1] *= v;
+  }
+}
+
+/* --- plan ------------------------------------------------------------------------ */
+const layers = sound =>
+  (Array.isArray(sound) ? sound : [sound]).map(s => (typeof s === "string" ? { name: s } : { ...s }));
+const num = (v, d) => (v == null ? d : +v);
+
+/* the video's sound requests: [{ id, group, type, scene, element, layer, instant, s }] */
+function requests(video) {
+  const out = [];
+  const add = (type, scene, element, instant, sound) =>
+    layers(sound).forEach((s, k) => {
+      const group = `${scene.id}-${element}`;
+      out.push({ id: k ? `${group}-${k + 1}` : group, group, type, scene: scene.id, element, layer: k, instant, s });
+    });
+  /* beats and transition illustrate the animation: they move with the animation piece they fall in
+     (editor clips, tools/soundtrack.mjs); a beat in a deleted piece is dropped */
+  video.scenes.forEach((scene, i) => {
+    const start = animationStart(scene);
+    if (i > 0 && start != null && scene.transition && typeof scene.transition === "object" && scene.transition.sound)
+      add("transition", scene, "transition", start, scene.transition.sound);
+    for (const beat of scene.beats ?? []) {
+      const t = beat.sound ? animationInstant(scene, beatTime(scene, beat)) : null;
+      if (t != null) add("beat", scene, beat.element, t, beat.sound);
+    }
+  });
+  return out;
+}
+
+/* editor clips (tools/soundtrack.mjs), validated, on video `v` (the loaded copy or raw scenes.json):
+   `scene_clips` { <scene>: clips } and `line_clips` { <line>: clips }. The default arrangement
+   (one whole clip, in place) is not stored */
+export function applyClips(v, draft) {
+  const fps = v.format.fps;
+  for (const [id, clips] of Object.entries(draft?.scene_clips ?? {})) {
+    const scene = v.scenes.find(c => c.id === id);
+    if (!scene) throw new Error(`cena ${id} não existe`);
+    const l = sanitizeClips(clips, scene.duration, 1 / fps);
+    delete scene.video_offset;
+    delete scene.video_em;
+    if (l.length === 1 && l[0].from === 0 && Math.abs(l[0].to - scene.duration) < 1e-3 && !l[0].offset && !l[0].speed)
+      delete scene.clips;
+    else scene.clips = l;
+  }
+  for (const [id, clips] of Object.entries(draft?.line_clips ?? {})) {
+    const line = v.scenes.flatMap(c => c.lines ?? []).find(f => f.id === id);
+    if (!line) throw new Error(`fala ${id} não existe`);
+    const dur = line.dur ?? line.end - line.start;
+    const l = sanitizeClips(clips, dur, 0.001);
+    if (l.length === 1 && l[0].from === 0 && Math.abs(l[0].to - dur) < 2e-3 && !l[0].offset && !l[0].speed)
+      delete line.clips;
+    else line.clips = l;
+  }
+}
+
+/* the animation shift (`video_offset`, from before clips): a number, frame-aligned, up to 30 s either way */
+export function sanitizeVideoOffset(offset, fps) {
+  const n = Number(offset);
+  if (!Number.isFinite(n) || Math.abs(n) > 30) throw new Error(`video_offset: de -30 a 30 segundos; veio "${offset}"`);
+  return +(Math.round(n * fps) / fps).toFixed(4);
+}
+
+/* --- validate what the studio sends (and what goes into scenes.json) ----------------
+   Only known keys, each within its range; defaults are dropped, and a sound with
+   only a name becomes the string. Throws with the message for the studio. */
+const RANGES = { offset: [-10, 10], db: [-40, 20], dur: [0.05, 60], speed: [0.25, 4], pitch: [-24, 24] };
+const DEFAULT = { offset: 0, db: 0, speed: 1, pitch: 0 };
+function number(v, [min, max], name) {
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < min || n > max) throw new Error(`${name}: ${v} fora de ${min} a ${max}`);
+  return +n.toFixed(3);
+}
+function pair(v, name, max, nullAtEnd = false) {
+  if (!Array.isArray(v) || v.length !== 2) throw new Error(`${name}: use [a, b]`);
+  return v.map((x, i) => (x == null && i === 1 && nullAtEnd ? null : number(x, [0, max], name)));
+}
+
+export function sanitizeSound(dir, s) {
+  const o = typeof s === "string" ? { name: s } : s;
+  if (!o || typeof o !== "object") throw new Error("som inválido");
+  const { file, error } = effectFile(dir, o.name);
+  if (error) throw new Error(error);
+  const m = measureEffect(file);
+  if (m.music) throw new Error(`“${o.name}” tem ${m.duration.toFixed(0)}s: é trilha, só serve de música de fundo`);
+  const v = { name: o.name };
+  if (o.anchor === "start") v.anchor = "start";
+  else if (o.anchor != null && o.anchor !== "peak") throw new Error(`âncora: ${o.anchor} (use peak ou start)`);
+  for (const k of ["offset", "db", "dur", "speed", "pitch"]) {
+    if (o[k] == null) continue;
+    const n = number(o[k], RANGES[k], k);
+    if (n !== DEFAULT[k]) v[k] = n;
+  }
+  if (o.trim != null) {
+    const t = pair(o.trim, "trim", m.duration, true);
+    if (t[1] != null && t[1] <= t[0]) throw new Error("trim: o fim vem depois do começo");
+    if (t[0] > 0 || t[1] != null) v.trim = t;
+  }
+  if (o.fade != null) v.fade = pair(o.fade, "fade", 10);
+  if (o.duck === false) v.duck = false;
+  else if (o.duck != null) v.duck = number(o.duck, [-40, 0], "duck");
+  if (v.dur != null) delete v.speed;
+  return Object.keys(v).length === 1 ? v.name : v;
+}
+
+export function sanitizeBed(dir, b, total) {
+  if (b == null) return null;
+  const o = typeof b === "string" ? { name: b } : b;
+  const { error } = effectFile(dir, o?.name);
+  if (error) throw new Error(`música de fundo: ${error}`);
+  const v = { name: o.name };
+  if (o.db != null && +o.db !== 0) v.db = number(o.db, [-40, 20], "música de fundo db");
+  if (o.from != null && +o.from > 0) v.from = number(o.from, [0, total], "música de fundo from");
+  if (o.to != null) v.to = number(o.to, [0, total], "música de fundo to");
+  if (v.from != null && v.to != null && v.to <= v.from) throw new Error("música de fundo: to vem depois de from");
+  if (o.trim != null) v.trim = pair(o.trim, "música de fundo trim", 3600, true);
+  if (o.fade != null) v.fade = pair(o.fade, "música de fundo fade", 30);
+  if (o.loop) v.loop = true;
+  if (o.duck === false) v.duck = false;
+  else if (o.duck != null) v.duck = number(o.duck, [-40, 0], "música de fundo duck");
+  if (o.speed != null && +o.speed !== 1) v.speed = number(o.speed, [0.5, 2], "música de fundo speed");
+  return Object.keys(v).length === 1 ? v.name : v;
+}
+
+/* the studio draft applied to a loaded video (copy): { places: [{ type,
+   scene, element, sounds: [] }], bed }. Returns the video with sounds swapped. */
+export function applyDraft(dir, video, draft) {
+  const v = structuredClone(video);
+  for (const l of draft?.places ?? []) {
+    const scene = v.scenes.find(c => c.id === l.scene);
+    if (!scene) throw new Error(`cena ${l.scene} não existe`);
+    const sounds = (l.sounds ?? []).map(s => sanitizeSound(dir, s));
+    const sound = sounds.length === 0 ? null : sounds.length === 1 ? sounds[0] : sounds;
+    if (l.type === "transition") {
+      if (v.scenes.indexOf(scene) === 0) throw new Error("a primeira cena não tem passagem");
+      const p = scene.transition && typeof scene.transition === "object" ? { ...scene.transition } : {};
+      if (sound) p.sound = sound;
+      else delete p.sound;
+      if (Object.keys(p).length) scene.transition = p;
+      else delete scene.transition;
+    } else {
+      const beat = (scene.beats ?? []).find(b => b.element === l.element);
+      if (!beat) throw new Error(`${l.scene}: beat ${l.element} não existe`);
+      if (sound) beat.sound = sound;
+      else delete beat.sound;
+    }
+  }
+  if (draft && "bed" in draft) {
+    const b = sanitizeBed(dir, draft.bed, v.total_duration);
+    if (b) v.bed = b;
+    else delete v.bed;
+  }
+  /* the cuts and the speed only move the bed's clock (finalClock); effects and voice stay put */
+  if (draft && "cuts" in draft) {
+    const c = normalizeCuts(draft.cuts, v.total_duration, v.format.fps);
+    if (c.length) v.cuts = c;
+    else delete v.cuts;
+  }
+  /* always explicit, even at 1: that is what tells it apart from a video that never chose */
+  if (draft && "speed" in draft) v.speed = sanitizeSpeed(draft.speed);
+  applyClips(v, draft);
+  return v;
+}
+
+/* the export speed, 1 to 1.5 (assemble.mjs): 110 or 1.1 both mean 110%; empty or invalid is 1 */
+export function sanitizeSpeed(s) {
+  const n = Number(
+    String(s ?? "")
+      .trim()
+      .replace(",", ".")
+      .replace(/%$/, ""),
+  );
+  const v = n > 3 ? n / 100 : n;
+  return Number.isFinite(v) && v > 0 ? Math.round(Math.min(1.5, Math.max(1, v)) * 100) / 100 : 1;
+}
+
+/* what the studio offers: the kit by role and what was captured for the video, measured */
+export function soundCatalog(dir) {
+  const item = (from, name, e, origin) => {
+    const file = join(from, name);
+    if (!existsSync(file)) return null;
+    const m = measureEffect(file);
+    return {
+      name,
+      origin,
+      role: e.role ?? null,
+      title: e.title ?? "",
+      music: m.music,
+      duration: +m.duration.toFixed(3),
+      peak_s: m.peak_s ?? null,
+      useful_end_s: m.useful_end_s ?? null,
+      volume_lufs: m.volume_lufs ?? null,
+    };
+  };
+  return {
+    kit: Object.entries(kitSources())
+      .map(([n, e]) => item(KIT, n, e, "kit"))
+      .filter(Boolean),
+    video: Object.entries(sources(dir))
+      .map(([n, e]) => item(effectsDir(dir), n, e, "video"))
+      .filter(Boolean),
+    roles: ROLES,
+    level_db: S.level_db,
+    ducking: S.ducking,
+    bed: S.bed,
+  };
+}
+export const kitDir = KIT;
+
+/* --- the bed's clock -----------------------------------------------------------------
+   The bed is isolated: the editor's area cuts and the speed (`cuts` and `speed` at the root of
+   scenes.json) act on the picture, voice and effects, never on the music. So the bed lives on the
+   final timeline (cuts closed, then divided by the speed) and plays there at its own pace, with
+   no gaps and no tempo change; `at` takes a scenes.json time to the final timeline. The identity
+   clock is the one before any edit (sound/preview.wav mixes everything in scenes.json time). */
+export const identityClock = video => ({ cuts: [], speed: 1, at: t => t, total: video.total_duration });
+
+/** @param {any} video @param {number} [speed] */
+export function finalClock(video, speed = video.speed) {
+  const cuts = normalizeCuts(video.cuts, video.total_duration, video.format.fps);
+  const s = Number(speed) > 0 ? Number(speed) : 1;
+  return {
+    cuts,
+    speed: s,
+    at: t => toEdited(t, cuts) / s,
+    total: (video.total_duration - removedDuration(cuts)) / s,
+  };
+}
+
+/* the voice spans on the final timeline (the parts inside a cut are gone) */
+const finalSegments = (segments, clock) =>
+  segments.map(([a, b]) => [clock.at(a), clock.at(b)]).filter(([a, b]) => b - a > 0.001);
+
+/* Computes and writes the effect (and bed) WAVs in `outDir`. `scenes`: only the
+   effects of these scenes (the preview; an empty set: none, just the bed). `clock`: where the bed
+   lives (finalClock by default; the effects always stay in scenes.json time). Returns the plan. */
+/** @param {string} dir @param {any} video @param {{ outDir: string, scenes?: Set<string> | null, withBed?: boolean, clock?: ReturnType<typeof finalClock> }} options */
+export function planSound(dir, video, { outDir, scenes = null, withBed = true, clock = finalClock(video) }) {
+  const total = video.total_duration;
+  const voice = voiceOf(dir, video);
+  const segments = voiceSegments(video);
+  const ducking = duckingCurve(segments, total);
+  const bedDucking = duckingCurve(finalSegments(segments, clock), clock.total);
+  const items = [],
+    pending = [],
+    warnings = [];
+  if (!voice.measured && isNarrated(dir))
+    warnings.push(`voz ainda sem áudio: efeitos nivelados por ${voice.lufs} LUFS (sound.default_voice_lufs)`);
+  mkdirSync(outDir, { recursive: true });
+
+  for (const p of requests(video)) {
+    if (scenes && !scenes.has(p.scene)) continue;
+    const { s, id } = p;
+    const { file, error, kit } = effectFile(dir, s.name);
+    if (error) throw new Error(`${id}: ${error}`);
+    const m = measureEffect(file);
+    if (m.music)
+      throw new Error(
+        `${id}: “${s.name}” tem ${m.duration.toFixed(0)}s; é trilha, não efeito (pode ser música de fundo)`,
+      );
+    /* from the kit, the effect brings its role's volume (or its own) */
+    const role = kit ? (ROLES[kit.role] ?? {}) : {};
+    const kitDb = kit ? num(kit.db, num(role.db, 0)) : 0;
+    if (kit && (s.dur != null || s.speed != null) && !role.stretchable)
+      warnings.push(`${id}: “${s.name}” é ${kit.role}, que não costuma aguentar ser esticado`);
+
+    const from = num(s.trim?.[0], 0),
+      to = num(s.trim?.[1], m.useful_end_s);
+    if (!(from >= 0 && to > from && from < m.duration))
+      throw new Error(`${id}: trim [${s.trim}] fora de “${s.name}” (${m.duration.toFixed(2)}s)`);
+    const pitch = num(s.pitch, 0);
+    let speed = s.dur != null ? (Math.min(to, m.duration) - from) / +s.dur : num(s.speed, 1);
+    if (!(speed >= 0.25 && speed <= 4)) {
+      warnings.push(`${id}: velocidade ${speed.toFixed(2)}× fora de 0,25–4×; limitada`);
+      speed = Math.min(4, Math.max(0.25, speed || 1));
+    }
+    let x = decode(file, { from, to: s.trim?.[1] != null || to < m.duration ? to : null, speed, pitch });
+    if (x.length < 4) {
+      warnings.push(`${id}: o trecho não tem som; ignorado`);
+      continue;
+    }
+
+    const peak = peakOf(x);
+    const volume = maxLoudness(x);
+    const anchor = s.anchor === "start" ? 0 : peak.s;
+    const instant = p.instant + num(s.offset, 0);
+    let start = instant - anchor;
+    let gain = voice.lufs + S.level_db + kitDb + num(s.db, 0) - volume;
+    const ceiling = S.max_peak_db - 20 * Math.log10(peak.amp);
+    if (gain > ceiling) {
+      warnings.push(
+        `${id}: limitado em ${ceiling.toFixed(1)} dB para o pico não passar de ${S.max_peak_db} dBFS (pedia ${gain.toFixed(1)})`,
+      );
+      gain = ceiling;
+    }
+
+    let cut = 0;
+    if (start < 0) {
+      cut = -start;
+      start = 0;
+      warnings.push(`${id}: começaria antes do vídeo; ${cut.toFixed(2)}s do começo cortados`);
+    }
+    let dur = x.length / 2 / RATE - cut;
+    if (start + dur > total) {
+      dur = total - start;
+      warnings.push(`${id}: passa do fim do vídeo; cortado em ${dur.toFixed(2)}s`);
+    }
+    if (dur <= 0.02) {
+      warnings.push(`${id}: não sobra som depois do corte; ignorado`);
+      continue;
+    }
+    x = x.slice(Math.round(cut * RATE) * 2, (Math.round(cut * RATE) + Math.round(dur * RATE)) * 2);
+
+    const fade = [num(s.fade?.[0], from > 0 || cut > 0 ? 0.004 : 0), num(s.fade?.[1], Math.min(0.05, dur / 4))].map(f =>
+      Math.min(f, dur / 2),
+    );
+    const duck = s.duck === false ? 0 : num(s.duck, S.ducking.db);
+    pending.push({
+      id,
+      group: p.group,
+      type: p.type,
+      layer: p.layer,
+      scene: p.scene,
+      element: p.element,
+      name: s.name,
+      x,
+      start,
+      dur,
+      cut,
+      peak: start + peak.s - cut,
+      beat: p.instant,
+      anchor: s.anchor === "start" ? "start" : "peak",
+      gain,
+      volume,
+      duck,
+      fade,
+      trim: [from, +to.toFixed(3)],
+      speed,
+      pitch,
+      kit,
+      kitDb,
+    });
+  }
+
+  pending.sort((a, b) => a.start - b.start);
+  const adjusted = [];
+  for (let i = 1; i < pending.length; i++) {
+    const note = giveWay(pending[i - 1], pending[i]);
+    if (note) adjusted.push(note);
+  }
+
+  for (const e of pending) {
+    apply(e.x, { gain_db: e.gain, fade: e.fade, duck_db: e.duck, t0: e.start, ducking });
+    const wav = join(outDir, `${e.id}.wav`);
+    writeWav(wav, e.x);
+    items.push({
+      id: e.id,
+      group: e.group,
+      type: e.type,
+      layer: e.layer,
+      scene: e.scene,
+      element: e.element,
+      name: e.name,
+      file: wav,
+      wav: relative(dir, wav),
+      start: +e.start.toFixed(3),
+      duration: +e.dur.toFixed(3),
+      peak: +e.peak.toFixed(3),
+      beat: +e.beat.toFixed(3),
+      anchor: e.anchor,
+      gain_db: +e.gain.toFixed(1),
+      volume_lufs: +e.volume.toFixed(1),
+      duck_db: e.duck,
+      fade: e.fade.map(f => +f.toFixed(3)),
+      trim: e.trim,
+      speed: +e.speed.toFixed(3),
+      pitch: e.pitch,
+      cut_start: +e.cut.toFixed(3),
+      ...(e.gave_way ? { gave_way: e.gave_way } : {}),
+      origin: e.kit ? "kit" : "video",
+      role: e.kit?.role ?? null,
+      kit_db: e.kitDb,
+    });
+  }
+
+  for (let i = 1; i < items.length; i++) {
+    const a = items[i - 1],
+      b = items[i];
+    if (a.group === b.group) continue;
+    const overlap = clash(a.start, a.duration, b.start, b.duration);
+    if (overlap) warnings.push(`${a.id} e ${b.id} tocam juntos por ${overlap.toFixed(2)}s`);
+  }
+
+  const bed =
+    withBed && video.bed ? makeBed(dir, video, { outDir, voice, ducking: bedDucking, warnings, clock }) : null;
+  return { items, bed, warnings, adjusted, voice, ducking: { ...S.ducking, segments } };
+}
+
+/* Two effects of different beats on top of each other. `warn`: the overlap, as a fraction of the
+   shorter one, that counts as a clash; `target`: where giving way stops; `attack` and `release`:
+   what is always kept before and after each peak. */
+const OVERLAP = { warn: 0.5, target: 0.25, min_s: 0.3, attack: 0.1, release: 0.1, fade: 0.08 };
+
+/** the overlap in seconds when it is a clash, else 0 */
+function clash(aStart, aDur, bStart, bDur) {
+  const shorter = Math.min(aDur, bDur),
+    overlap = aStart + aDur - bStart;
+  return shorter > OVERLAP.min_s && overlap > OVERLAP.warn * shorter ? overlap : 0;
+}
+
+/* Resolves a clash between `a` and the next effect `b` without moving either peak: first `b`
+   loses part of its build-up (it enters later, with a short fade-in), then, if that is not
+   enough, `a` loses part of its tail (shorter, with a fade-out). An effect anchored at its start
+   keeps its start: there the start is the movement it follows. Edits the samples in place and
+   returns what changed, or null. */
+function giveWay(a, b) {
+  if (a.group === b.group) return null;
+  const before = clash(a.start, a.dur, b.start, b.dur);
+  if (!before) return null;
+  const target = () => OVERLAP.target * Math.min(a.dur, b.dur);
+  const changes = [];
+
+  if (b.anchor !== "start") {
+    const room = b.peak - b.start - OVERLAP.attack;
+    const h = Math.round(Math.min(room, a.start + a.dur - b.start - target()) * RATE) / RATE;
+    if (h > 0.01) {
+      b.x = b.x.slice(Math.round(h * RATE) * 2);
+      b.start += h;
+      b.cut += h;
+      b.dur -= h;
+      b.fade[0] = Math.min(Math.max(b.fade[0], Math.min(OVERLAP.fade, (b.peak - b.start) / 2)), b.dur / 2);
+      b.gave_way = `entra ${h.toFixed(2)}s depois (subida aparada)`;
+      changes.push(`${b.id} ${b.gave_way}`);
+    }
+  }
+
+  if (a.start + a.dur - b.start > target()) {
+    const keep = Math.max(b.start + target() - a.start, a.peak - a.start + OVERLAP.release);
+    const n = Math.round(keep * RATE);
+    if (n / RATE < a.dur - 0.01) {
+      a.x = a.x.slice(0, n * 2);
+      a.dur = n / RATE;
+      a.fade[1] = Math.min(Math.max(a.fade[1], OVERLAP.fade), a.dur / 2);
+      a.gave_way = `termina em ${a.dur.toFixed(2)}s (cauda cortada)`;
+      changes.push(`${a.id} ${a.gave_way}`);
+    }
+  }
+
+  if (!changes.length) return null;
+  const after = Math.max(0, a.start + a.dur - b.start);
+  return `${a.id} e ${b.id} tocavam juntos por ${before.toFixed(2)}s: ${changes.join("; ")}; agora ${after.toFixed(2)}s`;
+}
+
+/* `from`/`to` are scenes.json times: they say which part of the video the music covers. On the
+   clock they become where it enters and ends; the music itself is never cut or sped up. `start`
+   in the result is on that clock, and `ducking` is the curve of the voice on it too. */
+function makeBed(dir, video, { outDir, voice, ducking, warnings, clock }) {
+  const b = typeof video.bed === "string" ? { name: video.bed } : video.bed;
+  const total = video.total_duration;
+  const { file, error } = effectFile(dir, b.name);
+  if (error) throw new Error(`música de fundo: ${error}`);
+  const start = clock.at(Math.max(0, num(b.from, 0))),
+    end = clock.at(Math.min(total, num(b.to, total)));
+  if (end - start < 0.1) {
+    warnings.push("música de fundo: from/to não deixam tempo; ignorada");
+    return null;
+  }
+  let x = decode(file, { from: num(b.trim?.[0], 0), to: b.trim?.[1] ?? null, speed: num(b.speed, 1) });
+  const span = Math.round((end - start) * RATE) * 2;
+  if (x.length < span) {
+    if (b.loop) {
+      const y = new Float32Array(span);
+      for (let o = 0; o < span; o += x.length) y.set(x.subarray(0, Math.min(x.length, span - o)), o);
+      x = y;
+    } else
+      warnings.push(
+        `música de fundo: “${b.name}” acaba ${((span - x.length) / 2 / RATE).toFixed(1)}s antes de ${end.toFixed(1)}s (use loop para textura)`,
+      );
+  }
+  x = x.slice(0, span);
+  const dur = x.length / 2 / RATE;
+  const volume = integratedLoudness(x);
+  if (!Number.isFinite(volume)) {
+    warnings.push("música de fundo: sem som audível; ignorada");
+    return null;
+  }
+  let gain = voice.lufs + S.bed.level_db + num(b.db, 0) - volume;
+  const peak = peakOf(x);
+  gain = Math.min(gain, S.max_peak_db - 20 * Math.log10(peak.amp));
+  const fade = [num(b.fade?.[0], S.bed.fade[0]), num(b.fade?.[1], S.bed.fade[1])].map(f => Math.min(f, dur / 2));
+  const duck = b.duck === false ? 0 : num(b.duck, S.bed.ducking_db);
+  apply(x, { gain_db: gain, fade, duck_db: duck, t0: start, ducking });
+  const wav = join(outDir, "bed.wav");
+  writeWav(wav, x);
+  return {
+    id: "bed",
+    name: b.name,
+    file: wav,
+    wav: relative(dir, wav),
+    start: +start.toFixed(3),
+    duration: +dur.toFixed(3),
+    gain_db: +gain.toFixed(1),
+    volume_lufs: +volume.toFixed(1),
+    duck_db: duck,
+    fade,
+    loop: !!b.loop,
+  };
+}
+
+export function prepareSound(videoDir, { preview = true, log = console.log, speed = undefined } = {}) {
+  const dir = resolve(videoDir);
+  const video = loadVideo(dir);
+  const total = video.total_duration;
+  const out = join(dir, "sound");
+  mkdirSync(out, { recursive: true });
+  const previousSound = keepPrevious(dir, "sound", null, ["sound/plan.json", "sound/preview.wav"]);
+  /* sound/preview.wav mixes everything in scenes.json time, so its bed is on the identity clock; the
+     export's (assemble.mjs) is on the final one */
+  const { items, bed, warnings, adjusted, voice, ducking } = planSound(dir, video, {
+    outDir: out,
+    clock: preview ? identityClock(video) : finalClock(video, speed),
+  });
+
+  /* On a single track, two overlapping clips cannot coexist: overwrite cuts
+     the one below. Overlapping effects become one mixed clip, each at its own
+     offset; the rest stay one clip per effect, editable in Premiere. */
+  const clips = [];
+  for (const it of items) {
+    const last = clips[clips.length - 1];
+    if (last && it.start < last.end - 0.001) {
+      last.items.push(it);
+      last.end = Math.max(last.end, it.start + it.duration);
+    } else clips.push({ start: it.start, end: it.start + it.duration, items: [it] });
+  }
+  for (const c of clips) {
+    if (c.items.length === 1) {
+      Object.assign(c, { id: c.items[0].id, wav: c.items[0].wav });
+      continue;
+    }
+    c.id = c.items.map(i => i.id).join("+");
+    c.wav = `sound/${c.id}.wav`;
+    const ins = c.items.flatMap(i => ["-i", join(dir, i.wav)]);
+    const graph =
+      c.items.map((i, k) => `[${k}]adelay=${Math.round((i.start - c.start) * 1000)}:all=1[a${k}]`).join(";") +
+      `;${c.items.map((_, k) => `[a${k}]`).join("")}amix=inputs=${c.items.length}:normalize=0:duration=longest`;
+    run("ffmpeg", [
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      ...ins,
+      "-filter_complex",
+      graph,
+      "-ar",
+      String(RATE),
+      "-c:a",
+      "pcm_s16le",
+      join(dir, c.wav),
+    ]);
+  }
+  const planClips = clips.map(c => ({
+    id: c.id,
+    wav: c.wav,
+    start: +c.start.toFixed(3),
+    duration: +(c.end - c.start).toFixed(3),
+    effects: c.items.map(i => i.id),
+  }));
+  const withoutFile = ({ file, ...r }) => r;
+  writeFileSync(
+    join(out, "plan.json"),
+    JSON.stringify(
+      {
+        provisional: video.provisional,
+        total_duration: total,
+        voice_lufs: voice.lufs,
+        voice_measured: voice.measured,
+        level_db: S.level_db,
+        window_s: S.window_s,
+        ducking,
+        items: items.map(withoutFile),
+        bed: bed && withoutFile(bed),
+        clips: planClips,
+        adjusted,
+        warnings,
+      },
+      null,
+      1,
+    ) + "\n",
+  );
+
+  /* preview: voice (if it exists yet), effects and bed in final timing */
+  let withVoice = 0;
+  if (preview && (items.length || bed)) {
+    const inputs = [];
+    for (const scene of video.scenes)
+      for (const line of scene.lines ?? []) {
+        if (line.wav && existsSync(join(dir, line.wav))) {
+          inputs.push(...lineInputs(scene, line, join(dir, line.wav)));
+          withVoice++;
+        }
+      }
+    for (const it of [...items, ...(bed ? [bed] : [])]) inputs.push({ file: it.file, t: it.start });
+    run("ffmpeg", [
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      ...inputs.flatMap(e => ["-i", e.file]),
+      "-filter_complex",
+      mixGraph(inputs, total),
+      "-t",
+      String(total),
+      "-ar",
+      String(RATE),
+      "-c:a",
+      "pcm_s16le",
+      join(out, "preview.wav"),
+    ]);
+  }
+  previousSound.close();
+
+  log(
+    `${items.length} efeito(s)${bed ? " + cama" : ""}${video.provisional ? " (tempo provisório)" : ""} → ${join(out, "plan.json")}`,
+  );
+  if (Number.isFinite(S.voice_target_lufs) && voice.gains?.some(g => g)) {
+    log(
+      `   falas niveladas em ${S.voice_target_lufs} LUFS: ganho de ${Math.min(...voice.gains).toFixed(1)} a ${Math.max(...voice.gains).toFixed(1)} dB`,
+    );
+  }
+  log(
+    `   voz ${voice.lufs} LUFS${voice.measured ? "" : " (padrão, sem áudio)"} · efeitos ${S.level_db} dB abaixo · ducking ${S.ducking.db} dB em ${ducking.segments.length} trecho(s)`,
+  );
+  for (const it of items) {
+    log(
+      `   ${it.id.padEnd(20)} começa ${it.start.toFixed(2).padStart(6)}s · ${it.anchor === "peak" ? "pico" : "inicio"} ${(it.anchor === "peak" ? it.peak : it.start).toFixed(2)}s (instante ${it.beat.toFixed(2)}s) · ${it.gain_db > 0 ? "+" : ""}${it.gain_db} dB · ${it.name}`,
+    );
+  }
+  if (bed)
+    log(
+      `   cama                 ${bed.start.toFixed(2)}–${(bed.start + bed.duration).toFixed(2)}s · ${bed.gain_db > 0 ? "+" : ""}${bed.gain_db} dB · ducking ${bed.duck_db} dB · ${bed.name}`,
+    );
+  adjusted.forEach(a => log(`   ↔ ${a}`));
+  warnings.forEach(a => log(`   ⚠ ${a}`));
+  planClips
+    .filter(c => c.effects.length > 1)
+    .forEach(c => log(`   ${c.effects.join(" e ")} se sobrepõem: vão juntos num clipe só (${c.wav})`));
+  if (preview && (items.length || bed))
+    log(
+      `prévia ${withVoice ? `com ${withVoice} fala(s)` : "só com efeitos (a voz ainda não existe)"} → ${join(out, "preview.wav")}`,
+    );
+  return { items, bed, clips: planClips, adjusted, warnings, voice };
+}
+
+/* inputs [{ file, t, gain_db? }] summed without normalizing, each at its own second;
+   `gain_db` is the per-line level (lineGain) */
+/* a line's mix inputs: one per voice piece (editor clips), each with its range of the WAV */
+export function lineInputs(scene, line, file) {
+  const gain_db = lineGain(file);
+  return lineClips(line).map(cl => ({
+    file,
+    t: scene.start + line.start + cl.from + cl.offset,
+    gain_db,
+    from: cl.from,
+    to: cl.to,
+    ...(cl.speed ? { speed: cl.speed } : {}),
+  }));
+}
+
+/* `from`/`to` on an input play only that range of the file (voice piece), `speed` plays it faster
+   with its pitch kept (atempo); what would start before 0 loses its head */
+export function mixGraph(inputs, total) {
+  const trim = e => {
+    /* seconds lost before 0 are video seconds: in the file, × speed */
+    const cut = Math.max(0, -e.t) * (e.speed ?? 1);
+    const from = (e.from ?? 0) + cut;
+    return e.from != null || cut
+      ? `atrim=start=${from.toFixed(4)}${e.to != null ? `:end=${e.to.toFixed(4)}` : ""},asetpts=PTS-STARTPTS,`
+      : "";
+  };
+  return (
+    inputs
+      .map(
+        (e, i) =>
+          `[${i}]${trim(e)}${e.speed && e.speed !== 1 ? `${atempo(e.speed).join(",")},` : ""}aresample=${RATE}${e.gain_db ? `,volume=${e.gain_db}dB` : ""},aformat=channel_layouts=stereo,adelay=${Math.round(Math.max(0, e.t) * 1000)}:all=1[a${i}]`,
+      )
+      .join(";") +
+    `;${inputs.map((_, i) => `[a${i}]`).join("")}amix=inputs=${inputs.length}:normalize=0:duration=longest,apad=whole_dur=${total}`
+  );
+}
+
+/* --- cli -------------------------------------------------------------------------- */
+if (isMainModule(import.meta.url)) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  try {
+    const option = n => (i => (i < 0 ? undefined : rest.splice(i, 2)[1]))(rest.indexOf(`--${n}`));
+    const search = option("search"),
+      role = option("role");
+    if (cmd === "capture") capture(+(rest[0] ?? 8));
+    else if (cmd === "download") await download(rest[0], rest[1], rest[2], search, role);
+    else if (cmd === "effects") effects(rest[0], rest[1]);
+    else if (cmd === "kit" && rest[0] === "adopt") adopt(rest[1], rest[2], role, option("as") ?? rest[3]);
+    else if (cmd === "kit") kit(rest[0]);
+    else if (cmd && existsSync(join(resolve(cmd), "scenes.json"))) {
+      await turn("sound", cmd);
+      prepareSound(cmd);
+    } else {
+      const source = readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n");
+      console.log(
+        source
+          .slice(
+            1,
+            source.findIndex((l, i) => i > 1 && l.includes("=====*/")),
+          )
+          .join("\n"),
+      );
+      process.exit(2);
+    }
+  } catch (e) {
+    console.error(`erro: ${e.message}`);
+    process.exit(1);
+  }
+}