@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/curveModel.ts

@@ -0,0 +1,500 @@
+// THE GRAPH EDITOR'S ADAPTER: shot tracks, seen through `TimelineModel`.
+//
+// ── WHY THERE IS NO SVG IN THIS LANE ────────────────────────────────────────
+//
+// `@dailies-studio/timeline`'s `CurveGraph` is a finished value-space curve
+// editor — dense engine sampling so a spring's overshoot is real, keyframe
+// drags in both axes, bezier handles in value space, ctrl+wheel zoom, one
+// history scrub per drag — and it renders and gestures ENTIRELY through a
+// `TimelineModel`. It was built for the motion editor and this lane simply
+// never mounted it. So the work here is a MAPPING, and a second curve editor is
+// not written.
+//
+// model.ts's header explains why the DOCK does not use `TimelineModel`: a bar
+// lane is intervals and that contract is instants. A curve is instants, so the
+// same argument points the other way here.
+//
+// ── THE THREE THINGS THE MAPPING HAS TO GET RIGHT ───────────────────────────
+//
+//   FRAMES ARE CONTAINER-LOCAL. Keyframe frames are scene-local in the document
+//     and `CurveGraph` draws its own ruler from 0, so the curve lives in the
+//     container's own clock end to end. Only `setFrame` crosses back into
+//     master time, through `sceneStart` — THE prefix sum, never a second one.
+//   A VECTOR TRACK IS ONE TRACK. `transform.position` is a single vec3 track,
+//     so its components share keyframe FRAMES. They are drawn as sub-rows and
+//     each one writes the whole vector back with its own slot replaced; the
+//     shared frames are the honest drawing of what the document holds, and
+//     splitting them would be a schema change.
+//   A DRAG IS ONE SCRUB. `gesture` is the dock's own bracket
+//     (`beginBlockDrag` / `captureCurveOps` / `endBlockDrag`), so a curve drag
+//     is one undo entry and Escape restores the base — the same promise every
+//     other gesture in this dock makes.
+import { keyframeAddrKey } from "@dailies-studio/timeline";
+import type { FocusedCurve, KeyframeAddr, TimelineModel, TimelineRow } from "@dailies-studio/timeline";
+import {
+  containerFrame,
+  homeOf,
+  layerChildren,
+  layerTrackablePath,
+  sceneStart,
+  sceneTrackablePath,
+  trackablePath,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, ShotTrack } from "@dailies-studio/shot/doc";
+import type { Rational, TrackKind, Value } from "@dailies-studio/engine";
+import { evaluateTrack } from "@dailies-studio/engine";
+import type { CurveKeyRef, CurveOp, KeyframeSel } from "../../state/types.js";
+import { frontFirst } from "./model.js";
+import type { ShotEditorStore } from "../../state/store.js";
+
+/** One curve's address: a track, and which component of it when it is a
+ *  vector. The pane's focus and every row id are this. */
+export interface CurveSubject {
+  containerId: string;
+  /** Null = the SHOT itself (its background and post stack). */
+  layerId: string | null;
+  path: string;
+  /** Which component of a vector track, or absent for a scalar. */
+  component?: number;
+}
+
+const SEP = "|";
+
+/** `TimelineModel` row ids are OPAQUE to the shared components, so this lane
+ *  gets to choose the encoding. A PIPE, because every part that goes into one
+ *  is an id slug (sc_…, l3_…, cmp_…) or a dotted path, and none can contain it. */
+export function curveRowId(s: CurveSubject): string {
+  return [s.containerId, s.layerId ?? "", s.path, s.component ?? ""].join(SEP);
+}
+
+export function parseCurveRowId(id: string): CurveSubject | null {
+  const [containerId, layerId, path, component] = id.split(SEP);
+  if (containerId === undefined || layerId === undefined || path === undefined) return null;
+  return {
+    containerId,
+    layerId: layerId === "" ? null : layerId,
+    path,
+    ...(component === undefined || component === "" ? {} : { component: Number(component) }),
+  };
+}
+
+export function sameSubject(a: CurveSubject | null, b: CurveSubject | null): boolean {
+  return a !== null && b !== null && curveRowId(a) === curveRowId(b);
+}
+
+/** The component labels a vector track's sub-rows carry. `transform.size` is
+ *  width and height rather than x and y, which is what the inspector calls it. */
+function componentNames(path: string, kind: TrackKind): readonly string[] {
+  if (kind === "vec2") return path === "transform.size" ? ["W", "H"] : ["X", "Y"];
+  if (kind === "vec3") return ["X", "Y", "Z"];
+  return [];
+}
+
+/** Is this kind drawable in VALUE SPACE? A colour and a boolean have no axis, so
+ *  their rows stay dope rows: diamonds, no curve. */
+function numericKind(kind: TrackKind): boolean {
+  return kind === "number" || kind === "vec2" || kind === "vec3";
+}
+
+/** The tracks of one subject, as rows — a vector expanded into its components,
+ *  which is the only way a vec3 reaches a value-space curve at all. */
+export function curveRowsOf(
+  doc: Doc3D,
+  containerId: string,
+  layerId: string | null,
+): Array<TimelineRow & { subject: CurveSubject }> {
+  const tracks = curveTracksOf(doc, containerId, layerId);
+  if (tracks === undefined) return [];
+  // The layer itself, for the LAYER-scoped lookup below: `instance.props.<key>`
+  // is typed by the component's contract, so a global lookup cannot label it or
+  // report its kind. Same `homeOf` route `tracksOf` takes.
+  const layer = layerId === null ? undefined : homeOf(doc, containerId)?.layersById[layerId];
+  const out: Array<TimelineRow & { subject: CurveSubject }> = [];
+  // Sorted by path so two layers with the same tracks list them the same way —
+  // `channelRows`' rule, for its reason: a `Record`'s own order is not one.
+  for (const path of Object.keys(tracks).sort()) {
+    const track = tracks[path]!;
+    const spec =
+      layerId === null
+        ? sceneTrackablePath(path)
+        : layer === undefined
+          ? trackablePath(path)
+          : layerTrackablePath(layer, path);
+    const label = spec?.label ?? path;
+    const kind = spec?.kind ?? track.kind;
+    const keyframes = track.keyframes.map((k) => ({
+      id: k.id,
+      frame: k.frame,
+      easeType: k.easeOut.type,
+    }));
+    const names = componentNames(path, kind);
+    if (names.length === 0) {
+      const subject: CurveSubject = { containerId, layerId, path };
+      out.push({ id: curveRowId(subject), label, depth: 0, numberTrack: numericKind(kind), keyframes, subject });
+      continue;
+    }
+    // The parent row is the TRACK — one row per component under it, because
+    // that is where the keyframes really live and a reader has to see that the
+    // frames are shared.
+    const parent: CurveSubject = { containerId, layerId, path };
+    out.push({ id: curveRowId(parent), label, depth: 0, numberTrack: false, keyframes, subject: parent });
+    names.forEach((name, component) => {
+      const subject: CurveSubject = { containerId, layerId, path, component };
+      out.push({
+        id: curveRowId(subject),
+        label: name,
+        depth: 1,
+        numberTrack: true,
+        keyframes,
+        subject,
+      });
+    });
+  }
+  return out;
+}
+
+/** The tracks of a curve subject. EXPORTED because the pane needs the real
+ *  track — its kind, and which key is last — to build a keyframe menu, and a
+ *  second lookup there would be a second spelling of the `homeOf` rule. */
+export function curveTracksOf(
+  doc: Doc3D,
+  containerId: string,
+  layerId: string | null,
+): Record<string, ShotTrack> | undefined {
+  if (layerId === null) return doc.scenesById[containerId]?.tracks;
+  // THROUGH `homeOf`, which is the one function that reads a scene and a
+  // definition through the same shape — a local branch here would be a second
+  // copy of that rule, and the def arm spells its roots differently.
+  return homeOf(doc, containerId)?.layersById[layerId]?.tracks;
+}
+
+/** The number a curve draws for a value: the value itself, or one component of
+ *  it. Non-numeric collapses to 0 — a row that reaches here is one the pane's
+ *  `numberTrack` gate should not have focused. */
+function numberOf(value: Value | undefined, component: number | undefined): number {
+  if (component !== undefined) return Array.isArray(value) ? Number(value[component] ?? 0) : 0;
+  return typeof value === "number" ? value : 0;
+}
+
+/**
+ * The value axis's unit, as a spread so an unknown unit leaves the field
+ * ABSENT (`exactOptionalPropertyTypes`).
+ *
+ * The doc's trackable paths carry no unit metadata, only a naming rule: every
+ * angle in degrees ends in `Deg` (`transform.rollDeg`, `mesh.primitive.arcDeg`,
+ * `splineFollow.bankDeg`, …). That suffix is the one unit this can say
+ * without guessing, and the inspector's own rows already label those "°".
+ * The keyframe inspector's Value field reads this same function.
+ */
+export function unitOf(path: string): { unit: string } | Record<never, never> {
+  return path.endsWith("Deg") ? { unit: "°" } : {};
+}
+
+/**
+ * One subject's curve: its keys as numbers and THE ENGINE'S OWN SAMPLER, so the
+ * drawn curve and the rendered frame are one function. A local re-implementation
+ * would lose the spring's inherited boundary velocity, which is exactly the
+ * shape an author opens this panel to look at. Null when the track is gone or
+ * has no keys.
+ */
+function curveOf(doc: Doc3D, subject: CurveSubject, fps: Rational): FocusedCurve | null {
+  const track = curveTracksOf(doc, subject.containerId, subject.layerId)?.[subject.path];
+  if (track === undefined || track.keyframes.length === 0) return null;
+  return {
+    rowId: curveRowId(subject),
+    keyframes: track.keyframes.map((k) => ({
+      id: k.id,
+      frame: k.frame,
+      value: numberOf(k.value, subject.component),
+      easeOut: k.easeOut,
+    })),
+    sample: (from, to, n) => {
+      const out: Array<{ frame: number; value: number }> = [];
+      const step = n <= 1 ? 0 : (to - from) / (n - 1);
+      for (let i = 0; i < n; i += 1) {
+        const f = from + step * i;
+        out.push({ frame: f, value: numberOf(evaluateTrack(track, f, fps), subject.component) });
+      }
+      return out;
+    },
+  };
+}
+
+/** The number a curve row reads at a CONTAINER-LOCAL frame, for the list's
+ *  value column. Null when the track is gone or has no keys. */
+export function curveValueAt(doc: Doc3D, subject: CurveSubject, localFrame: number, fps: Rational): number | null {
+  const track = curveTracksOf(doc, subject.containerId, subject.layerId)?.[subject.path];
+  if (track === undefined || track.keyframes.length === 0) return null;
+  return numberOf(evaluateTrack(track, localFrame, fps), subject.component);
+}
+
+/**
+ * Everything `CurveGraph` reads and writes, over one focused track.
+ *
+ * A PLAIN FUNCTION, not a hook: the pane holds the memo (it knows which of its
+ * inputs are identity-stable) and this stays testable without a renderer.
+ */
+export function shotCurveModel(args: {
+  store: ShotEditorStore;
+  doc: Doc3D;
+  /** The container the rows belong to, and its own duration. */
+  containerId: string;
+  containerFrames: number;
+  /** The MASTER playhead. Converted to container-local here and nowhere else. */
+  frame: number;
+  fps: Rational;
+  pxPerFrame: number;
+  focus: CurveSubject | null;
+  rows: Array<TimelineRow & { subject: CurveSubject }>;
+  /** The WHOLE selection, not just its primary: the graph lights every key it
+   *  holds, which is what a marquee or a shift-click has to produce. */
+  selected: readonly { path: string; frame: number; layerId: string | null; containerId: string }[];
+  /** Def-local clocks do not convert: a definition has no master position. */
+  defOpen: boolean;
+  /** The OTHER curves the author has asked to see beside the focused one
+   *  (shift-click in the list). The focused subject is skipped if listed. */
+  visible?: readonly CurveSubject[];
+  /** Each row's list colour, by row id, so the graph draws a curve in the
+   *  colour of its dot. */
+  colors?: ReadonlyMap<string, string>;
+}): TimelineModel {
+  const { store, doc, containerId, fps, focus, rows } = args;
+  const track = focus === null ? undefined : curveTracksOf(doc, focus.containerId, focus.layerId)?.[focus.path];
+  const colorOf = (s: CurveSubject): { color: string } | Record<never, never> => {
+    const c = args.colors?.get(curveRowId(s));
+    return c === undefined ? {} : { color: c };
+  };
+  const curves = (args.visible ?? [])
+    .filter((s) => !sameSubject(s, focus))
+    .flatMap((s) => {
+      const c = curveOf(doc, s, fps);
+      return c === null ? [] : [{ ...c, ...colorOf(s) }];
+    });
+
+  const keyOf = (subject: CurveSubject, keyframeId: string): CurveKeyRef => ({
+    containerId: subject.containerId,
+    layerId: subject.layerId,
+    path: subject.path,
+    keyframeId,
+    ...(subject.component === undefined ? {} : { component: subject.component }),
+  });
+
+  /** A shared `KeyframeAddr` back into this lane's own address. Null when the
+   *  row is not one of ours or the keyframe has gone. */
+  const refOf = (addr: KeyframeAddr): CurveKeyRef | null => {
+    const subject = parseCurveRowId(addr.rowId);
+    if (subject === null) return null;
+    return keyOf(subject, addr.keyframeId);
+  };
+
+  const focusedCurve = focus === null || track === undefined ? null : curveOf(doc, focus, fps);
+
+  // The SELECTION, mapped from the store's position address onto the id one the
+  // shared components use. The store keeps positions on purpose (a key can be
+  // replaced by a drag landing on its frame); this direction is a lookup, and
+  // the reverse — id to position — happens inside the capture against the base.
+  const selectedAddrs: KeyframeAddr[] = [];
+  if (focus !== null) {
+    for (const at of args.selected) {
+      const owner = curveTracksOf(doc, at.containerId, at.layerId)?.[at.path];
+      const key = owner?.keyframes.find((k) => k.frame === at.frame);
+      if (key === undefined) continue;
+      // Every row that draws this track — the parent and each component — shows
+      // the same keyframe, so the selection lights up on whichever is focused.
+      const subject: CurveSubject = {
+        containerId: at.containerId,
+        layerId: at.layerId,
+        path: at.path,
+        ...(focus.path === at.path && focus.component !== undefined ? { component: focus.component } : {}),
+      };
+      selectedAddrs.push({ rowId: curveRowId(subject), keyframeId: key.id });
+    }
+  }
+
+  return {
+    rows,
+    durationFrames: args.containerFrames,
+    fps,
+    frame: args.defOpen
+      ? args.frame
+      : containerFrame(doc, containerId, args.frame),
+    pxPerFrame: args.pxPerFrame,
+    // The dock's own zoom bounds, shared deliberately: the graph and the rows
+    // are two faces of one timeline and a second zoom range would make ⌘-wheel
+    // mean two different things in one panel.
+    pxPerFrameBounds: { min: 0.2, max: 60 },
+    selectedKeyframes: new Set(selectedAddrs.map(keyframeAddrKey)),
+    selectedAddrs,
+    curves,
+    focusedCurve:
+      focus === null || focusedCurve === null
+        ? null
+        : {
+            // Keys and the engine sampler (`curveOf`).
+            ...focusedCurve,
+            ...colorOf(focus),
+            ...unitOf(focus.path),
+          },
+
+    setFrame(next) {
+      // The graph's only caller is CurveGraph's `scrubTo`, a pointer drag on
+      // the ruler and the graph background, so it takes the clock exactly like
+      // the dock's ruler does.
+      store.pauseForScrub();
+      // BACK INTO MASTER TIME, through the one prefix sum. A definition has no
+      // master position at all, so it seeks its own clock.
+      if (args.defOpen) {
+        store.seekDef(next);
+        return;
+      }
+      store.seek(next + (sceneStart(doc, containerId) ?? 0));
+    },
+    setPxPerFrame(px) {
+      store.setDockPpf(px);
+    },
+    selectKeyframes(refs, mode = "set") {
+      // ID TO POSITION, here and only here. The shared components address a key
+      // by its stable id (a React key that moved mid-drag would remount the
+      // circle holding pointer capture); the store keeps positions, because a
+      // drag landing on an occupied frame REPLACES the key an id would still
+      // point at. This is the one seam between the two.
+      const at = refs.flatMap((addr) => {
+        const ref = refOf(addr);
+        if (ref === null) return [];
+        const owner = curveTracksOf(doc, ref.containerId, ref.layerId)?.[ref.path];
+        const key = owner?.keyframes.find((k) => k.id === ref.keyframeId);
+        return key === undefined
+          ? []
+          : [{ containerId: ref.containerId, layerId: ref.layerId, path: ref.path, frame: key.frame }];
+      });
+      if (at.length === 0) {
+        // An empty "set" is a deselect — a marquee that caught nothing. An
+        // empty add/toggle is not: it would clear a selection the author was
+        // extending.
+        if (mode === "set") store.selectKeyframe(null);
+        return;
+      }
+      store.focusScene(at[0]!.containerId);
+      // FOLDED IN ORDER, so the last one the gesture named ends up primary —
+      // which is what makes a shift-click read as "extend to here".
+      at.forEach((k, i) => store.selectKeyframes(k, i === 0 ? mode : "add"));
+    },
+    toggleKeyframe(rowId, frame) {
+      const subject = parseCurveRowId(rowId);
+      if (subject === null) return;
+      store.focusScene(subject.containerId);
+      // AT THE CLICKED FRAME, not the playhead's. The diamond verbs key where
+      // the playhead is because that is what a diamond means; a double-click in
+      // a curve names a point ON the curve, and moving the playhead to reach it
+      // would be the panel answering a different question.
+      store.toggleKeyframeAt(subject.containerId, subject.layerId, subject.path, frame);
+    },
+    setEase(refs, ease) {
+      // One batched write, so an ease on N keys is ONE undo step.
+      const keys: KeyframeSel[] = [];
+      for (const addr of refs) {
+        const ref = refOf(addr);
+        if (ref === null) continue;
+        const owner = curveTracksOf(doc, ref.containerId, ref.layerId)?.[ref.path];
+        const key = owner?.keyframes.find((k) => k.id === ref.keyframeId);
+        if (key === undefined) continue;
+        keys.push({ containerId: ref.containerId, layerId: ref.layerId, path: ref.path, frame: key.frame });
+      }
+      store.setKeyframesEase(keys, ease);
+    },
+    gesture: {
+      begin: () => store.beginBlockDrag(),
+      capture: (ops) => {
+        const mapped: CurveOp[] = [];
+        for (const op of ops) {
+          if (op.kind === "setValue") {
+            const key = refOf(op.ref);
+            if (key !== null) mapped.push({ kind: "setValue", key, value: op.value });
+            continue;
+          }
+          const keys = op.refs.map(refOf).filter((k): k is CurveKeyRef => k !== null);
+          if (keys.length === 0) continue;
+          if (op.kind === "move") {
+            // `snap` rides through verbatim — the ANCHOR (`keys[0]`) survives
+            // the map because `refs.map` preserves order, which is the whole
+            // contract the op's own comment states.
+            mapped.push({
+              kind: "move",
+              keys,
+              deltaFrames: op.deltaFrames,
+              ...(op.snap === undefined ? {} : { snap: op.snap }),
+            });
+          } else mapped.push({ kind: "setEase", keys, ease: op.ease });
+        }
+        store.captureCurveOps(mapped);
+      },
+      end: (commit) => store.endBlockDrag(commit),
+    },
+  };
+}
+
+/**
+ * The layer a curve pane should be showing, given what is selected.
+ *
+ * A LADDER, and the last rung is the one that matters: a pane that opened empty
+ * whenever nothing happened to be selected would read as broken in the most
+ * common case there is — an author switches to the graph to look at the
+ * animation they can already see in the rows.
+ *
+ *   a focused KEYFRAME       the most specific thing the author has pointed at,
+ *                            and it carries its own container (in the scene
+ *                            context the playhead's shot and the clicked
+ *                            diamond's shot can differ).
+ *   the SELECTED layer       what every other panel is showing.
+ *   the shot's own tracks    when it has some: a post-stack animation belongs
+ *                            to the shot and to no layer.
+ *   the first layer that     so the pane opens on something rather than on a
+ *   carries a track          sentence.
+ */
+export function curveSubjectLayer(
+  state: {
+    selectedKeyframe: { containerId: string; layerId: string | null } | null;
+    selection: readonly string[];
+    containerId: string | null;
+  },
+  doc?: Doc3D,
+): { containerId: string; layerId: string | null } | null {
+  const key = state.selectedKeyframe;
+  if (key !== null) return { containerId: key.containerId, layerId: key.layerId };
+  const containerId = state.containerId;
+  if (containerId === null) return null;
+  const first = state.selection[0];
+  if (first !== undefined) return { containerId, layerId: first };
+  if (doc === undefined) return { containerId, layerId: null };
+  if (Object.keys(doc.scenesById[containerId]?.tracks ?? {}).length > 0) return { containerId, layerId: null };
+  return { containerId, layerId: animatedLayers(doc, containerId)[0] ?? null };
+}
+
+/**
+ * Every layer in a container that carries a track, IN OUTLINE ORDER, walking
+ * the forest: the order every other list in this chrome uses (front first,
+ * `frontFirst`), and the only one where "the first" means what a reader would
+ * point at, the highest row. A layer inside a group is reachable, which a flat
+ * scan of the roots would have missed. A group with tracks of its own is listed
+ * before its children.
+ */
+export function animatedLayers(doc: Doc3D, containerId: string): string[] {
+  const home = homeOf(doc, containerId);
+  const out: string[] = [];
+  const walk = (ids: readonly string[]): void => {
+    for (const { id } of frontFirst(ids)) {
+      const layer = home?.layersById[id];
+      if (layer === undefined) continue;
+      if (Object.keys(layer.tracks ?? {}).length > 0) out.push(id);
+      walk(layerChildren(layer));
+    }
+  };
+  walk(home?.layers ?? []);
+  return out;
+}
+
+/** The ALL ANIMATED scope's rows: the shot's own tracks, then every animated
+ *  layer's, each owner's rows in `curveRowsOf` order. */
+export function allAnimatedRows(doc: Doc3D, containerId: string): Array<TimelineRow & { subject: CurveSubject }> {
+  return [null, ...animatedLayers(doc, containerId)].flatMap((layerId) => curveRowsOf(doc, containerId, layerId));
+}

package/src/panels/timeline/duckUnderVoice.ts

@@ -0,0 +1,68 @@
+// "Duck under voice": the mixer's one-press duck, written as the per-clip
+// `duck` the schema already has (audioDuck.ts derives the dip from it in all
+// three mixers). No new field: the button is a shorthand for setting every
+// bed's `duck.sources` to the voice clips, and its pressed state is read back
+// from those same sources, so an author who edits one duck by hand sees the
+// button let go.
+//
+// A VOICE TRACK IS FOUND BY ITS NAME, because the document has no track role.
+// Sound effects are never ducked: a hit under a line is meant to be heard.
+import { authoredAudioClips, audioTracksOf, removeAudioDuck, updateAudioClip } from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+
+const VOICE_RE = /\b(voice|voices|vo|voice-?over|narration|narrator|dialog|dialogue|speech)\b/i;
+const SFX_RE = /\b(sfx|fx|effects?|foley)\b/i;
+
+export interface VoiceDuck {
+  /** Clip ids on voice tracks (a recording's sound counts). */
+  sources: string[];
+  /** Real audio clips on the other, non-effects tracks. */
+  targets: string[];
+}
+
+export function voiceDuckPlan(doc: Doc3D): VoiceDuck {
+  const voice = new Set(audioTracksOf(doc).filter((t) => VOICE_RE.test(t.name)).map((t) => t.id));
+  const sfx = new Set(audioTracksOf(doc).filter((t) => SFX_RE.test(t.name)).map((t) => t.id));
+  const sources: string[] = [];
+  const targets: string[] = [];
+  for (const m of authoredAudioClips(doc)) {
+    if (voice.has(m.trackId)) sources.push(m.clip.id);
+    else if (!sfx.has(m.trackId) && m.layerId === undefined) targets.push(m.clip.id);
+  }
+  return { sources, targets };
+}
+
+/** `available`: there is a voice to duck under and a bed to duck. `active`:
+ *  every bed already ducks under every voice clip. */
+export function voiceDuckState(doc: Doc3D): { available: boolean; active: boolean } {
+  const { sources, targets } = voiceDuckPlan(doc);
+  if (sources.length === 0 || targets.length === 0) return { available: false, active: false };
+  const byId = new Map(authoredAudioClips(doc).map((m) => [m.clip.id, m.clip]));
+  const active = targets.every((id) => {
+    const have = byId.get(id)?.duck?.sources ?? [];
+    return sources.every((s) => have.includes(s));
+  });
+  return { available: true, active };
+}
+
+/** On: add the voice clips to every bed's duck (keeping any other sources and
+ *  the strength). Off: take them out again, and drop a duck left empty. */
+export function applyVoiceDuck(doc: Doc3D, on: boolean): Doc3D {
+  const { sources, targets } = voiceDuckPlan(doc);
+  if (sources.length === 0) return doc;
+  const byId = new Map(authoredAudioClips(doc).map((m) => [m.clip.id, m.clip]));
+  let next = doc;
+  for (const id of targets) {
+    const duck = byId.get(id)?.duck;
+    const have = duck?.sources ?? [];
+    const merged = on ? [...have, ...sources.filter((s) => !have.includes(s))] : have.filter((s) => !sources.includes(s));
+    if (merged.length === have.length && merged.every((s, i) => s === have[i])) continue;
+    next =
+      merged.length === 0
+        ? removeAudioDuck(next, id)
+        : updateAudioClip(next, id, {
+            duck: { sources: merged, ...(duck?.strength === undefined ? {} : { strength: duck.strength }) },
+          });
+  }
+  return next;
+}