fablecut 0.0.0-stage → 1.12.0

package/denoise.js

@@ -0,0 +1,120 @@
+/* Noise reduction — render and replace. The file's noise floor is measured
+   first (astats: the level of its quietest stretches), then ffmpeg's FFT
+   denoiser (afftdn) pulls everything near that floor down and writes a FLAC
+   beside it in media/. Clips then play that file instead; the original
+   stays registered, so switching back is instant. The whole file is
+   processed, not just a clip's window, so `in` points stay valid and linked
+   stems keep their timing (and their channel layout). Used by server.js
+   (POST /api/denoise) and the MCP server (fablecut_denoise). */
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const { spawn, spawnSync } = require("child_process");
+
+/* nr: how far the noise is pulled down, dB. The floor is measured per file —
+   afftdn's own noise tracking (tn) left loud hiss untouched in testing. */
+const AMOUNTS = {
+  light: { nr: 10, label: "Light" },
+  medium: { nr: 18, label: "Medium" },
+  strong: { nr: 30, label: "Strong" },
+};
+const AMOUNT_IDS = Object.keys(AMOUNTS);
+
+/** media/ file name for a denoised copy, e.g. "take 3.denoise-medium.flac". */
+function denoiseName(srcName, amount) {
+  const base = path.basename(decodeURIComponent(String(srcName).split("?")[0]));
+  const stem = base.replace(/\.[^.]+$/, "").replace(/\.denoise-(light|medium|strong)$/, "");
+  return `${stem}.denoise-${amount}.flac`;
+}
+function probe(file) {
+  const r = spawnSync("ffprobe", ["-v", "error", "-select_streams", "a:0",
+    "-show_entries", "stream=channels:format=duration", "-of", "json", file], { encoding: "utf8" });
+  if (r.error) throw new Error("ffprobe not found on PATH — needed for noise reduction");
+  try {
+    const j = JSON.parse(r.stdout);
+    return { channels: j.streams?.[0]?.channels || 0, duration: Math.round(+j.format?.duration * 1000) / 1000 || undefined };
+  } catch { return { channels: 0, duration: undefined }; }
+}
+/** The file's noise floor, dB RMS: the 10th-percentile level of its 50 ms
+ *  windows (mono, 16 kHz) — the room tone between words, steady from run to
+ *  run where a single quietest window is not. Digital silence is skipped. */
+function measureNoiseFloor(file) {
+  return new Promise((resolve, reject) => {
+    const SR = 16000, WIN = SR / 20;
+    const proc = spawn("ffmpeg", ["-v", "error", "-i", file, "-vn", "-map", "0:a:0", "-ac", "1", "-ar", String(SR), "-f", "f32le", "-"]);
+    const levels = [];
+    let sum = 0, n = 0, rest = Buffer.alloc(0);
+    proc.stdout.on("data", (chunk) => {
+      const buf = rest.length ? Buffer.concat([rest, chunk]) : chunk;
+      const count = Math.floor(buf.length / 4);
+      for (let i = 0; i < count; i++) {
+        const x = buf.readFloatLE(i * 4);
+        sum += x * x;
+        if (++n === WIN) { if (sum > 1e-12) levels.push(sum / WIN); sum = 0; n = 0; }
+      }
+      rest = buf.subarray(count * 4);
+    });
+    proc.stderr.resume();
+    proc.on("error", () => reject(new Error("ffmpeg not found on PATH — needed for noise reduction")));
+    proc.on("close", () => {
+      if (!levels.length) return resolve(-80);
+      levels.sort((a, b) => a - b);
+      resolve(10 * Math.log10(levels[Math.floor(levels.length * 0.1)]));
+    });
+  });
+}
+/* afftdn's nf sits a little above the measured RMS floor (its noise model
+   reads louder than plain RMS); the result is clamped to its −80…−20 range. */
+const FLOOR_OFFSET_DB = 4;
+/** Denoise `file` into `outDir`. Resolves {file, name, duration, channels, cached}.
+ *  An existing output with the same name is reused. */
+function denoiseFile(file, outDir, amount) {
+  const a = AMOUNTS[amount];
+  if (!a) return Promise.reject(new Error(`amount must be one of ${AMOUNT_IDS.join(", ")}`));
+  const name = denoiseName(file, amount);
+  const out = path.join(outDir, name);
+  if (fs.existsSync(out) && fs.statSync(out).size > 0)
+    return Promise.resolve({ file: out, name, cached: true, ...probe(out) });
+  const src = probe(file);
+  if (!src.channels) return Promise.reject(new Error(`${path.basename(file)} has no audio to clean up`));
+  const part = out + ".part.flac";
+  return measureNoiseFloor(file).then((floor) => new Promise((resolve, reject) => {
+    const nf = Math.round(Math.min(-20, Math.max(-80, floor + FLOOR_OFFSET_DB)) * 10) / 10;
+    const proc = spawn("ffmpeg", ["-v", "error", "-y", "-i", file, "-vn", "-map", "0:a:0",
+      "-af", `afftdn=nr=${a.nr}:nf=${nf}`, "-c:a", "flac", part]);
+    let err = "";
+    proc.stderr.on("data", (d) => { err = (err + d).slice(-2000); });
+    proc.on("error", () => reject(new Error("ffmpeg not found on PATH — needed for noise reduction")));
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        try { fs.rmSync(part, { force: true }); } catch {}
+        return reject(new Error("ffmpeg denoise failed: " + (err.trim().split("\n").pop() || code)));
+      }
+      fs.renameSync(part, out);
+      resolve({ file: out, name, cached: false, noiseFloor: nf, ...probe(out) });
+    });
+  }));
+}
+
+/** The media a clip's sound comes from originally (a denoised copy points back). */
+function baseMediaId(doc, id) {
+  return doc.media.find((m) => m.id === id)?.derivedFrom || id;
+}
+/** The audio clips a selection's noise reduction applies to: an audio clip and
+ *  its linked stems, or a video's stems. Throws for a picture that carries its
+ *  own sound (no stems) — its file can't be swapped without the picture. */
+function denoiseTargets(doc, clips) {
+  const out = new Map();
+  for (const c of clips) {
+    const group = c.linkGroup ? doc.clips.filter((x) => x.linkGroup === c.linkGroup) : [c];
+    const stems = group.filter((x) => x.kind === "audio" && x.mediaId);
+    if (!stems.length) {
+      if (c.kind === "video") throw new Error(`clip ${c.id}: its sound plays from the picture (no linked audio stems) — noise reduction works on audio clips`);
+      throw new Error(`clip ${c.id} is ${c.kind} — no audio to clean up`);
+    }
+    for (const s of stems) out.set(s.id, s);
+  }
+  return [...out.values()];
+}
+
+module.exports = { AMOUNTS, AMOUNT_IDS, denoiseName, denoiseFile, measureNoiseFloor, baseMediaId, denoiseTargets };

package/ducking.js

@@ -0,0 +1,127 @@
+/* FableCut auto-duck — find where the voice is and turn that into `duck`
+   keyframes (dB) on the music. Zero dependencies; loaded by the editor as a
+   plain script (global `FableCutDucking`) and required by the MCP server, so
+   the inspector's Auto-duck and `fablecut_auto_duck` write identical keys.
+
+   Pipeline: rmsEnvelope (per voice clip) → activeRegions (timeline seconds,
+   above a threshold) → mergeRegions (all voices, short gaps bridged) →
+   duckKeyframes (ramps down before speech, back up after). */
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === "object" && module.exports) module.exports = api;
+  else root.FableCutDucking = api;
+})(typeof self !== "undefined" ? self : this, function () {
+  "use strict";
+
+  const HOP = 0.05;  // s between envelope points
+  const WIN = 0.1;   // s RMS window
+
+  /** Streaming RMS envelope over one or more channels (power summed, so a
+   *  stereo voice reads like its loudness). push() as audio arrives. */
+  class EnvelopeMeter {
+    constructor(channels, sampleRate, hop = HOP, win = WIN) {
+      this.c = channels;
+      this.hopN = Math.max(1, Math.round(hop * sampleRate));
+      this.winN = Math.max(this.hopN, Math.round(win * sampleRate));
+      this.ring = new Float64Array(this.winN); // per-sample power, last winN
+      this.idx = 0; this.sum = 0; this.n = 0;
+      this.out = [];
+    }
+    push(chs) {
+      const len = chs.length ? chs[0].length : 0;
+      for (let i = 0; i < len; i++) {
+        let e = 0;
+        for (let k = 0; k < chs.length; k++) { const x = chs[k][i]; e += x * x; }
+        this.sum += e - this.ring[this.idx];
+        this.ring[this.idx] = e;
+        this.idx = (this.idx + 1) % this.winN;
+        if (++this.n % this.hopN === 0)
+          this.out.push(Math.sqrt(Math.max(0, this.sum) / Math.min(this.n, this.winN)));
+      }
+    }
+    /** Linear RMS per hop; point i covers the window ending at (i + 1) × hop. */
+    result() { return Float32Array.from(this.out); }
+  }
+  function rmsEnvelope(chs, sampleRate, hop = HOP) {
+    const m = new EnvelopeMeter(chs.length, sampleRate, hop);
+    m.push(chs);
+    return m.result();
+  }
+
+  /** Timeline [start, end] spans where the envelope is above threshold.
+   *  env[i] maps to timeline t0 + (i + 1) × hop / speed; `gain` (linear) is the
+   *  clip's own gain × volume, so a quiet take still counts as voice. */
+  function activeRegions(env, { t0 = 0, hop = HOP, speed = 1, gain = 1, threshold = -40, minLen = 0.25 } = {}) {
+    const lim = Math.pow(10, threshold / 20);
+    const step = hop / Math.max(0.01, speed);
+    const out = [];
+    let a = -1;
+    for (let i = 0; i <= env.length; i++) {
+      const on = i < env.length && env[i] * gain >= lim;
+      if (on && a < 0) a = i;
+      if (!on && a >= 0) {
+        // the window ending at point a started WIN earlier — begin there
+        const s = t0 + Math.max(0, (a + 1) * step - WIN / Math.max(0.01, speed));
+        const e = t0 + i * step;
+        if (e - s >= minLen) out.push([s, e]);
+        a = -1;
+      }
+    }
+    return out;
+  }
+
+  /** Union of region lists; gaps shorter than `gap` seconds are bridged so the
+   *  music doesn't pump between words. */
+  function mergeRegions(lists, gap = 0.6) {
+    const all = lists.flat().filter((r) => r[1] > r[0]).sort((x, y) => x[0] - y[0]);
+    const out = [];
+    for (const [s, e] of all) {
+      const last = out[out.length - 1];
+      if (last && s <= last[1] + gap) last[1] = Math.max(last[1], e);
+      else out.push([s, e]);
+    }
+    return out;
+  }
+
+  /** `duck` keyframes (clip-local seconds, dB) for one music clip.
+   *  Ramps start `attack` s before each region and recover over `release` s
+   *  after it; ramps that would meet stay ducked. Returns [] when no region
+   *  touches the clip. */
+  function duckKeyframes(regions, { start, duration }, { amount = -12, attack = 0.3, release = 0.6 } = {}) {
+    amount = Math.min(0, +amount || 0);
+    const end = start + duration;
+    const spans = mergeRegions([regions.map(([s, e]) => [s - attack, e + release])], 0)
+      .filter(([s, e]) => e > start && s < end);
+    if (!spans.length || !amount) return [];
+    // The envelope in timeline time: each span is 0 → amount (attack) → hold →
+    // amount → 0 (release). A merged span always has attack-end ≤ release-start.
+    const pts = [];
+    for (const [s, e] of spans) pts.push([s, 0], [s + attack, amount], [e - release, amount], [e, 0]);
+    const valAt = (t) => {
+      if (t <= pts[0][0]) return pts[0][1];
+      for (let i = 1; i < pts.length; i++) {
+        const [t1, v1] = pts[i], [t0, v0] = pts[i - 1];
+        if (t <= t1) return t1 > t0 ? v0 + (v1 - v0) * (t - t0) / (t1 - t0) : v1;
+      }
+      return pts[pts.length - 1][1];
+    };
+    // Cut it to the clip: interpolated values on the edges, corners inside.
+    const r3 = (x) => Math.round(x * 1000) / 1000;
+    const keys = [];
+    const put = (t, v) => {
+      t = r3(t - start); v = r3(v) || 0;
+      const last = keys[keys.length - 1];
+      if (last && t <= last.t) { last.v = v; return; } // same instant: latest wins
+      keys.push({ t, v, ease: "linear" });
+    };
+    const v0 = valAt(start), v1 = valAt(end);
+    if (v0) put(start, v0);
+    for (const [t, v] of pts) if (t > start && t < end) put(t, v);
+    if (v1) put(end, v1);
+    // collapse runs of equal values to their two ends
+    return keys.filter((k, i) => !(i > 0 && i < keys.length - 1 &&
+      keys[i - 1].v === k.v && keys[i + 1].v === k.v));
+  }
+
+  return { HOP, WIN, EnvelopeMeter, rmsEnvelope, activeRegions, mergeRegions, duckKeyframes };
+});