@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/audio/meterMath.ts

@@ -0,0 +1,273 @@
+// THE METER'S BALLISTICS, AS A PLAIN FUNCTION, BECAUSE THE AUDIO THREAD IS THE
+// ONE PLACE A UNIT TEST CANNOT GO.
+//
+// An AudioWorkletProcessor runs inside `AudioWorkletGlobalScope`: no DOM, no
+// module graph a test can reach into, and no way to observe it except by
+// building a real AudioContext and listening to what it posts. So the smoothing
+// — which is the only part with an opinion in it — lives out here as an
+// ordinary exported function, and the worklet gets its SOURCE TEXT rather than
+// a second copy of the arithmetic. One implementation, and the tests drive it
+// directly with no AudioContext at all.
+//
+// ── THE FUNCTION MUST BE SELF-CONTAINED, AND THAT IS A REAL CONSTRAINT ──
+//
+// `meterStep.toString()` is what crosses into the worklet. Anything the body
+// references that is not a JavaScript builtin or one of its own parameters does
+// not exist on the other side, and the failure is a `ReferenceError` inside an
+// audio thread whose console output is easy to miss. So:
+//
+//   NO module-level constants in the body. The tuning is a PARAMETER, and the
+//     worklet's source interpolates `METER_TUNING` as JSON beside the function.
+//   NO nested function declarations or arrow consts. esbuild's `keepNames`
+//     wraps every named function — nested ones included — in a module-scope
+//     `__name` helper, which does not survive serialisation. This repo has been
+//     bitten by exactly that once already, in the page-injected collector that
+//     threw `ReferenceError: __name is not defined` inside the page while every
+//     vitest run stayed green (vitest's transform omits `keepNames`). The body
+//     below therefore has no inner functions at all, and `meter.ts` defines a
+//     scoped `__name` in the worklet prelude anyway, so the class cannot come
+//     back through a future edit.
+//
+//   NO RELIANCE ON THE NAME. The shipped chrome is minified, so this text
+//     reads `function Xe(…)` there. The worklet binds it by its own
+//     `const meterStep = (…)`, and a consumer must never call it by the name
+//     written below.
+//
+// `test/audioMeter.test.ts` proves the constraint rather than asserting it in
+// prose: it rebuilds the function from `METER_STEP_SOURCE` alone, in a scope
+// with nothing in it, and checks it answers what the imported one answers. It
+// also builds the worklet from a minified bundle and runs `process` there.
+
+/** What a meter's needle does, in milliseconds. */
+export interface MeterTuning {
+  /** Rising. FAST, because a transient the eye never sees is a transient the
+   *  author cannot mix against: a meter that misses the peak of a consonant
+   *  reads 6 dB low on speech. */
+  attackMs: number;
+  /** Falling. SLOW, because a needle that tracks the waveform down is a blur.
+   *  This is the number that makes a meter readable at all. */
+  releaseMs: number;
+  /** How long the peak marker STAYS where the loudest sample put it. */
+  holdMs: number;
+  /** How fast it falls once the hold expires. Slower than `releaseMs`, so the
+   *  marker is still visibly above the bar when it starts to move. */
+  holdReleaseMs: number;
+}
+
+/**
+ * The house ballistics.
+ *
+ * ponytail: one set of numbers, no per-meter override. They are roughly a
+ * digital peak-programme meter's, which is the face every NLE mixer wears, and
+ * nothing in this chrome has asked for a second calibration. Add a parameter if
+ * a second meter is ever measured needing one.
+ */
+export const METER_TUNING: MeterTuning = {
+  attackMs: 5,
+  releaseMs: 300,
+  holdMs: 1200,
+  holdReleaseMs: 900,
+};
+
+/** Linear amplitude, 0..1-ish. Not dB: the conversion is a FACE decision and a
+ *  meter drawn in dB and a meter drawn on a linear bar want the same state. */
+export interface MeterState {
+  rms: number;
+  peak: number;
+  /** The peak marker: the highest recent peak, held then released. */
+  hold: number;
+  /** Milliseconds of hold left before the marker starts falling. */
+  holdLeftMs: number;
+}
+
+/** Frozen, so every idle meter shares one snapshot identity —
+ *  `useSyncExternalStore` compares by identity and a fresh object per read is
+ *  an infinite render loop. */
+export const METER_SILENT: MeterState = Object.freeze({ rms: 0, peak: 0, hold: 0, holdLeftMs: 0 });
+
+/**
+ * One step of the meter, over `dtMs` of audio.
+ *
+ * SELF-CONTAINED by contract — see this file's header. Builtins only, no inner
+ * functions, and every tuning number arrives as a parameter.
+ *
+ * The smoothing is a one-pole filter whose coefficient is `exp(-dt / tau)`,
+ * which is the fraction of the OLD value still present after `dt`. Written that
+ * way rather than as a fixed per-block factor because the render quantum's
+ * duration depends on the context's sample rate: a coefficient tuned at 48 kHz
+ * would make the needle 8% faster on a 44.1 kHz device, and the author would be
+ * mixing against a different meter on a different machine.
+ *
+ * ATTACK AND RELEASE ARE THE SAME FILTER with different taus, chosen by
+ * direction. That is what a peak-programme meter is, and it is why a bar that
+ * simply averaged looked dead on speech.
+ *
+ * NON-FINITE IN IS ZERO, not propagated. A NaN sample (a source that has
+ * glitched, an uninitialised buffer) would otherwise poison the state for the
+ * life of the tap: every later `Math.exp` blend of a NaN is a NaN, the bar goes
+ * blank, and nothing says why.
+ */
+export function meterStep(
+  state: MeterState,
+  rms: number,
+  peak: number,
+  dtMs: number,
+  tuning: MeterTuning,
+): MeterState {
+  const dt = Number.isFinite(dtMs) && dtMs > 0 ? dtMs : 0;
+  const inRms = Number.isFinite(rms) && rms > 0 ? rms : 0;
+  const inPeak = Number.isFinite(peak) && peak > 0 ? peak : 0;
+  const prevRms = Number.isFinite(state.rms) && state.rms > 0 ? state.rms : 0;
+  const prevPeak = Number.isFinite(state.peak) && state.peak > 0 ? state.peak : 0;
+  const attack = Math.exp(-dt / (tuning.attackMs > 0 ? tuning.attackMs : 1e-3));
+  const release = Math.exp(-dt / (tuning.releaseMs > 0 ? tuning.releaseMs : 1e-3));
+  const nextRms = inRms + (prevRms - inRms) * (inRms > prevRms ? attack : release);
+  const nextPeak = inPeak + (prevPeak - inPeak) * (inPeak > prevPeak ? attack : release);
+
+  // ── THE PEAK MARKER ──────────────────────────────────────────────────
+  //
+  // Against the RAW peak of this block and not against the smoothed one: the
+  // marker exists to record the loudest sample that actually happened, and
+  // reading it off a needle that is still climbing would under-report every
+  // transient by exactly the attack it just applied.
+  let hold = Number.isFinite(state.hold) && state.hold > 0 ? state.hold : 0;
+  let holdLeftMs = Number.isFinite(state.holdLeftMs) && state.holdLeftMs > 0 ? state.holdLeftMs : 0;
+  if (inPeak >= hold) {
+    hold = inPeak;
+    holdLeftMs = tuning.holdMs > 0 ? tuning.holdMs : 0;
+  } else if (holdLeftMs > dt) {
+    holdLeftMs = holdLeftMs - dt;
+  } else {
+    holdLeftMs = 0;
+    hold = hold * Math.exp(-dt / (tuning.holdReleaseMs > 0 ? tuning.holdReleaseMs : 1e-3));
+    // The marker may never fall BELOW the needle it marks: a hold that sank
+    // under the bar reads as a second, quieter peak that never happened.
+    if (hold < nextPeak) hold = nextPeak;
+  }
+  return { rms: nextRms, peak: nextPeak, hold, holdLeftMs };
+}
+
+/**
+ * The bytes the worklet gets.
+ *
+ * A module-level `toString()` and not a call per attach: the string is fixed
+ * for the life of the page, and reading it once is what lets `meter.ts` build
+ * ONE Blob URL for every context.
+ */
+export const METER_STEP_SOURCE: string = meterStep.toString();
+
+// ── WHEN A CHANGE IS WORTH TELLING ANYONE ABOUT ─────────────────────────
+//
+// The tap measures whether or not anything is sounding, and it measures for as
+// long as a face is mounted. Without a gate that costs a structured clone
+// across the thread boundary and a React commit per post, for ever, over a
+// silent mix on a paused transport. The gate is the SAME question on both
+// sides of the port ("could a face tell these two apart?"), so it lives here
+// beside the ballistics and crosses into the worklet as text, exactly as
+// `meterStep` does.
+
+/**
+ * The bottom of the scale, in dB, and the ONE place it is spelled.
+ *
+ * It began as a face decision in the meter's component, and it is still drawn
+ * there (`meterPercent`, panels/timeline/SoundMode.tsx). It moved here because
+ * the publisher's "indistinguishable"
+ * test is defined against the scale the face draws: two levels below the floor
+ * are the same picture, and a second -60 in a second file is a drift that would
+ * show up as a meter that either dithered or went deaf.
+ */
+export const METER_FLOOR_DB = -60;
+
+/** The floor as LINEAR amplitude, which is the unit the state is kept in. */
+export const METER_FLOOR = 10 ** (METER_FLOOR_DB / 20);
+
+/**
+ * How far a level must move before anybody is told, in dB.
+ *
+ * PICKED OFF THE PIXELS, for the 72px header meter this was first drawn in:
+ * one DEVICE pixel there was 60 / (72 * dpr) dB, 0.21 dB even at dpr 4, so
+ * nothing suppressed could move it. The meters now live in the Sound mode's
+ * mixer (SoundMode.tsx), a continuous vertical bar per channel no taller than
+ * the strip, so the same arithmetic holds there. What it can also move is the
+ * readout's one decimal, by a tenth or two, and only for a level sitting
+ * nearly still: a moving one crosses the threshold on every post (see below).
+ *
+ * NOT COARSER, because the release is 300 ms and a 16 ms post is therefore
+ * 0.47 dB of fall: a 1 dB threshold would hold three posts back and then jump
+ * the needle three pixels, which is the stair-step a meter exists to not have.
+ * Not finer, because below a device pixel there is nothing left to show.
+ */
+export const METER_VISIBLE_DB = 0.2;
+
+/** The same threshold as an amplitude RATIO, so the test is two multiplies and
+ *  no logarithm on the audio thread. */
+export const METER_VISIBLE_RATIO = 10 ** (METER_VISIBLE_DB / 20);
+
+/**
+ * Could a face tell these two apart? The publisher's gate, and the worklet's.
+ *
+ * SELF-CONTAINED by the same contract as `meterStep` (see this file's header):
+ * it crosses into the worklet as text, so the floor and the ratio arrive as
+ * parameters and there are no inner functions in the body.
+ *
+ * The candidate arrives as three LOOSE FLOATS rather than as a state object
+ * because both callers hold them loose (the port hands the main thread a
+ * `Float32Array`, the worklet holds its own fields), and building an object to
+ * ask the question would be the allocation the question exists to avoid.
+ *
+ * BELOW THE FLOOR EVERYTHING IS ONE LEVEL. The face draws 0% for all of it, and
+ * a release that keeps halving toward a denormal would otherwise notify for
+ * ever without ever changing the picture. Above the floor the test is a RATIO
+ * and not a difference, because the bar is logarithmic: 0.001 of amplitude is
+ * 9 dB of bar near the floor and a thousandth of a pixel at the top, so a
+ * linear epsilon would either dither down there or go deaf up here.
+ *
+ * `holdLeftMs` IS DELIBERATELY NOT COMPARED. Nothing draws it: it is the
+ * marker's own countdown, and the marker's POSITION is `hold`, which is
+ * compared. Notifying on it alone would be the 62 Hz churn back again with no
+ * pixel to show for it.
+ */
+export function meterVisiblyDiffers(
+  prev: MeterState,
+  rms: number,
+  peak: number,
+  hold: number,
+  floor: number,
+  ratio: number,
+): boolean {
+  // Written out three times, with two reused locals and no inner helper: a
+  // nested function does not survive the trip into the worklet.
+  let a = prev.rms > floor ? prev.rms : 0;
+  let b = rms > floor ? rms : 0;
+  if ((a > b ? a : b) > (a < b ? a : b) * ratio) return true;
+  a = prev.peak > floor ? prev.peak : 0;
+  b = peak > floor ? peak : 0;
+  if ((a > b ? a : b) > (a < b ? a : b) * ratio) return true;
+  a = prev.hold > floor ? prev.hold : 0;
+  b = hold > floor ? hold : 0;
+  return (a > b ? a : b) > (a < b ? a : b) * ratio;
+}
+
+/** The gate's bytes, for the worklet. Same reason as `METER_STEP_SOURCE`. */
+export const METER_DIFFERS_SOURCE: string = meterVisiblyDiffers.toString();
+
+/** How often the processor posts AT MOST, in milliseconds. About one animation
+ *  frame: faster is invisible and costs a structured clone per post, slower is
+ *  a meter that stutters against the picture. A post is only made when
+ *  `meterVisiblyDiffers` says the picture changed, so this is a ceiling and not
+ *  a cadence. */
+export const METER_POST_MS = 16;
+
+/** The channels a tap measures, in post order: the master is STEREO, and a
+ *  mono source is upmixed to both by the node's own channel rules (`meter.ts`,
+ *  `createNode`), so it reads as equal L and R. */
+export const METER_CHANNELS = ["L", "R"] as const;
+export type MeterChannel = (typeof METER_CHANNELS)[number];
+
+/** The numbers ONE channel carries, in order: rms, peak, hold. */
+export const METER_FIELDS = 3;
+
+/** What a post carries: each channel's three numbers, L first. A
+ *  `Float32Array` of exactly this length, so the reader indexes rather than
+ *  parsing. The worklet and the `onmessage` guard both read it from here. */
+export const METER_MESSAGE_LENGTH = METER_FIELDS * METER_CHANNELS.length;

package/src/audio/meterStore.ts

@@ -0,0 +1,155 @@
+// WHERE A METER'S NUMBERS LIVE, AND IT IS NOT THE SHOT STORE.
+//
+// A tap posts about sixty times a second, for as long as anything is sounding.
+// There are exactly two channels in this chrome and neither of them may carry
+// that:
+//
+//   THE SHOT STORE is what every panel in the shell subscribes to, and its
+//     notifications are what re-derive the inspector, the outline and the dock.
+//     A level is not document state, does not survive a reload, and must never
+//     enter the undo history — putting it there would make a meter tick an edit.
+//   THE HOT CHANNEL (`useShotEditorHot`) is THE FRAME. Its contract is "the
+//     smallest leaf that must repaint every tick", and a level is neither the
+//     frame nor on the frame's schedule: a paused transport still meters a
+//     monitored input, and a playing one posts on the AUDIO clock.
+//
+// So this is a lane-local store on the same terms `panels/timeline/viewport.ts`
+// is one, and its header states the rule both obey.
+//
+// ── IDENTITY IS THE WHOLE CONTRACT ──────────────────────────────────────
+//
+// `useSyncExternalStore` compares snapshots with `Object.is` and calls its
+// getter during render, so `read` must return the SAME object until the value
+// actually changes and must never allocate. An unknown key answers one frozen
+// silent reading rather than a fresh zero object, which is what stops a mounted
+// meter over a channel nobody is tapping from re-rendering for ever.
+import {
+  METER_FLOOR,
+  METER_SILENT,
+  METER_VISIBLE_RATIO,
+  meterVisiblyDiffers,
+} from "./meterMath.js";
+import type { MeterState } from "./meterMath.js";
+
+/** What a face reads. The full `MeterState` — `holdLeftMs` included — because
+ *  the tap owns the ballistics and a second decay out here would be a second
+ *  set of ballistics that disagreed with the first. */
+export type MeterReading = MeterState;
+
+export { METER_SILENT };
+
+interface Entry {
+  reading: MeterReading;
+  listeners: Set<() => void>;
+}
+
+/**
+ * Keyed by a STRING, not by the GainNode.
+ *
+ * The node is the tap's business (`meter.ts` keys its WeakMap on it), and a
+ * face that had to hold a live audio node in order to draw a bar would be a
+ * React component pinning a Web Audio graph across every re-render. A key is a
+ * name the chrome chooses — "master", a clip id — so a face can subscribe
+ * before the tap exists and keep drawing silence until it does.
+ */
+const ENTRIES = new Map<string, Entry>();
+
+/** The current reading. Stable by identity between publishes, and it never
+ *  creates an entry: a getter with a side effect is a subscription attached
+ *  from a render React may throw away. */
+export function readMeter(key: string): MeterReading {
+  return ENTRIES.get(key)?.reading ?? METER_SILENT;
+}
+
+/** Subscribe to one channel. Returns the unsubscribe, which drops the entry
+ *  with the last listener AND with no reading left to serve, so a meter that
+ *  unmounts leaves nothing behind in the map. */
+export function subscribeMeter(key: string, listener: () => void): () => void {
+  let entry = ENTRIES.get(key);
+  if (entry === undefined) {
+    entry = { reading: METER_SILENT, listeners: new Set() };
+    ENTRIES.set(key, entry);
+  }
+  entry.listeners.add(listener);
+  const held = entry;
+  return () => {
+    held.listeners.delete(listener);
+    if (held.listeners.size === 0 && held.reading === METER_SILENT) ENTRIES.delete(key);
+  };
+}
+
+/**
+ * Publish one channel's reading. Called from a `MessagePort` handler at the
+ * post rate, so it does exactly three things: decide whether anybody could
+ * SEE the difference, replace the object, and notify.
+ *
+ * ── THE GATE IS THE CONTRACT AT THE TOP OF THIS FILE, ENFORCED ──────────
+ *
+ * "`read` must return the SAME object until the value actually changes" is a
+ * promise the READER cannot keep on its own. A publisher that swapped the
+ * object on every post kept the letter of it and broke the sense: a mounted
+ * meter re-rendered at the worklet's post rate for ever, playing or not,
+ * silent or not, because every post was a new identity. So the publisher is
+ * what decides that the value actually changed, and `meterVisiblyDiffers`
+ * (meterMath.ts) is the definition of "actually": a move the face could not
+ * draw is not a change, and the same question is asked on the audio thread
+ * before the post is even made.
+ *
+ * SILENCE LANDS ON THE FROZEN SINGLETON, exactly, rather than on a small
+ * number near it. A release is asymptotic and never reaches zero, so without
+ * this the lane's rest state would be whatever amplitude the decay happened to
+ * be at when the gate closed: `readMeter` would hand back a private object
+ * instead of `METER_SILENT`, and `subscribeMeter`'s unsubscribe, which drops
+ * an entry only when its reading IS `METER_SILENT`, would leak the entry.
+ *
+ * A listener that THROWS must not stop the others hearing about it. This lane
+ * is decoration: a meter face that blew up may not take the mixer's other bars
+ * down with it, which is the posture the filmstrip loader's notify already
+ * takes for the same reason.
+ */
+export function publishMeter(key: string, reading: MeterReading): void {
+  const entry = ENTRIES.get(key);
+  const prev = entry === undefined ? METER_SILENT : entry.reading;
+  if (!meterVisiblyDiffers(prev, reading.rms, reading.peak, reading.hold, METER_FLOOR, METER_VISIBLE_RATIO)) {
+    return;
+  }
+  const next =
+    reading.rms <= METER_FLOOR && reading.peak <= METER_FLOOR && reading.hold <= METER_FLOOR
+      ? METER_SILENT
+      : reading;
+  if (entry === undefined) {
+    ENTRIES.set(key, { reading: next, listeners: new Set() });
+    return;
+  }
+  entry.reading = next;
+  for (const listener of [...entry.listeners]) {
+    try {
+      listener();
+    } catch {
+      // See above.
+    }
+  }
+}
+
+/**
+ * The channel has stopped being tapped: fall to silence and say so.
+ *
+ * NOT a delete when someone is listening. A face subscribed to a channel whose
+ * tap just detached has to be told, or it keeps the last level it was handed
+ * painted on screen for ever — a meter frozen at -6 dB over a silent mix, which
+ * reads as a signal rather than as a missing one.
+ */
+export function clearMeter(key: string): void {
+  const entry = ENTRIES.get(key);
+  if (entry === undefined) return;
+  if (entry.listeners.size === 0) {
+    ENTRIES.delete(key);
+    return;
+  }
+  publishMeter(key, METER_SILENT);
+}
+
+/** Test hook, and the one way to empty the map without a subscriber churn. */
+export function resetMeters(): void {
+  ENTRIES.clear();
+}