@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/audio/meter.ts

@@ -0,0 +1,485 @@
+// THE TAP: one AudioWorkletNode hanging off a GainNode, measuring and never
+// sounding.
+//
+// ── WHY A WORKLET AND NOT AN AnalyserNode ───────────────────────────────
+//
+// `AnalyserNode` answers on the MAIN thread, when asked. A meter built on one
+// samples the signal at whatever rate rAF happens to run at, which means every
+// transient between two frames is invisible and a stalled main thread reads as
+// silence. The peak a mixer exists to show is exactly the thing that model
+// drops. A worklet sees every block, so the attack is measured where the audio
+// is and only the RESULT crosses the thread boundary.
+//
+// ── THE OUTPUT IS NEVER CONNECTED, AND THAT IS THE SAFETY RULE ──────────
+//
+// The node is connected FROM the gain node and its own output goes NOWHERE. A
+// meter that joined the graph would sum a second copy of the signal into the
+// destination: every metered channel 6 dB hot, and the export — which mixes
+// offline and has no meters — would disagree with what the author heard. The
+// processor writes nothing to `outputs` either, so even a mis-wiring downstream
+// could only add silence.
+//
+// ── THE PROCESSOR'S SOURCE IS BUILT HERE, FROM meterMath.ts's ───────────
+//
+// A worklet is loaded by URL, and this chrome is served as one bundle with no
+// second entry point to put a processor file at. So the source is assembled as
+// a string and handed over as a Blob URL. The SMOOTHING inside it is not
+// written here: `METER_STEP_SOURCE` is `meterMath.ts`'s own function,
+// stringified, which is what makes the ballistics unit-testable with no
+// AudioContext anywhere. Read that file's header for the constraint that keeps
+// the function portable.
+//
+// THE SOURCE TEXT'S OWN NAME IS NEVER USED. The chrome is minified, so the
+// text reads `function Xe(…)` in production, and the prelude binds each one to
+// the name `process` calls (`const meterStep = (…);`). `audioMeter.test.ts`
+// runs this processor built from a minified bundle; `sourceHygiene.test.ts`
+// fails any evaluated text in the repo that calls a serialised function by a
+// name it does not bind.
+//
+// `__name` IS DEFINED IN THE PRELUDE ON PURPOSE. esbuild's `keepNames` wraps
+// named functions in a module-scope helper that does not survive being turned
+// into text, and this repo has already shipped one page-injected function that
+// threw `ReferenceError: __name is not defined` while every vitest run stayed
+// green (vitest's transform omits `keepNames`). `meterStep` is written with no
+// inner functions so it cannot need the helper today; the prelude is what stops
+// a future edit reintroducing the failure in a place nothing tests.
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+import { useShotEditor } from "../state/context.js";
+import { recordRuntimeError, runtimeRealmRestarted } from "../state/runtimeErrors.js";
+import {
+  METER_CHANNELS,
+  METER_DIFFERS_SOURCE,
+  METER_FIELDS,
+  METER_FLOOR,
+  METER_MESSAGE_LENGTH,
+  METER_POST_MS,
+  METER_STEP_SOURCE,
+  METER_TUNING,
+  METER_VISIBLE_RATIO,
+  meterVisiblyDiffers,
+} from "./meterMath.js";
+import { clearMeter, publishMeter, readMeter, subscribeMeter } from "./meterStore.js";
+import type { MeterReading } from "./meterStore.js";
+import type { MeterChannel } from "./meterMath.js";
+
+/** The processor's registered name. One string, spelled once: the module text
+ *  and the node constructor must agree or the construction throws. */
+export const METER_PROCESSOR = "dailies-meter";
+
+// --- minimal structural Web Audio surface (fakes stay trivial) ---------------
+//
+// The same posture `preview.ts` takes and for the same reason: no DOM lib types
+// in the signatures, so the jsdom tests drive a hand-rolled fake rather than
+// needing a real audio graph.
+
+export interface MeterContextLike {
+  readonly sampleRate: number;
+}
+
+/**
+ * What a tap hangs off. `disconnect` MUST take a destination: calling the
+ * no-argument form on a monitored gain node would tear down its real output
+ * too, which is the whole mix.
+ */
+export interface MeterSourceLike {
+  connect(destination: unknown): unknown;
+  disconnect(destination?: unknown): void;
+}
+
+export interface MeterPortLike {
+  onmessage: ((event: { data: unknown }) => void) | null;
+  close?(): void;
+}
+
+export interface MeterNodeLike {
+  readonly port: MeterPortLike;
+  disconnect(): void;
+  /** Raised once when the processor throws: it is dead for good. */
+  onprocessorerror?: ((event: unknown) => void) | null;
+}
+
+export interface MeterDeps {
+  /** Compile the processor into this context. Called at most once per context;
+   *  a second call with the same URL is harmless but is not made. */
+  addModule(ctx: MeterContextLike, url: string): Promise<void>;
+  /** Construct the node. Separate from `addModule` because the construction is
+   *  what throws when the module has not landed, and a test wants to drive the
+   *  two independently. */
+  createNode(ctx: MeterContextLike): MeterNodeLike & MeterSourceLike;
+  /** The module URL. One per page in production. */
+  moduleUrl(): string;
+}
+
+/** The whole processor, as text. */
+export function meterWorkletSource(): string {
+  return [
+    // See the header: scoped to this module, never installed on anything else.
+    "const __name = (fn) => fn;",
+    // BOUND BY NAME HERE, never by the text's own name. The shipped chrome is
+    // minified, so `meterStep.toString()` there is `function Xe(…)`, and a bare
+    // declaration would leave `process` calling a `meterStep` that does not
+    // exist: `ReferenceError: meterStep is not defined` on every quantum. As a
+    // parenthesised expression the text's own name no longer matters.
+    `const meterStep = (${METER_STEP_SOURCE});`,
+    `const meterVisiblyDiffers = (${METER_DIFFERS_SOURCE});`,
+    `const TUNING = ${JSON.stringify(METER_TUNING)};`,
+    `const POST_MS = ${JSON.stringify(METER_POST_MS)};`,
+    `const FLOOR = ${JSON.stringify(METER_FLOOR)};`,
+    `const RATIO = ${JSON.stringify(METER_VISIBLE_RATIO)};`,
+    `const CHANNELS = ${JSON.stringify(METER_CHANNELS.length)};`,
+    `const FIELDS = ${JSON.stringify(METER_FIELDS)};`,
+    "class DailiesMeterProcessor extends AudioWorkletProcessor {",
+    "  constructor() {",
+    "    super();",
+    // ONE STATE PER CHANNEL, each through the same `meterStep`: L and R are
+    // two meters that happen to share a quantum, not one meter split.
+    "    this.states = [];",
+    "    for (let c = 0; c < CHANNELS; c++) this.states.push({ rms: 0, peak: 0, hold: 0, holdLeftMs: 0 });",
+    // What the MAIN THREAD currently believes, per channel, which is what a new
+    // post has to be measured against. Born at silence, which is what the
+    // store answers for a channel nobody has published to yet, so the first
+    // audible block posts and a silent start posts nothing at all. Allocated
+    // once; a post overwrites its entries, never the array.
+    "    this.posted = this.states.slice();",
+    "    this.sinceMs = 0;",
+    "  }",
+    "  process(inputs) {",
+    "    const input = inputs[0];",
+    "    const count = input ? input.length : 0;",
+    "    let frames = 0;",
+    "    for (let c = 0; c < count; c++) {",
+    "      const ch = input[c];",
+    "      if (ch && ch.length > frames) frames = ch.length;",
+    "    }",
+    // A DISCONNECTED input reports no channels at all, which is not the same as
+    // a block of zeros: the needle must still decay over the time that passed,
+    // so the quantum falls back to the spec's 128 rather than to nothing.
+    "    if (frames === 0) frames = 128;",
+    "    const dtMs = (frames / sampleRate) * 1000;",
+    "    for (let c = 0; c < CHANNELS; c++) {",
+    // ONE INPUT CHANNEL FEEDS BOTH. The node asks for two with the speakers
+    // rule, so the engine upmixes mono before this runs; an engine (or a
+    // test) that hands over one channel anyway still reads as equal L and R,
+    // never as a dead right side.
+    "      const ch = count === 0 ? null : input[c < count ? c : count - 1];",
+    "      let sum = 0;",
+    "      let peak = 0;",
+    "      const n = ch ? ch.length : 0;",
+    "      for (let i = 0; i < n; i++) {",
+    "        const v = ch[i];",
+    "        sum += v * v;",
+    "        const a = v < 0 ? -v : v;",
+    "        if (a > peak) peak = a;",
+    "      }",
+    "      const rms = n > 0 ? Math.sqrt(sum / n) : 0;",
+    "      this.states[c] = meterStep(this.states[c], rms, peak, dtMs, TUNING);",
+    "    }",
+    "    this.sinceMs += dtMs;",
+    "    if (this.sinceMs < POST_MS) return true;",
+    // EITHER CHANNEL moving is a post, and the post carries both: the main
+    // thread gates each channel again on its own, so a still side costs no
+    // render there.
+    "    let differs = false;",
+    "    for (let c = 0; c < CHANNELS && !differs; c++) {",
+    "      const s = this.states[c];",
+    "      differs = meterVisiblyDiffers(this.posted[c], s.rms, s.peak, s.hold, FLOOR, RATIO);",
+    "    }",
+    // ── THE QUIET PATH, AND WHY IT IS HERE AND NOT ON THE MAIN THREAD ──
+    //
+    // A filter in the `onmessage` handler saves the React commit and nothing
+    // else: the structured clone, the port hop and the main thread's wake-up
+    // have all already happened by the time it runs. This is where that cost
+    // is actually spent, so this is where a silent mix has to stop spending
+    // it. The tap outlives the transport, because the preview's AudioContext
+    // is built on the first play edge and is not suspended afterwards, so
+    // "silent" is the state a metered session sits in for most of its life.
+    //
+    // RE-ARMING IS INSTANT, and that is what `this.sinceMs = POST_MS` buys.
+    // The counter is left ARMED rather than reset, so the gate is re-asked
+    // every render quantum (2.7 ms at 48 kHz) instead of every 16 ms, and the
+    // first audible block posts from inside the very `process` call that saw
+    // it. A meter that misses the attack is worse than a meter that costs 62
+    // commits a second.
+    "    if (!differs) {",
+    "      this.sinceMs = POST_MS;",
+    "      return true;",
+    "    }",
+    "    this.sinceMs = 0;",
+    // A FRESH array per post, copied by the structured clone. Transferring
+    // would detach the buffer and cost an allocation anyway; six floats at
+    // ~60 Hz is not worth a ring buffer and a SharedArrayBuffer's
+    // cross-origin-isolation requirement.
+    "    const out = new Float32Array(CHANNELS * FIELDS);",
+    "    for (let c = 0; c < CHANNELS; c++) {",
+    "      const s = this.states[c];",
+    // THE MAIN THREAD'S GATE, MIRRORED. `onmessage` publishes only the
+    // channels that visibly differ from the store and drops the rest, so a
+    // channel moves its `posted` entry only when it passes the same test.
+    // Advancing a dropped channel's entry would let it creep, one sub-threshold
+    // post at a time, up to two thresholds from what the face shows, and then
+    // never post again.
+    "      if (meterVisiblyDiffers(this.posted[c], s.rms, s.peak, s.hold, FLOOR, RATIO)) this.posted[c] = s;",
+    "      out[c * FIELDS] = s.rms;",
+    "      out[c * FIELDS + 1] = s.peak;",
+    "      out[c * FIELDS + 2] = s.hold;",
+    "    }",
+    "    this.port.postMessage(out);",
+    // TRUE FOR EVER while the node lives. Returning false lets the engine
+    // collect the processor, and a meter that stopped measuring during a quiet
+    // passage would never come back. The quiet path above stops the POSTING,
+    // never the measuring: the needle has to keep falling while nobody is
+    // being told, or the level it re-arms from is the one it had before the
+    // silence.
+    "    return true;",
+    "  }",
+    "}",
+    `registerProcessor(${JSON.stringify(METER_PROCESSOR)}, DailiesMeterProcessor);`,
+  ].join("\n");
+}
+
+/**
+ * ONE Blob URL for the page.
+ *
+ * ponytail: created on first use and never revoked. It is one small object URL
+ * for the life of the document, and revoking it would break the next context's
+ * `addModule` — a second AudioContext is born whenever the preview is disposed
+ * and re-created. Revoke it from a page-teardown hook if a leak is ever
+ * measured; there is nothing else holding it.
+ */
+let moduleUrl: string | null = null;
+function browserModuleUrl(): string {
+  if (moduleUrl === null) {
+    moduleUrl = URL.createObjectURL(new Blob([meterWorkletSource()], { type: "text/javascript" }));
+  }
+  return moduleUrl;
+}
+
+const browserDeps: MeterDeps = {
+  addModule: (ctx, url) => (ctx as unknown as BaseAudioContext).audioWorklet.addModule(url),
+  createNode: (ctx) => {
+    const node = new AudioWorkletNode(ctx as unknown as BaseAudioContext, METER_PROCESSOR, {
+      // ONE output, and it is never connected — see the header. Declaring zero
+      // outputs would also work in Chrome, but "the output exists and goes
+      // nowhere" is the statement the rule is written as, and it is the shape
+      // every other analysis worklet in the wild takes.
+      numberOfOutputs: 1,
+      outputChannelCount: [1],
+      // TWO INPUT CHANNELS, ALWAYS, by the speakers rule: the engine upmixes a
+      // mono master to L = R and downmixes anything wider, so `process` sees
+      // exactly the stereo pair the meter draws. The default ("max") would
+      // hand a mono source over as one channel.
+      channelCount: METER_CHANNELS.length,
+      channelCountMode: "explicit",
+      channelInterpretation: "speakers",
+    });
+    return node as unknown as MeterNodeLike & MeterSourceLike;
+  },
+  moduleUrl: browserModuleUrl,
+};
+
+/** `addModule` is per CONTEXT and must not be repeated: a second compile of the
+ *  same source is wasted work on the audio thread, and two attaches racing at
+ *  the first play edge would both do it. Keyed on the context object, so a
+ *  disposed context's promise is collected with it. */
+const MODULES = new WeakMap<object, Promise<void>>();
+
+function moduleFor(ctx: MeterContextLike, deps: MeterDeps): Promise<void> {
+  const existing = MODULES.get(ctx);
+  if (existing !== undefined) return existing;
+  const pending = deps.addModule(ctx, deps.moduleUrl());
+  MODULES.set(ctx, pending);
+  // A FAILED compile is dropped rather than latched, so the next mount tries
+  // again. Latching would silence every meter in the session over one transient
+  // failure, which is the posture the preview's buffer cache already rejects.
+  void pending.catch(() => {
+    if (MODULES.get(ctx) === pending) MODULES.delete(ctx);
+  });
+  return pending;
+}
+
+interface Tap {
+  key: string;
+  /** How many mounted meters want this node measured. A channel can be on
+   *  screen in two places (a strip and a master bar) and neither may tear the
+   *  other's tap down. */
+  refs: number;
+  node: (MeterNodeLike & MeterSourceLike) | null;
+  /** Set by the last `release`, read by the async bring-up: a mount that
+   *  unmounted while `addModule` was in flight must not leave a node wired to
+   *  a graph nobody is looking at. */
+  dead: boolean;
+}
+
+/** ONE tap per GainNode, and the map holds no strong reference to the graph. */
+const TAPS = new WeakMap<MeterSourceLike, Tap>();
+
+/** Meter nodes whose processor threw and is dead, until each is torn down:
+ *  while any is, the worklet error stands in the stage health. */
+const deadProcessors = new Set<object>();
+
+/**
+ * Measure `source` under `key` until the returned function is called. Each
+ * stereo channel publishes under `meterChannelKey(key, "L" | "R")`.
+ *
+ * Refcounted, so two faces over one bus share one worklet. Idempotent per
+ * (node, key): a second attach under a DIFFERENT key on the same node is
+ * refused rather than silently re-pointed, because one node cannot honestly
+ * publish as two buses and the quiet version of that bug is a master bar
+ * showing a clip's level.
+ */
+export function attachMeter(
+  key: string,
+  ctx: MeterContextLike,
+  source: MeterSourceLike,
+  deps: MeterDeps = browserDeps,
+): () => void {
+  const existing = TAPS.get(source);
+  if (existing !== undefined) {
+    if (existing.key !== key) {
+      console.error(
+        `[audio] meter: this node is already published as ${JSON.stringify(existing.key)}; ` +
+          `refusing to also publish it as ${JSON.stringify(key)}`,
+      );
+      return () => {};
+    }
+    existing.refs += 1;
+    return () => release(source, existing);
+  }
+  const tap: Tap = { key, refs: 1, node: null, dead: false };
+  TAPS.set(source, tap);
+  void moduleFor(ctx, deps)
+    .then(() => {
+      if (tap.dead) return;
+      const node = deps.createNode(ctx);
+      // A processor that throws is dead for good and says so only in the
+      // console: kept for the stage health an agent reads (runtimeErrors.ts),
+      // STANDING until this node is torn down (`release`).
+      node.onprocessorerror = (event) => {
+        const message = (event as { message?: unknown } | null)?.message;
+        deadProcessors.add(node);
+        recordRuntimeError(
+          "audio-worklet",
+          `the level meter's audio worklet processor threw and stopped${typeof message === "string" && message !== "" ? `: ${message}` : " (the browser console has the error)"}`,
+          true,
+        );
+      };
+      // Spelled once per tap, not per post: the handler runs at the post rate.
+      const channels = METER_CHANNELS.map((channel) => meterChannelKey(key, channel));
+      node.port.onmessage = (event) => {
+        const data = event.data;
+        if (!(data instanceof Float32Array) || data.length < METER_MESSAGE_LENGTH) return;
+        for (let c = 0; c < channels.length; c++) {
+          const at = c * METER_FIELDS;
+          // THE GATE BEFORE THE ALLOCATION, PER CHANNEL, which is the half
+          // `publishMeter` cannot do for us: by the time the store had the
+          // object, the object would exist. Same question, same numbers,
+          // asked against what the store is already holding, so a post where
+          // only L moved leaves R's reading (and R's face) alone. See
+          // `meterStore.ts`'s header for why a reading's identity is the
+          // whole contract.
+          if (!meterVisiblyDiffers(readMeter(channels[c]!), data[at]!, data[at + 1]!, data[at + 2]!, METER_FLOOR, METER_VISIBLE_RATIO)) {
+            continue;
+          }
+          publishMeter(channels[c]!, reading(data, at));
+        }
+      };
+      // The tap's ONE connection, and it is inbound only.
+      source.connect(node);
+      tap.node = node;
+    })
+    .catch((e: unknown) => {
+      // Decoration, not the mix: a meter that cannot be built must leave the
+      // audio alone and say so once, rather than failing the play edge.
+      console.error("[audio] meter tap unavailable", e);
+    });
+  return () => release(source, tap);
+}
+
+function reading(data: Float32Array, at: number): MeterReading {
+  return { rms: data[at]!, peak: data[at + 1]!, hold: data[at + 2]!, holdLeftMs: 0 };
+}
+
+/**
+ * The store key one channel of a tap publishes under: `"master:L"`.
+ *
+ * A TAP IS STILL ONE KEY (`attachMeter`'s refusal is about the node, and one
+ * node is one stereo bus), and the store is still one reading per key, so
+ * neither contract had to change shape to carry two channels. Each channel is
+ * its own entry, gated on its own, so a still side never re-renders.
+ */
+export function meterChannelKey(key: string, channel: MeterChannel): string {
+  return `${key}:${channel}`;
+}
+
+function release(source: MeterSourceLike, tap: Tap): void {
+  if (tap.dead) return;
+  tap.refs -= 1;
+  if (tap.refs > 0) return;
+  tap.dead = true;
+  TAPS.delete(source);
+  const node = tap.node;
+  tap.node = null;
+  if (node !== null) {
+    node.port.onmessage = null;
+    node.onprocessorerror = null;
+    // THE SELECTIVE FORM. `source.disconnect()` with no argument would drop the
+    // monitored node's real output as well, which is the mix.
+    try {
+      source.disconnect(node);
+    } catch {
+      // Already torn down with its context; nothing left to unwire.
+    }
+    node.disconnect();
+    node.port.close?.();
+    if (deadProcessors.delete(node) && deadProcessors.size === 0) runtimeRealmRestarted("audio-worklet");
+  }
+  // The face keeps drawing whatever it last saw unless it is told, so the
+  // channel falls to silence rather than freezing at -6 dB over nothing.
+  for (const channel of METER_CHANNELS) clearMeter(meterChannelKey(tap.key, channel));
+}
+
+/**
+ * One channel's live reading, for a face.
+ *
+ * Subscribes to the lane-local store and NOT to the shot store or the hot
+ * channel — see `meterStore.ts`'s header for why neither may carry this.
+ */
+export function useMeterReading(key: string): MeterReading {
+  const subscribe = useCallback((onChange: () => void) => subscribeMeter(key, onChange), [key]);
+  const get = useCallback(() => readMeter(key), [key]);
+  return useSyncExternalStore(subscribe, get, get);
+}
+
+/**
+ * Tap a node while this component is mounted AND no export is running.
+ *
+ * ── BOTH HALVES OF THAT GATE ARE LOAD-BEARING ───────────────────────────
+ *
+ * MOUNTED, because a tap is per-frame work on the audio thread for a bar
+ * nobody is looking at. The effect's cleanup is the detach, so closing the
+ * mixer stops the measuring rather than merely hiding it.
+ *
+ * NO EXPORT LOCK, because an export is the one time this chrome's audio graph
+ * is not the author's monitor. A BROWSER export renders through the visible
+ * stage and a SERVER render has the machine busy; adding a worklet to either is
+ * work competing with the render for the audio thread, and the numbers it would
+ * post describe a mix nobody is listening to. `exportLock` is the store's own
+ * word for both (state/types.ts), and reading it here is the only thing this
+ * lane asks of the shot store.
+ *
+ * `source` is null until the graph exists — the preview builds its context
+ * lazily on the first play edge, which is the user gesture — so a face mounts
+ * over silence and starts metering when the node arrives.
+ */
+export function useMeterTap(
+  key: string,
+  ctx: MeterContextLike | null,
+  source: MeterSourceLike | null,
+  deps?: MeterDeps,
+): void {
+  const exporting = useShotEditor((s) => s.exportLock !== null);
+  useEffect(() => {
+    if (ctx === null || source === null || exporting) return;
+    return attachMeter(key, ctx, source, deps);
+  }, [key, ctx, source, exporting, deps]);
+}