@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/AudioLane.tsx

@@ -1,12 +1,42 @@
-// The audio lane: one coloured band per clip at its MASTER position.
+// The audio lanes: one coloured band per clip, in whichever of the two homes
+// holds it.
 //
-// ── WHY IT IS ONE LANE AND NOT A TRACK PER CLIP ─────────────────────────
+// ── TWO HOMES, TWO PLACES ON SCREEN ─────────────────────────────────────
 //
-// `doc.audio` is a flat record of master-timed clips with no lane field, and
-// the reference editor draws one music bed under the whole video. A lane-packer
-// would be inventing a document concept the schema deliberately does not have,
-// and the first thing it would need is somewhere to persist which lane a clip
-// landed in. Clips overlap by drawing over each other, in document order.
+// `doc.audio` is the BED — master-timed, spanning the cuts — and it draws here,
+// at the bottom of the dock, where every NLE puts the music. `Scene3D.audio`
+// (schema v13) is the sound a SHOT owns, and it draws inside that shot's group
+// (`SceneAudioRow`), because that is what owning it means: it moves, duplicates
+// and dies with the shot, and it is cut at the shot's end.
+//
+// Both use `AudioClipBar`, which is base-agnostic — it takes `offsetFrames`
+// (the shot's master start, or 0 for the bed) exactly as `BlockRow` does, and
+// every gesture below it is a signed DELTA, which means the same thing in
+// either frame base. The one thing that is not base-agnostic is the snap
+// anchor, which is always master, and that is what `offsetFrames` is added into.
+//
+// ── A THIRD SOUND EXISTS, AND IT IS DRAWN SOMEWHERE ELSE ────────────────
+//
+// A video layer's `video.sound` reaches the mix through `masterAudioClips` as a
+// VIRTUAL clip whose id is the layer id and whose `MasterAudioClip.layerId` is
+// set. It is deliberately absent from both lanes here: it is drawn in the video
+// row itself (`LifespanRow`), under that recording's filmstrip, because a
+// soundtrack that appears in two places is one an author can trim in the wrong
+// one. Both lanes read their own record (`doc.audio`, `Scene3D.audio`), so this
+// is a property of WHERE THEY READ rather than a filter they apply, and there
+// is no `layerId` on an `AudioClipRef` for a filter to test.
+//
+// The one place the flatten IS read here is `duckCandidates`, which must offer
+// the virtual clips: ducking a bed under a recording's dialogue is the case the
+// feature exists for, and naming a source is not drawing a bar.
+//
+// ── WHY EACH IS ONE LANE AND NOT A TRACK PER CLIP ───────────────────────
+//
+// Neither record has a lane field, and the reference editor draws one music bed
+// under the whole video. A lane-packer would be inventing a document concept
+// the schema deliberately does not have, and the first thing it would need is
+// somewhere to persist which lane a clip landed in. Clips overlap by drawing
+// over each other, in document order.
 //
 // ── THE GESTURES ────────────────────────────────────────────────────────
 //
@@ -15,41 +45,126 @@
 //   IN / OUT  trim; the head trim moves `offsetFrames` with `frame` so the
 //             audio under the remaining bar does not slide.
 //   FADES     the two corner handles, dragged along the bar.
-//   GAIN      the horizontal rubber band, dragged vertically.
+//   GAIN      the horizontal rubber band, dragged vertically — and once the
+//             clip has a `gainTrack`, the band edits the KEY at the playhead
+//             and the flat line becomes the sampled envelope.
+//
+// GAIN is Sound mode's only (`mix`), with the duck, the gain key and the clip
+// mute. Mixing lives in the Sound tab, so these rows stay slim: the waveform,
+// move, trim, fades and the home switch.
 //
 // All of them go through `beginBlockDrag`/`endBlockDrag`, which is the dock's
 // ONE history scrub: each gesture is one undo entry and Escape restores the
 // base by reference. All of them snap through the shared `snap.ts` — there is
 // no second snapper in this lane.
 import { useEffect, useRef, useState } from "react";
-import type { PointerEvent as ReactPointerEvent } from "react";
+import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from "react";
 import { drawClipWaveform, frameToPx, loadPeaks, startDrag } from "@dailies-studio/timeline";
 import type { PeakData } from "@dailies-studio/timeline";
+import { IconVolume, IconVolumeOff } from "@dailies-studio/ui";
 import { framesToSeconds } from "@dailies-studio/engine";
 import type { Rational } from "@dailies-studio/engine";
-import { MAX_AUDIO_GAIN } from "@dailies-studio/shot/doc";
-import type { AudioClipRef, ShotAsset } from "@dailies-studio/shot/doc";
+import {
+  DUCK_DEFAULT_STRENGTH,
+  DUCK_MAX_DEPTH_DB,
+  MAX_AUDIO_GAIN,
+  audioGainSampler,
+  masterAudioClips,
+} from "@dailies-studio/shot/doc";
+import type { AudioClipRef, ShotAsset, ShotTrack } from "@dailies-studio/shot/doc";
+import { useStudioTheme } from "@dailies-studio/ui/theme";
 import { useShotEditor, useStore } from "../../state/context.js";
-import { audioClipView, frameDelta } from "./model.js";
+import { ACCEPTED_AUDIO_EXTENSIONS } from "../storyboard/storyboardDrop.js";
+import { AUDIO_ROW_H, audioClipView, frameDelta } from "./model.js";
 import type { AudioDrag } from "./model.js";
 import { isSnapSuppressed } from "./snap.js";
+import { AudioFxButton } from "./AudioFxButton.js";
 import type { SnapPress } from "./snap.js";
+import { formatCombo } from "../../state/shortcuts.js";
+
+const WAVE_COLOR_FALLBACK = "rgba(150, 205, 255, 0.7)";
+/**
+ * Mirrors of timeline-rows.css, pinned to it by audioLane.test: `.audio-lane`'s
+ * height (with its 1px top seam), `.scene-audio-row`'s height, and
+ * `.audio-clip`'s inset top and bottom.
+ *
+ * ONE AUDIO ROW HEIGHT. A shot's own row is the boards' 32px lane too: inside
+ * a shot it is the only audio row on screen (see `AudioLane`'s shot-context
+ * early return), and two heights for one medium read as two features.
+ * `groupHeights` counts it through this constant.
+ */
+export const AUDIO_LANE_H = AUDIO_ROW_H;
+export const SHOT_AUDIO_ROW_H = AUDIO_LANE_H;
+export const AUDIO_CLIP_INSET = 4;
+/**
+ * A clip bar's inner height per row kind, in px: what the waveform canvas, the
+ * fade ramp and the gain envelope are drawn into. The row less the bar's two
+ * insets and its 1px border; the master lane also pays its top seam.
+ */
+const MASTER_WAVE_H = AUDIO_LANE_H - 1 - 2 * AUDIO_CLIP_INSET - 2;
+const SHOT_WAVE_H = SHOT_AUDIO_ROW_H - 2 * AUDIO_CLIP_INSET - 2;
 
-const WAVE_COLOR = "rgba(150, 205, 255, 0.7)";
-/** Canvas px. Matches the bar's inner height in styles.css. */
-const WAVE_H = 26;
+/**
+ * What the Sound tab's file input offers and what the drop box says, from ONE
+ * list: the extensions the import accepts (storyboardDrop's mirror of the
+ * CLI's audio kinds). Extensions only, no MIME types: `audio/ogg` would also offer an
+ * `.opus` the import then refuses, and the picker should not offer a file the
+ * drop would turn away.
+ */
+export const AUDIO_FILE_ACCEPT = ACCEPTED_AUDIO_EXTENSIONS.join(",");
+export const AUDIO_FORMAT_HINT = ACCEPTED_AUDIO_EXTENSIONS.map((ext) => ext.slice(1).toUpperCase()).join(" / ");
 
-export function AudioLane(props: { ppf: number; labelWidth: number; beginSnap?: SnapPress }) {
-  const { ppf, labelWidth, beginSnap } = props;
+/** The empty row's drop box, shared by the master lane and a shot's own row so
+ *  the two say the same sentence in the same shape. */
+function AudioDropBox() {
+  return (
+    <span className="audio-empty">
+      <span className="audio-empty-copy">Drop an audio file, or press + to add sound</span>
+      <span className="audio-empty-formats">{AUDIO_FORMAT_HINT}</span>
+    </span>
+  );
+}
+
+export function AudioLane(props: {
+  ppf: number;
+  labelWidth: number;
+  beginSnap?: SnapPress;
+  /**
+   * The SHOT CONTEXT's window, or absent in the scene context. Clips are
+   * MASTER-timed and stay so; this re-zeros the lane on the shot and keeps
+   * the clips that OVERLAP it.
+   *
+   * Overlap and not containment, and the difference is the common case: a music
+   * bed spans the whole video, so a containment test would empty the lane in
+   * every shot — in a tool whose launch deliverable is a 52-second music ad.
+   * A bed that starts before the shot is drawn from a negative x and its head is
+   * clipped by the track box, which is the honest read: it continues off-screen
+   * to the left because it continues before this shot.
+   */
+  shotWindow?: { origin: number; len: number } | undefined;
+}) {
+  const { ppf, labelWidth, beginSnap, shotWindow } = props;
+  const origin = shotWindow?.origin ?? 0;
   const store = useStore();
   const doc = useShotEditor((s) => s.doc);
   const [error, setError] = useState<string | null>(null);
   const [importing, setImporting] = useState(false);
   const [over, setOver] = useState(false);
-  const fileRef = useRef<HTMLInputElement | null>(null);
 
   if (doc === null) return null;
-  const clips = Object.values(doc.audio);
+  const clips = Object.values(doc.audio).filter((clip) => {
+    if (shotWindow === undefined) return true;
+    const start = Math.trunc(clip.frame);
+    const end = start + Math.max(1, Math.trunc(clip.durationFrames));
+    return end > shotWindow.origin && start < shotWindow.origin + shotWindow.len;
+  });
+  // INSIDE A SHOT WITH NO BED OVER IT, THE SHOT'S OWN ROW IS THE AUDIO ROW. That
+  // row already draws the drop box (`SceneAudioRow`'s `empty`), so an empty
+  // master lane under it was a second "Audio" row with the same box, one that
+  // drops into the bed instead of the shot. The Project keeps the master lane
+  // always: there it is the only way into the bed. Nothing sums this lane's
+  // height, so dropping it moves no spacer.
+  if (shotWindow !== undefined && clips.length === 0 && !importing) return null;
 
   /**
    * NEW CLIPS LAND AT THE PLAYHEAD, dropped ones included.
@@ -60,22 +175,16 @@ export function AudioLane(props: { ppf: number; labelWidth: number; beginSnap?:
    * one would make "where does the thing I make appear" a question with two
    * answers. The clip is draggable the moment it exists.
    */
-  const importFiles = (files: FileList | null): void => {
-    const file = files?.[0];
-    if (file === undefined) return;
-    setError(null);
-    setImporting(true);
-    void store
-      .importAudio(file)
-      .catch((e: unknown) => setError(e instanceof Error ? e.message : String(e)))
-      .finally(() => setImporting(false));
-  };
+  const importFiles = (files: FileList | null): void =>
+    importEach(store, files, undefined, setImporting, setError);
 
   return (
     <div
       className={`audio-lane${over ? " is-over" : ""}`}
       data-testid="audio-lane"
       onDragOver={(e) => {
+        // Files only: a shot reorder or an asset drag is not an import.
+        if (!e.dataTransfer.types.includes("Files")) return;
         e.preventDefault();
         setOver(true);
       }}
@@ -87,34 +196,13 @@ export function AudioLane(props: { ppf: number; labelWidth: number; beginSnap?:
       }}
     >
       <div className="audio-label-cell" style={{ width: labelWidth }}>
-        <span className="audio-lane-name">Audio</span>
-        <button
-          type="button"
-          className="audio-add"
-          title="Import audio at the playhead"
-          disabled={importing}
-          onClick={() => fileRef.current?.click()}
-        >
-          {importing ? "…" : "+"}
-        </button>
-        <input
-          ref={fileRef}
-          className="audio-file-input"
-          type="file"
-          accept="audio/*"
-          hidden
-          data-testid="audio-file-input"
-          onChange={(e) => {
-            importFiles(e.currentTarget.files);
-            // Cleared so re-picking the SAME file fires change again.
-            e.currentTarget.value = "";
-          }}
-        />
+        {/* Sound's teal square, the swatch every track row leads with. */}
+        <span className="audio-swatch" aria-hidden="true" />
+        <span className="audio-lane-name">Sound</span>
+        <AddSoundButton importing={importing} />
       </div>
       <div className="audio-track">
-        {clips.length === 0 && !importing ? (
-          <span className="audio-empty">Drop an audio file here, or press +</span>
-        ) : null}
+        {clips.length === 0 && !importing ? <AudioDropBox /> : null}
         {clips.map((clip) => (
           <AudioClipBar
             key={clip.id}
@@ -122,7 +210,10 @@ export function AudioLane(props: { ppf: number; labelWidth: number; beginSnap?:
             asset={doc.assets[clip.asset]}
             fps={doc.fps}
             ppf={ppf}
+            offsetFrames={0}
+            originFrames={origin}
             beginSnap={beginSnap}
+            waveH={MASTER_WAVE_H}
           />
         ))}
       </div>
@@ -135,17 +226,340 @@ export function AudioLane(props: { ppf: number; labelWidth: number; beginSnap?:
   );
 }
 
-function AudioClipBar(props: {
+/**
+ * A Sound row's "+": the Sound tab, where adding is Import, Library and
+ * Generate on one row per track. These rows keep the drop (a file dragged onto
+ * the lane still lands at the playhead), not a second picker.
+ */
+function AddSoundButton({ importing }: { importing: boolean }) {
+  const store = useStore();
+  return (
+    <button
+      type="button"
+      className="audio-add"
+      data-testid="audio-add"
+      aria-label="Add sound"
+      title="Add sound: opens the Sound tab"
+      disabled={importing}
+      onClick={() => store.setDockMode("sound")}
+    >
+      {importing ? "…" : "+"}
+    </button>
+  );
+}
+
+/**
+ * Import every file, one after another, so a multi-file drop loses nothing.
+ * Each store error already names its file, so the failures are shown together.
+ */
+export function importEach(
+  store: ReturnType<typeof useStore>,
+  files: FileList | null,
+  sceneId: string | undefined,
+  setImporting: (busy: boolean) => void,
+  setError: (message: string | null) => void,
+  trackId?: string,
+): void {
+  // Copied now: the picker clears its input right after this returns.
+  const list = Array.from(files ?? []);
+  if (list.length === 0) return;
+  setError(null);
+  setImporting(true);
+  void (async () => {
+    const failed: string[] = [];
+    for (const file of list) {
+      try {
+        await store.importAudio(file, undefined, sceneId, trackId);
+      } catch (e) {
+        failed.push(e instanceof Error ? e.message : String(e));
+      }
+    }
+    setError(failed.length === 0 ? null : failed.join(" "));
+    setImporting(false);
+  })();
+}
+
+/** A clip's name: its file name without the store's hash prefix. */
+export function clipLabel(clip: AudioClipRef, asset: ShotAsset | undefined): string {
+  return asset?.path.replace(/^[0-9a-f]{8}-/, "") ?? clip.asset;
+}
+
+/** The duck popover's rows. Two clips cut from one file share a name, so a
+ *  repeated name gets a count ("voiceover.wav · 2") to keep the rows apart. */
+function duckRows(
+  clips: readonly AudioClipRef[],
+  assets: Readonly<Record<string, ShotAsset>>,
+): { id: string; label: string }[] {
+  const labels = clips.map((c) => clipLabel(c, assets[c.asset]));
+  const seen = new Map<string, number>();
+  return clips.map((c, i) => {
+    const label = labels[i]!;
+    const n = (seen.get(label) ?? 0) + 1;
+    seen.set(label, n);
+    return { id: c.id, label: labels.indexOf(label) === labels.lastIndexOf(label) ? label : `${label} · ${n}` };
+  });
+}
+
+/**
+ * DUCKING, from the bar.
+ *
+ * The control is a popover rather than a drag, because a duck is a
+ * RELATIONSHIP: it names other clips, and there is no gesture on one bar that
+ * expresses "under these". The button stays visible at rest whether or not the
+ * clip ducks, which is the design system's rule about a capability's only
+ * affordance; what changes is whether it reads as armed.
+ */
+function DuckButton({
+  clip,
+  candidates,
+  store,
+}: {
+  clip: AudioClipRef;
+  /** Every OTHER clip in the document, named. A duck may name a clip in either
+   *  home, which is why this is the flatten and not the lane. */
+  candidates: readonly { id: string; label: string }[];
+  store: ReturnType<typeof useStore>;
+}) {
+  const [open, setOpen] = useState(false);
+  const duck = clip.duck;
+  const sources = duck?.sources ?? [];
+  const strength = duck?.strength ?? DUCK_DEFAULT_STRENGTH;
+
+  const toggle = (id: string): void => {
+    const next = sources.includes(id) ? sources.filter((s) => s !== id) : [...sources, id];
+    store.setAudioDuck(clip.id, next, duck?.strength);
+  };
+
+  return (
+    <span className="audio-duck">
+      <button
+        type="button"
+        className="audio-clip-btn"
+        aria-label={duck === undefined ? "Duck under a voice" : "Ducking"}
+        aria-pressed={duck !== undefined}
+        aria-expanded={open}
+        data-testid={`audio-duck-${clip.id}`}
+        title={
+          duck === undefined
+            ? "Duck under a voice: hold this clip down while another one speaks"
+            : `Ducking under ${sources.length} clip(s) at ${Math.round(strength * 100)}%`
+        }
+        onPointerDown={(e) => e.stopPropagation()}
+        onClick={() => setOpen((v) => !v)}
+      >
+        ⌄
+      </button>
+      {open && (
+        <div className="audio-duck-pop" onPointerDown={(e) => e.stopPropagation()}>
+          {candidates.length === 0 ? (
+            <p className="audio-duck-empty">
+              Nothing to duck under yet. Add the narration, then come back.
+            </p>
+          ) : (
+            <>
+              <p className="audio-duck-title">Hold this down while these speak</p>
+              {candidates.map((other) => (
+                <label key={other.id} className="audio-duck-row">
+                  <input
+                    type="checkbox"
+                    checked={sources.includes(other.id)}
+                    onChange={() => toggle(other.id)}
+                  />
+                  <span>{other.label}</span>
+                </label>
+              ))}
+              <label className="audio-duck-row audio-duck-strength">
+                <span>Depth</span>
+                <input
+                  type="range"
+                  min={0.05}
+                  max={1}
+                  step={0.05}
+                  value={strength}
+                  disabled={sources.length === 0}
+                  aria-label="Duck depth"
+                  onChange={(e) => store.setAudioDuck(clip.id, sources, Number(e.currentTarget.value))}
+                />
+                {/* The dB, because that is the unit the decision is made in.
+                    0.25 is 6 dB, which is the default for a reason. */}
+                <span className="audio-duck-db">{Math.round(strength * DUCK_MAX_DEPTH_DB)} dB</span>
+              </label>
+            </>
+          )}
+        </div>
+      )}
+    </span>
+  );
+}
+
+/**
+ * A SHOT'S OWN AUDIO, drawn inside that shot's group.
+ *
+ * Last in the group on purpose: video above, audio below, the way the master
+ * bed sits under every scene group in the dock. The clips are scene-local and
+ * `offsetFrames` puts them back on the ruler's master base.
+ *
+ * DRAWN ONLY WHEN THE SHOT HAS SOME, unless the caller asks for the empty
+ * row (`empty`). Over the Project the master lane is always present because it
+ * teaches the import (see `TimelineDock`'s `laneShown`). The boards also draw a drop box in
+ * a shot's own audio row, and `empty` is that row: the same box as the master
+ * lane's, dropping into this shot. The dock passes it inside an entered shot,
+ * where it is the one audio row on screen. It is opt-in because the dock's
+ * group height sum (`groupHeights`) adds `SHOT_AUDIO_ROW_H` only when the shot
+ * has audio OR is the entered shot, the same predicate the dock passes `empty`
+ * on, and a row drawn without that count would push every group under it off
+ * its spacer. Over the Project, the way in is a drop on this row once a clip is
+ * here, or the clip's own ⇥ button, which is the shortest path from "I
+ * imported some music" to "this whoosh belongs to that cut". The `+` opens the
+ * Sound tab, the one place sound is added from a picker.
+ */
+export function SceneAudioRow(props: {
+  sceneId: string;
+  ppf: number;
+  labelWidth: number;
+  /** The shot's start on the master timeline. */
+  offsetFrames: number;
+  /** The shot context's re-zero, 0 in the scene context. */
+  originFrames: number;
+  beginSnap?: SnapPress;
+  /** Draw the row and its drop box even with no clips. The caller must count
+   *  the row's height whenever it passes this (see above). */
+  empty?: boolean;
+}) {
+  const { sceneId, ppf, labelWidth, offsetFrames, originFrames, beginSnap, empty = false } = props;
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const [over, setOver] = useState(false);
+  const [importing, setImporting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const scene = doc?.scenesById[sceneId];
+  const clips = Object.values(scene?.audio ?? {});
+  if (doc === null || scene === undefined || (clips.length === 0 && !importing && !empty)) return null;
+
+  // The SHOT is the home, and the playhead is converted into its base by the
+  // store — this row never does frame arithmetic of its own.
+  const importFiles = (files: FileList | null): void =>
+    importEach(store, files, sceneId, setImporting, setError);
+
+  return (
+    <div
+      className={`scene-audio-row${over ? " is-over" : ""}`}
+      data-testid={`scene-audio-${sceneId}`}
+      data-scene-audio={sceneId}
+      onDragOver={(e) => {
+        if (!e.dataTransfer.types.includes("Files")) return;
+        e.preventDefault();
+        setOver(true);
+      }}
+      onDragLeave={() => setOver(false)}
+      onDrop={(e) => {
+        e.preventDefault();
+        // STOPPED, so the master lane's own drop handler does not also fire and
+        // make a second clip in the other home from one file.
+        e.stopPropagation();
+        setOver(false);
+        importFiles(e.dataTransfer?.files ?? null);
+      }}
+    >
+      <div className="scene-audio-label" style={{ width: labelWidth }}>
+        <span className="audio-swatch" aria-hidden="true" />
+        <span className="scene-audio-name">Sound</span>
+        <AddSoundButton importing={importing} />
+      </div>
+      <div className="audio-track">
+        {clips.length === 0 && !importing ? <AudioDropBox /> : null}
+        {clips.map((clip) => (
+          <AudioClipBar
+            key={clip.id}
+            clip={clip}
+            asset={doc.assets[clip.asset]}
+            fps={doc.fps}
+            ppf={ppf}
+            offsetFrames={offsetFrames}
+            originFrames={originFrames}
+            beginSnap={beginSnap}
+            ownedBy={sceneId}
+            limitFrames={Math.max(0, Math.trunc(scene.durationFrames))}
+            waveH={SHOT_WAVE_H}
+          />
+        ))}
+      </div>
+      {error === null ? null : (
+        <p className="audio-error" role="status">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
+export function AudioClipBar(props: {
   clip: AudioClipRef;
   asset: ShotAsset | undefined;
   fps: Rational;
   ppf: number;
+  /** Where this clip's frame base starts on the MASTER timeline: 0 for a bed,
+   *  the shot's start for a clip its shot owns. `BlockRow`'s prop, for the same
+   *  reason and with the same meaning. */
+  offsetFrames: number;
+  /** The shot context's re-zero. DRAWING ONLY: every gesture below is a signed
+   *  delta, which means the same thing in either base. */
+  originFrames: number;
   beginSnap: SnapPress | undefined;
+  /** Absent in the master lane. Present for a clip a shot owns, so the home
+   *  button can say which way it would move. */
+  ownedBy?: string;
+  /**
+   * The owning shot's length, so the bar can mark what will NOT be heard.
+   *
+   * `masterAudioClips` cuts an owned clip at its shot's end, and the document
+   * keeps the authored length so growing the shot brings the tail back. That
+   * means the bar and the mixer legitimately disagree, and a bar that drew the
+   * authored 60 frames with nothing to say about the last 10 would be the exact
+   * silent divergence this lane exists to prevent — you would see audio, hear
+   * none, and have nothing to look at.
+   */
+  limitFrames?: number;
+  /** The bar's inner height in this row (`MASTER_WAVE_H` or `SHOT_WAVE_H`):
+   *  the waveform, the fade ramp and the envelope all draw into it. */
+  waveH: number;
+  /**
+   * Sound mode's rows: which track row is under this screen y, or undefined
+   * off every row. Present only there. A body drag then carries the clip
+   * across rows in the SAME scrub as its time move, so one undo puts both back.
+   */
+  rowAt?: (clientY: number) => string | undefined;
+  onContextMenu?: (e: ReactMouseEvent<HTMLElement>) => void;
+  /** A short tag drawn after the name (Sound mode's "Shot 02"). */
+  badge?: string;
+  /**
+   * Sound mode's bar: the mixing controls too (the gain band and its keys, the
+   * duck, the gain key, the clip mute). Absent in Rows mode, where the bar
+   * moves, trims, fades and changes home, and draws the envelope it plays
+   * without editing it.
+   */
+  mix?: boolean;
 }) {
-  const { clip, asset, fps, ppf, beginSnap } = props;
+  const { clip, asset, fps, ppf, offsetFrames, originFrames, beginSnap, ownedBy, limitFrames, waveH, rowAt } = props;
+  const mix = props.mix === true;
   const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const selected = useShotEditor((s) => s.selectedAudio.includes(clip.id));
   const c = audioClipView(clip);
-  const left = frameToPx(c.frame, ppf);
+  // THE FLATTEN, so a bed can duck under narration a SHOT owns. Reading the
+  // lane instead would offer only the clips drawn beside this one, which is
+  // the commonest case and not the only one.
+  const duckCandidates =
+    doc === null || !mix
+      ? []
+      : duckRows(
+          masterAudioClips(doc)
+            .map((m) => m.clip)
+            .filter((other) => other.id !== clip.id),
+          doc.assets,
+        );
+  const left = frameToPx(offsetFrames + c.frame - originFrames, ppf);
   const width = Math.max(8, frameToPx(c.durationFrames, ppf));
 
   /**
@@ -161,25 +575,44 @@ function AudioClipBar(props: {
     (e: ReactPointerEvent<HTMLElement>): void => {
       e.preventDefault();
       e.stopPropagation();
+      if (e.button !== 0) return;
+      // THE PICK. A press on a clip already in a multi-pick keeps the pick, so
+      // the ⌥ stagger below has every clip to rank; ⇧ toggles.
+      const state = store.getState();
+      if (e.shiftKey) store.selectAudio([clip.id], "toggle");
+      else if (!state.selectedAudio.includes(clip.id)) store.selectAudio([clip.id]);
+      const picked = store.getState().selectedAudio;
+      // ⌥ on a multi-pick in Sound mode STAGGERS the pick by rank; on one clip
+      // it slips the source, as it always has.
+      const stagger = mode === "body" && e.altKey && rowAt !== undefined && picked.length > 1;
       // Read AT THE PRESS: a gesture whose meaning changed under a key held
       // mid-drag would slip a clip the author was only moving.
       const effective: AudioDrag = mode === "body" && e.altKey ? "slip" : mode;
       const startX = e.clientX;
       const snap = beginSnap?.({ audioClipId: clip.id }, isSnapSuppressed(e));
+      // MASTER frames, because every target on the snapper's list is: a clip a
+      // shot owns is numbered from that shot, so its own base has to be added
+      // in or the whole gesture snaps to the wrong side of the video.
       const anchor =
-        effective === "out"
+        offsetFrames +
+        (effective === "out"
           ? c.frame + c.durationFrames
           : effective === "fade-in"
             ? c.frame + c.fadeInFrames
             : effective === "fade-out"
               ? c.frame + c.durationFrames - c.fadeOutFrames
-              : c.frame;
+              : c.frame);
       store.beginBlockDrag();
       startDrag(e, {
         onMove(ev) {
           const raw = frameDelta(ev.clientX - startX, ppf);
+          if (stagger) {
+            store.dragAudioStagger(picked, raw);
+            return;
+          }
           const delta = snap === undefined ? raw : snap(anchor + raw) - anchor;
-          store.dragAudio(clip.id, effective, delta);
+          const row = effective === "body" ? rowAt?.(ev.clientY) : undefined;
+          store.dragAudio(clip.id, effective, delta, row);
         },
         onEnd: (commit) => store.endBlockDrag(commit),
       });
@@ -192,7 +625,7 @@ function AudioClipBar(props: {
     e.stopPropagation();
     const startY = e.clientY;
     const from = c.gain;
-    const height = e.currentTarget.parentElement?.clientHeight ?? WAVE_H;
+    const height = e.currentTarget.parentElement?.clientHeight ?? waveH;
     store.beginBlockDrag();
     startDrag(e, {
       onMove(ev) {
@@ -205,38 +638,103 @@ function AudioClipBar(props: {
 
   const fadeInPx = frameToPx(c.fadeInFrames, ppf);
   const fadeOutPx = frameToPx(c.fadeOutFrames, ppf);
+  const track = clip.gainTrack;
+  /** Frames past the shot's end — audible in the document, silent in the mix. */
+  const overrun = limitFrames === undefined ? 0 : Math.max(0, c.frame + c.durationFrames - limitFrames);
 
   return (
     <div
-      className={`audio-clip${c.muted ? " is-muted" : ""}`}
+      className={`audio-clip${c.muted ? " is-muted" : ""}${selected ? " is-selected" : ""}`}
       data-audio-clip={clip.id}
       style={{ left, width }}
       onPointerDown={drag("body")}
-      title={`${asset?.path ?? clip.asset} · drag to move it and its markers, ⌥drag to slip the source, ⌘drag to ignore snapping`}
+      onContextMenu={props.onContextMenu}
+      title={formatCombo(`${asset?.path ?? clip.asset} · drag to move it and its markers, ⌥drag to slip the source, ⌘drag to ignore snapping`)}
     >
-      <AudioWaveform clip={c} asset={asset} fps={fps} widthPx={width} />
+      <AudioWaveform clip={c} asset={asset} fps={fps} widthPx={width} heightPx={waveH} />
 
       {/* The fade ramps, drawn as ONE polyline over the whole bar so the two
           fades and the flat middle cannot disagree about the level between
           them. Inert: the corner handles below take the pointer. */}
       {c.fadeInFrames > 0 || c.fadeOutFrames > 0 ? (
-        <svg className="audio-fade-curve" viewBox={`0 0 ${width} ${WAVE_H}`} preserveAspectRatio="none" aria-hidden="true">
+        <svg className="audio-fade-curve" viewBox={`0 0 ${width} ${waveH}`} preserveAspectRatio="none" aria-hidden="true">
           <polyline
-            points={`0,${WAVE_H} ${fadeInPx},0 ${Math.max(fadeInPx, width - fadeOutPx)},0 ${width},${WAVE_H}`}
+            points={`0,${waveH} ${fadeInPx},0 ${Math.max(fadeInPx, width - fadeOutPx)},0 ${width},${waveH}`}
             fill="none"
           />
         </svg>
       ) : null}
 
-      <span
-        className="audio-gain-band"
-        data-handle="audio-gain"
-        style={{ bottom: `${(c.gain / MAX_AUDIO_GAIN) * 100}%` }}
-        onPointerDown={dragGain}
-        title={`Gain ${c.gain.toFixed(2)} — drag up or down`}
-      />
+      {/* THE GAIN, one control in two shapes. A clip with no automation gets
+          the flat rubber band it always had. One with a `gainTrack` gets the
+          ENVELOPE the mixer will actually apply, sampled through the engine so
+          the line on screen and the samples in the file are the same function —
+          and the band then edits the key under the playhead rather than a
+          static number the engine would ignore. */}
+      {!mix ? (
+        track === undefined ? null : (
+          <svg
+            className="audio-gain-curve"
+            data-testid={`audio-envelope-${clip.id}`}
+            viewBox={`0 0 ${width} ${waveH}`}
+            preserveAspectRatio="none"
+            aria-hidden="true"
+          >
+            <polyline points={envelopePoints(track, c, fps, width, ppf, waveH)} fill="none" />
+          </svg>
+        )
+      ) : track === undefined ? (
+        <span
+          className="audio-gain-band"
+          data-handle="audio-gain"
+          style={{ bottom: `${(c.gain / MAX_AUDIO_GAIN) * 100}%` }}
+          onPointerDown={dragGain}
+          title={`Gain ${c.gain.toFixed(2)}: drag up or down`}
+        />
+      ) : (
+        <>
+          <svg
+            className="audio-gain-curve"
+            data-testid={`audio-envelope-${clip.id}`}
+            viewBox={`0 0 ${width} ${waveH}`}
+            preserveAspectRatio="none"
+            aria-hidden="true"
+          >
+            <polyline points={envelopePoints(track, c, fps, width, ppf, waveH)} fill="none" />
+          </svg>
+          <span className="audio-gain-band is-automated" data-handle="audio-gain" onPointerDown={dragGain} />
+          {track.keyframes.map((k) => (
+            <span
+              key={k.id}
+              className="audio-gain-key"
+              data-audio-gain-key={k.id}
+              style={{
+                left: frameToPx(k.frame, ppf),
+                bottom: `${(gainOf(k.value) / MAX_AUDIO_GAIN) * 100}%`,
+              }}
+              title={`Gain ${gainOf(k.value).toFixed(2)} at +${k.frame}f`}
+            />
+          ))}
+        </>
+      )}
 
-      <span className="audio-clip-name">{asset?.path.replace(/^[0-9a-f]{8}-/, "") ?? clip.asset}</span>
+      {/* WHAT WILL NOT BE HEARD. Hatched rather than cut off, because the
+          document still holds these frames: lengthening the shot brings them
+          back, and a bar that simply ended at the boundary would give the
+          author nothing to drag. */}
+      {overrun > 0 ? (
+        <span
+          className="audio-overrun"
+          data-testid={`audio-overrun-${clip.id}`}
+          style={{ left: frameToPx(c.durationFrames - overrun, ppf) }}
+          title={`${overrun}f past the end of this shot: kept, but not heard. Lengthen the shot or trim the clip.`}
+        />
+      ) : null}
+
+      <span className="audio-clip-name">
+        {clipLabel(clip, asset)}
+        {props.badge === undefined ? null : <span className="audio-clip-badge">{props.badge}</span>}
+      </span>
 
       <span
         className="audio-handle audio-handle-in"
@@ -266,16 +764,53 @@ function AudioClipBar(props: {
       />
 
       <span className="audio-clip-buttons">
+        {mix ? <AudioFxButton clip={clip} asset={asset} store={store} /> : null}
+        {mix ? <DuckButton clip={clip} candidates={duckCandidates} store={store} /> : null}
+        {/* THE HOME SWITCH. One bit, so a target rather than a drop zone: a
+            cross-lane drag would have to hit-test another lane mid-capture to
+            carry the same information. Attaching picks the shot the clip
+            STARTS in, which is the only shot it can be said to belong to. */}
         <button
           type="button"
           className="audio-clip-btn"
-          aria-label={c.muted ? "Unmute clip" : "Mute clip"}
-          aria-pressed={c.muted}
+          aria-label={ownedBy === undefined ? "Attach to the shot under it" : "Move to the master bed"}
+          title={
+            ownedBy === undefined
+              ? "Attach to the shot it starts in: it will move, duplicate and end with that shot"
+              : "Move to the master bed: it will span the cuts and stop following this shot"
+          }
           onPointerDown={(e) => e.stopPropagation()}
-          onClick={() => store.toggleAudioMute(clip.id)}
+          onClick={() => store.moveAudioHome(clip.id)}
         >
-          {c.muted ? "🔇" : "🔊"}
+          {ownedBy === undefined ? "⇥" : "⇤"}
         </button>
+        {/* THE AUTOMATION KEY, at the playhead. A toggle, because the same
+            button is both states and a second control for "remove" would be a
+            control that is disabled almost always. */}
+        {mix ? (
+          <button
+            type="button"
+            className="audio-clip-btn"
+            aria-label="Keyframe the gain at the playhead"
+            title="Keyframe the gain at the playhead: the first key changes nothing, it just makes the level automatable"
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={() => store.toggleAudioGainKey(clip.id)}
+          >
+            ◆
+          </button>
+        ) : null}
+        {mix ? (
+          <button
+            type="button"
+            className="audio-clip-btn"
+            aria-label={c.muted ? "Unmute clip" : "Mute clip"}
+            aria-pressed={c.muted}
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={() => store.toggleAudioMute(clip.id)}
+          >
+            {c.muted ? <IconVolumeOff /> : <IconVolume />}
+          </button>
+        ) : null}
         <button
           type="button"
           className="audio-clip-btn"
@@ -298,13 +833,23 @@ function AudioClipBar(props: {
  * decimation out of it — nothing here refetches. (Not the asset id: that is a
  * filename slug this lane mints per document, so it repeats across shots.)
  */
-function AudioWaveform(props: {
+export function AudioWaveform(props: {
   clip: { offsetFrames: number; durationFrames: number };
-  asset: ShotAsset | undefined;
+  /**
+   * The asset, by IDENTITY. The fetch below keys its effect on this prop, so a
+   * caller must hand it the same object across renders — `{ path }` built in
+   * the render would refetch and re-`setData` forever. The row models carry the
+   * resolved `ShotAsset` for exactly that reason.
+   */
+  asset: { path: string } | undefined;
   fps: Rational;
   widthPx: number;
+  /** Canvas px: the inner height of the box it is drawn into, which differs
+   *  per row (the master lane, a shot's audio row, a video row's sound strip). */
+  heightPx: number;
 }) {
-  const { clip, asset, fps, widthPx } = props;
+  const { clip, asset, fps, widthPx, heightPx } = props;
+  const { resolved: resolvedTheme } = useStudioTheme();
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const [data, setData] = useState<PeakData | null>(null);
 
@@ -326,15 +871,59 @@ function AudioWaveform(props: {
   useEffect(() => {
     const canvas = canvasRef.current;
     if (canvas === null || data === null || data.peaks.length === 0) return;
+    const waveColor = getComputedStyle(canvas).getPropertyValue("--audio-waveform").trim();
     drawClipWaveform(canvas, {
       data,
       fromSeconds: framesToSeconds(clip.offsetFrames, fps),
       toSeconds: framesToSeconds(clip.offsetFrames + clip.durationFrames, fps),
       widthPx,
-      heightPx: WAVE_H,
-      color: WAVE_COLOR,
+      heightPx,
+      color: waveColor || WAVE_COLOR_FALLBACK,
     });
-  }, [data, widthPx, fps, clip.offsetFrames, clip.durationFrames]);
+  }, [data, widthPx, heightPx, fps, clip.offsetFrames, clip.durationFrames, resolvedTheme]);
 
   return <canvas className="audio-wave" ref={canvasRef} aria-hidden="true" />;
 }
+
+/** A track value as a gain. Guarded rather than cast: the track shape allows a
+ *  vector, and a validator problem must not become a NaN in a `points` list
+ *  that then removes the whole polyline. */
+function gainOf(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 1;
+}
+
+/**
+ * The envelope polyline, in the bar's own pixel space.
+ *
+ * SAMPLED THROUGH THE ENGINE, one point per drawn pixel rather than one per
+ * keyframe, because the segments between keys are eased (and may be springs)
+ * and a straight line between two keys would draw a curve the mixer is not
+ * going to apply. `audioGainSampler` is the same function the preview and both
+ * export mixes take their values from, so the line and the samples cannot
+ * disagree — which is the whole reason this is not a local lerp.
+ *
+ * The FADES are deliberately not folded in. They already have their own
+ * polyline over the bar, and multiplying the two would draw one line the author
+ * could not take either control back off.
+ */
+function envelopePoints(
+  track: ShotTrack,
+  clip: { durationFrames: number },
+  fps: Rational,
+  widthPx: number,
+  ppf: number,
+  heightPx: number,
+): string {
+  const sample = audioGainSampler(track, 0, fps);
+  if (sample === undefined) return "";
+  // One sample per pixel, capped: a bar zoomed to thousands of pixels does not
+  // need thousands of points to read as a curve, and this runs per render.
+  const steps = Math.max(2, Math.min(240, Math.round(widthPx)));
+  const out: string[] = [];
+  for (let i = 0; i <= steps; i++) {
+    const frame = (i / steps) * clip.durationFrames;
+    const y = heightPx * (1 - gainOf(sample(frame) ?? 1) / MAX_AUDIO_GAIN);
+    out.push(`${frameToPx(frame, ppf)},${y}`);
+  }
+  return out.join(" ");
+}