@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/SoundMode.tsx

@@ -0,0 +1,1406 @@
+// SOUND MODE: the dock as a small DAW (gap 8).
+//
+// ── ONE ROW PER TRACK, AND THE TRACK IS THE MIXER ───────────────────────
+//
+// Rows mode draws audio by HOME: the bed at the bottom, a shot's own clips
+// inside its group. Sound mode draws it by TRACK (`doc.audioTracks`, schema
+// v39), one 72px row each, because the question here is "what plays with
+// what", and a track is the answer the mixer gives. Both homes still exist and
+// both draw on their track's row: a shot's clip wears a "Shot 02" badge and is
+// placed from its shot's start, exactly as `SceneAudioRow` places it.
+//
+// A recording's `video.sound` is drawn on its track too, READ-ONLY: its
+// fields live on the layer, and Rows mode's video row is where it is trimmed.
+// It can still change track, because a track is all Sound mode owns.
+//
+// ── WHAT IS SAVED AND WHAT IS NOT ──────────────────────────────────────
+//
+// Name, level, pan and mute are the document's (`AudioTrack3D`), so an export
+// hears them. SOLO is this tab's (`soloTracks`): a listening aid, never a mix
+// decision, and a solo saved by accident would silence a render. The master
+// strip is a meter and nothing else: the document has no master gain, and the
+// preview volume (this tab's, like solo) is the transport's speaker, so the
+// mixer never shows a second level an export ignores.
+//
+// ── ONE HOME FOR EACH CONTROL ──────────────────────────────────────────
+//
+// Level and pan live on the mixer's strips only. The track row's strip keeps
+// the name and M/S, the two things an author reaches for while looking at the
+// waveforms. Two faders for one gain were two places to wonder which one won.
+//
+// ── EVERY STRIP DRAG IS ONE UNDO ───────────────────────────────────────
+//
+// Fader and pan drags go through the dock's one history scrub
+// (`beginBlockDrag` / `dragAudioTrack` / `endBlockDrag`), like a clip drag:
+// one undo entry per gesture, and Escape puts the base back by reference.
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import type {
+  KeyboardEvent as ReactKeyboardEvent,
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
+  ReactNode,
+} from "react";
+import { frameToPx, startDrag } from "@dailies-studio/timeline";
+import { Popover, Toggle, useConfirm } from "@dailies-studio/ui";
+import type { MenuEntry, UseContextMenuResult } from "@dailies-studio/ui";
+import {
+  MAX_AUDIO_GAIN,
+  TEMPO_BPM_MAX,
+  TEMPO_BPM_MIN,
+  addAudioTrack,
+  audioAnalysisFileName,
+  audioTrackOf,
+  audioTracksOf,
+  authoredAudioClips,
+  sceneWindows,
+  setAudioClipTrack,
+} from "@dailies-studio/shot/doc";
+import type { AudioClipRef, AudioTrack3D, Doc3D, Tempo3D } from "@dailies-studio/shot/doc";
+import { fetchAssetBytes, generationStatus } from "../../api.js";
+import { meterChannelKey, useMeterReading, useMeterTap } from "../../audio/meter.js";
+import { METER_FLOOR_DB } from "../../audio/meterMath.js";
+import { MASTER_METER_KEY, readMonitor, subscribeMonitor } from "../../audio/preview.js";
+import { ADD_ICON, CLOSE_ICON, LIBRARY_ICON, LOCK_ICON, METRONOME_ICON, SPARKLES_ICON } from "../../icons.js";
+import { useShotEditor, useShotEditorHot, useStore } from "../../state/context.js";
+import { gateForViewer } from "../../state/menu.js";
+import { formatCombo, shortcutFor } from "../../state/shortcuts.js";
+import { shotNumberOf } from "../../state/storyboardModel.js";
+import { AUDIO_FILE_ACCEPT, AudioClipBar, AudioWaveform, clipLabel, importEach } from "./AudioLane.js";
+import { voiceDuckState } from "./duckUnderVoice.js";
+import type { BeatTick } from "./beatRuler.js";
+import type { SnapPress } from "./snap.js";
+
+type Store = ReturnType<typeof useStore>;
+type OpenMenu = UseContextMenuResult["open"];
+
+/** Mirrors of timeline-sound.css. */
+export const SOUND_ROW_H = 72;
+export const SOUND_SHOTS_ROW_H = 24;
+/** The clip bar's inner height in a track row: the row less its 1px seam, the
+ *  bar's 8px insets and its 1px border. */
+const SOUND_WAVE_H = SOUND_ROW_H - 1 - 2 * 8 - 2;
+/** A press that travels less than this is a click, not a rubber band. */
+const MARQUEE_MIN_PX = 3;
+
+const MINUS = "−";
+
+// ── THE FADER LAW ────────────────────────────────────────────────────────
+//
+// Unity sits at three quarters of the travel, as on a console, so the useful
+// range (cuts of a few dB) gets most of the throw and +6 dB gets the last
+// quarter. `pos = (gain / 2) ^ log2(4/3)` puts gain 1 at exactly 0.75.
+const FADER_EXP = Math.log2(4 / 3);
+/** Within this much travel of unity, a drag lands ON unity. */
+const UNITY_DETENT = 0.012;
+
+/** A track gain (0..2) as fader travel (0..1). */
+export function faderPos(gain: number): number {
+  if (!(gain > 0)) return 0;
+  return Math.min(1, (gain / MAX_AUDIO_GAIN) ** FADER_EXP);
+}
+
+/** Fader travel (0..1) as a gain (0..2), with the unity detent. Rounded to
+ *  three places so a drag writes numbers a person could have typed. */
+export function faderGain(pos: number): number {
+  const p = Math.min(1, Math.max(0, pos));
+  if (p <= 0) return 0;
+  if (Math.abs(p - faderPos(1)) < UNITY_DETENT) return 1;
+  return Math.round(MAX_AUDIO_GAIN * p ** (1 / FADER_EXP) * 1000) / 1000;
+}
+
+/** A gain as dB, one decimal: "0.0 dB", "−3.0 dB", "+1.5 dB", "−∞ dB". */
+export function dbLabel(gain: number, unit = true): string {
+  const tail = unit ? " dB" : "";
+  if (!(gain > 0)) return `${MINUS}∞${tail}`;
+  let text = (20 * Math.log10(gain)).toFixed(1);
+  if (text === "-0.0") text = "0.0";
+  if (text.startsWith("-")) text = `${MINUS}${text.slice(1)}`;
+  else if (text !== "0.0") text = `+${text}`;
+  return `${text}${tail}`;
+}
+
+/** The BPM chip's text: "120 BPM · 4/4". */
+export function tempoLabel(tempo: Tempo3D): string {
+  const bpm = Math.round(tempo.bpm * 100) / 100;
+  return `${bpm} BPM · ${Math.max(1, Math.trunc(tempo.beatsPerBar ?? 4))}/4`;
+}
+
+// ── THE ROWS ─────────────────────────────────────────────────────────────
+
+/** One clip on a row, in either home, or a recording's read-only sound. */
+interface RowClip {
+  clip: AudioClipRef;
+  /** Master frame the clip's own frame base starts at. */
+  offsetFrames: number;
+  sceneId: string | null;
+  /** Set for a recording's sound (read-only). */
+  layerId?: string;
+  masterStart: number;
+  masterEnd: number;
+}
+
+/** Every clip by track id, in both homes plus the recordings' sounds. */
+function clipsByTrack(doc: Doc3D): Map<string, RowClip[]> {
+  const out = new Map<string, RowClip[]>();
+  const push = (trackId: string, row: RowClip): void => {
+    const list = out.get(trackId);
+    if (list === undefined) out.set(trackId, [row]);
+    else list.push(row);
+  };
+  const span = (clip: AudioClipRef, offset: number) => {
+    const start = offset + Math.trunc(clip.frame);
+    return { masterStart: start, masterEnd: start + Math.max(1, Math.trunc(clip.durationFrames)) };
+  };
+  for (const clip of Object.values(doc.audio)) {
+    push(audioTrackOf(doc, clip.track).id, { clip, offsetFrames: 0, sceneId: null, ...span(clip, 0) });
+  }
+  for (const w of sceneWindows(doc)) {
+    for (const clip of Object.values(doc.scenesById[w.id]?.audio ?? {})) {
+      push(audioTrackOf(doc, clip.track).id, { clip, offsetFrames: w.start, sceneId: w.id, ...span(clip, w.start) });
+    }
+  }
+  // The recordings' sounds: the flatten is the one reader of `video.sound`,
+  // already on master frames and cut to the shot.
+  for (const m of authoredAudioClips(doc)) {
+    if (m.layerId === undefined) continue;
+    push(m.trackId, {
+      clip: m.clip,
+      offsetFrames: 0,
+      sceneId: m.sceneId,
+      layerId: m.layerId,
+      ...span(m.clip, 0),
+    });
+  }
+  return out;
+}
+
+export function SoundLanes(props: {
+  ppf: number;
+  labelWidth: number;
+  timeW: number;
+  /** The shot context's re-zero, 0 over the Project. */
+  origin: number;
+  /** The shot context's window, absent over the Project. */
+  window?: { origin: number; len: number } | undefined;
+  beginSnap: SnapPress;
+  /** The beat grid (`beatRulerTicks`), or empty with no tempo. */
+  grid: readonly BeatTick[];
+  /** The snap guide and the playhead, drawn through every row. */
+  overlay: ReactNode;
+  openMenu: OpenMenu;
+  onGenerate: () => void;
+}) {
+  const { ppf, labelWidth, timeW, origin, window: shotWindow, beginSnap, grid, overlay, openMenu, onGenerate } = props;
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const editingDef = useShotEditor((s) => s.editingDef);
+  const solo = useShotEditor((s) => s.soloTracks);
+  const notice = useShotEditor((s) => s.dockNotice);
+  const reveal = useShotEditor((s) => s.dockReveal);
+  // Hot: the cold lane sleeps through a cut the transport plays (store
+  // `set`), and the Shot pills mark what is playing. A string, so this
+  // renders at a cut and not per frame.
+  const currentShot = useShotEditorHot((s) => s.sceneId);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const [marquee, setMarquee] = useState<{ left: number; top: number; right: number; bottom: number } | null>(null);
+  const [flashed, setFlashed] = useState<string | null>(null);
+  const { confirm, dialog } = useConfirm();
+
+  const byTrack = useMemo(() => (doc === null ? new Map<string, RowClip[]>() : clipsByTrack(doc)), [doc]);
+
+  // THE REVEAL, for the clips an agent or the library just placed. The dock's
+  // own reveal effect consumes the request after this one runs (a child's
+  // effects run first), and only scrolls layer rows.
+  useEffect(() => {
+    const ids = reveal?.audioIds;
+    if (ids === undefined || ids.length === 0) return;
+    const root = rootRef.current;
+    const el = root?.querySelector<HTMLElement>(`[data-audio-clip="${CSS.escape(ids[0]!)}"]`);
+    if (el === null || el === undefined) return;
+    el.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+    if (reveal?.flash) setFlashed(el.closest<HTMLElement>("[data-sound-row]")?.dataset["soundRow"] ?? null);
+  }, [reveal]);
+
+  if (doc === null) return null;
+  if (editingDef !== null) {
+    return (
+      <div className="sound-lanes" style={{ minWidth: labelWidth + timeW }}>
+        <p className="sound-note">A component has no master time, so it has no sound. Leave it to mix the film.</p>
+      </div>
+    );
+  }
+
+  const tracks = audioTracksOf(doc);
+  const inWindow = (r: RowClip): boolean =>
+    shotWindow === undefined ||
+    (r.masterEnd > shotWindow.origin && r.masterStart < shotWindow.origin + shotWindow.len);
+  const total = [...byTrack.values()].reduce((n, list) => n + list.length, 0);
+  const windows = sceneWindows(doc).filter(
+    (w) => shotWindow === undefined || (w.end > shotWindow.origin && w.start < shotWindow.origin + shotWindow.len),
+  );
+
+  /** The track row under a screen y, read live: rows can scroll mid-drag. */
+  const rowAt = (clientY: number): string | undefined => {
+    for (const row of rootRef.current?.querySelectorAll<HTMLElement>("[data-sound-row]") ?? []) {
+      const r = row.getBoundingClientRect();
+      if (clientY >= r.top && clientY < r.bottom) return row.dataset["soundRow"];
+    }
+    return undefined;
+  };
+
+  const clipMenu = (row: RowClip) => (e: ReactMouseEvent<HTMLElement>): void => {
+    e.preventDefault();
+    e.stopPropagation();
+    const s = store.getState();
+    if (!s.selectedAudio.includes(row.clip.id)) store.selectAudio([row.clip.id]);
+    openMenu({ x: e.clientX, y: e.clientY }, gateForViewer(store.getState(), clipMenuEntries(store, doc, row)));
+  };
+
+  const trackMenu = (track: AudioTrack3D, index: number, onRename: () => void) =>
+    (e: ReactMouseEvent<HTMLElement>): void => {
+      e.preventDefault();
+      e.stopPropagation();
+      const count = byTrack.get(track.id)?.filter((r) => r.layerId === undefined).length ?? 0;
+      const entries: MenuEntry[] = [
+        { kind: "action", id: "track-add-above", label: "Add track above", onSelect: () => store.addAudioTrackAt(index) },
+        { kind: "action", id: "track-add-below", label: "Add track below", onSelect: () => store.addAudioTrackAt(index + 1) },
+        { kind: "action", id: "track-rename", label: "Rename", onSelect: onRename },
+        {
+          kind: "action",
+          id: "track-up",
+          label: "Move up",
+          disabled: index === 0,
+          onSelect: () => store.reorderAudioTrack(track.id, index - 1),
+        },
+        {
+          kind: "action",
+          id: "track-down",
+          label: "Move down",
+          disabled: index === tracks.length - 1,
+          onSelect: () => store.reorderAudioTrack(track.id, index + 1),
+        },
+        { kind: "separator" },
+        {
+          kind: "action",
+          id: "track-delete",
+          label: "Delete track",
+          danger: true,
+          disabled: tracks.length <= 1,
+          title: tracks.length <= 1 ? "A film keeps at least one track." : undefined,
+          onSelect: () => {
+            if (count === 0) {
+              store.removeAudioTrack(track.id);
+              return;
+            }
+            void confirm({
+              title: `Delete ${track.name}?`,
+              message: `Its ${count} clip${count === 1 ? "" : "s"} go with it. Undo brings them back.`,
+              confirmLabel: "Delete track",
+              danger: true,
+            }).then((ok) => {
+              if (ok) store.removeAudioTrack(track.id);
+            });
+          },
+        },
+      ];
+      openMenu({ x: e.clientX, y: e.clientY }, gateForViewer(store.getState(), entries));
+    };
+
+  /**
+   * THE RUBBER BAND over clip bars. Membership is decided per move from rects
+   * frozen at the press; shift adds to the pick as it stood; Escape puts that
+   * pick back.
+   */
+  const beginMarquee = (e: ReactPointerEvent<HTMLDivElement>): void => {
+    if (e.button !== 0) return;
+    const target = e.target as HTMLElement;
+    if (!target.classList.contains("sound-lane")) return;
+    e.preventDefault();
+    const root = e.currentTarget;
+    const at = root.getBoundingClientRect();
+    const from = { x: e.clientX - at.left, y: e.clientY - at.top };
+    const bars = [...root.querySelectorAll<HTMLElement>("[data-audio-clip]:not([data-readonly])")].map((el) => {
+      const r = el.getBoundingClientRect();
+      return {
+        id: el.dataset["audioClip"]!,
+        left: r.left - at.left,
+        right: r.right - at.left,
+        top: r.top - at.top,
+        bottom: r.bottom - at.top,
+      };
+    });
+    const base = store.getState().selectedAudio;
+    const add = e.shiftKey ? base : [];
+    let painting = false;
+    let written: string | null = null;
+    startDrag(e, {
+      onMove(ev) {
+        const box = root.getBoundingClientRect();
+        const to = { x: ev.clientX - box.left, y: ev.clientY - box.top };
+        if (!painting && Math.abs(to.x - from.x) < MARQUEE_MIN_PX && Math.abs(to.y - from.y) < MARQUEE_MIN_PX) return;
+        painting = true;
+        const rect = {
+          left: Math.min(from.x, to.x),
+          right: Math.max(from.x, to.x),
+          top: Math.min(from.y, to.y),
+          bottom: Math.max(from.y, to.y),
+        };
+        setMarquee(rect);
+        const hits = [...add];
+        for (const b of bars) {
+          if (b.right > rect.left && b.left < rect.right && b.bottom > rect.top && b.top < rect.bottom) {
+            if (!hits.includes(b.id)) hits.push(b.id);
+          }
+        }
+        const key = hits.join("\n");
+        if (key === written) return;
+        written = key;
+        store.selectAudio(hits);
+      },
+      onEnd(commit) {
+        setMarquee(null);
+        if (!painting) {
+          // A plain click on empty lane drops the pick, as it does over rows.
+          if (commit && !e.shiftKey) store.selectAudio([]);
+          return;
+        }
+        if (!commit) store.selectAudio(base);
+      },
+    });
+  };
+
+  const split = shortcutFor("edit.split");
+
+  return (
+    <div
+      ref={rootRef}
+      className="sound-lanes"
+      data-testid="sound-lanes"
+      style={{ minWidth: labelWidth + timeW }}
+      onPointerDown={beginMarquee}
+      onAnimationEnd={(e) => {
+        if (e.animationName === "row-revealed") setFlashed(null);
+      }}
+    >
+      {dialog}
+      <div className="dock-overlay sound-overlay" style={{ left: labelWidth }} aria-hidden="true">
+        {grid.map((t) =>
+          t.tier === 2 ? (
+            <span key={t.frame} className="sound-beat" style={{ left: frameToPx(t.frame, ppf) }} />
+          ) : (
+            <span key={t.frame} className="sound-bar" style={{ left: frameToPx(t.frame, ppf) }} />
+          ),
+        )}
+        {overlay}
+      </div>
+
+      {notice === null ? null : (
+        <div className="sound-notice" role="status" data-testid="sound-notice" style={{ left: labelWidth + 8 }}>
+          {split === undefined ? null : <kbd className="sound-notice-key">{formatCombo(split)}</kbd>}
+          <span>{notice.text}</span>
+          <button
+            type="button"
+            className="btn is-icon is-ghost sound-notice-close"
+            aria-label="Dismiss"
+            onClick={() => store.dismissDockNotice()}
+          >
+            {CLOSE_ICON}
+          </button>
+        </div>
+      )}
+
+      <div className="sound-row sound-shots-row">
+        <div className="sound-strip-cell sound-shots-label" style={{ width: labelWidth }}>
+          Shots
+        </div>
+        <div className="sound-shots">
+          {windows.map((w) => (
+            <button
+              key={w.id}
+              type="button"
+              className={`sound-shot-pill${w.id === currentShot ? " is-current" : ""}`}
+              aria-current={w.id === currentShot ? "true" : undefined}
+              style={{ left: frameToPx(w.start - origin, ppf), width: Math.max(4, frameToPx(w.end - w.start, ppf) - 2) }}
+              title={doc.scenesById[w.id]?.name ?? ""}
+              onPointerDown={(e) => e.stopPropagation()}
+              onClick={() => {
+                store.pauseForScrub();
+                store.seek(w.start);
+              }}
+            >
+              Shot {shotNumberOf(doc, w.id) ?? String(doc.scenes.indexOf(w.id) + 1).padStart(2, "0")}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {tracks.map((track, index) => {
+        const rows = (byTrack.get(track.id) ?? []).filter(inWindow);
+        const dimmed = solo.length > 0 && !solo.includes(track.id);
+        return (
+          <TrackRow
+            key={track.id}
+            track={track}
+            index={index}
+            rows={rows}
+            doc={doc}
+            ppf={ppf}
+            labelWidth={labelWidth}
+            origin={origin}
+            beginSnap={beginSnap}
+            rowAt={rowAt}
+            dimmed={dimmed}
+            soloed={solo.includes(track.id)}
+            flashed={flashed === track.id}
+            empty={index === 0 && total === 0}
+            onClipMenu={clipMenu}
+            onTrackMenu={trackMenu}
+            onGenerate={onGenerate}
+          />
+        );
+      })}
+
+      <div className="sound-row sound-add-row">
+        <div className="sound-strip-cell" style={{ width: labelWidth }}>
+          <button
+            type="button"
+            className="btn is-ghost sound-add-track"
+            data-testid="sound-add-track"
+            onClick={() => store.addAudioTrackAt()}
+          >
+            {ADD_ICON}
+            Add track
+          </button>
+        </div>
+      </div>
+
+      {marquee === null ? null : (
+        <span
+          className="dock-marquee"
+          aria-hidden="true"
+          style={{
+            left: marquee.left,
+            top: marquee.top,
+            width: marquee.right - marquee.left,
+            height: marquee.bottom - marquee.top,
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+/** The right-click menu on a clip bar. A recording's sound offers the track
+ *  move alone: its other fields live on the layer. */
+function clipMenuEntries(store: Store, doc: Doc3D, row: RowClip): MenuEntry[] {
+  const s = store.getState();
+  const picked = s.selectedAudio.includes(row.clip.id) ? s.selectedAudio : [row.clip.id];
+  const current = audioTrackOf(doc, row.clip.track).id;
+  const moveTo = (trackId: string): void => {
+    store.edit((base) => picked.reduce((d, id) => setAudioClipTrack(d, id, trackId), base));
+  };
+  const trackItems: MenuEntry[] = [
+    ...audioTracksOf(doc).map(
+      (t): MenuEntry => ({
+        kind: "action",
+        id: `clip-track-${t.id}`,
+        label: t.name,
+        checked: row.layerId === undefined ? t.id === current : t.id === audioTrackOf(doc, row.clip.track).id,
+        onSelect: () => moveTo(t.id),
+      }),
+    ),
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "clip-track-new",
+      label: "New track",
+      onSelect: () =>
+        store.edit((base) => {
+          const made = addAudioTrack(base, {});
+          return picked.reduce((d, id) => setAudioClipTrack(d, id, made.id), made.doc);
+        }),
+    },
+  ];
+  const move: MenuEntry = { kind: "submenu", label: "Move to track", items: trackItems };
+  if (row.layerId !== undefined) return [move];
+
+  const f = s.frame;
+  const inside = f > row.masterStart && f < row.masterEnd;
+  const shotNo = row.sceneId === null ? null : (shotNumberOf(doc, row.sceneId) ?? null);
+  return [
+    {
+      kind: "action",
+      id: "clip-split",
+      label: "Split at playhead",
+      shortcut: shortcutFor("edit.split"),
+      disabled: !inside,
+      title: inside ? undefined : "Move the playhead inside the clip to split it.",
+      onSelect: () => store.splitAtPlayhead(),
+    },
+    move,
+    {
+      kind: "action",
+      id: "clip-duplicate",
+      label: "Duplicate",
+      shortcut: shortcutFor("edit.duplicate"),
+      onSelect: () => store.duplicateSelection(),
+    },
+    {
+      kind: "action",
+      id: "clip-home",
+      label: row.sceneId === null ? "Attach to shot" : `Detach from Shot ${shotNo ?? ""}`.trim(),
+      title:
+        row.sceneId === null
+          ? "Attach to the shot it starts in: it moves, duplicates and ends with that shot."
+          : "Move to the bed: it spans the cuts and stops following this shot.",
+      onSelect: () => store.moveAudioHome(row.clip.id),
+    },
+    { kind: "separator" },
+    {
+      kind: "action",
+      id: "clip-delete",
+      label: "Delete",
+      shortcut: shortcutFor("edit.delete"),
+      danger: true,
+      onSelect: () => store.deleteSelection(),
+    },
+  ];
+}
+
+function TrackRow(props: {
+  track: AudioTrack3D;
+  index: number;
+  rows: readonly RowClip[];
+  doc: Doc3D;
+  ppf: number;
+  labelWidth: number;
+  origin: number;
+  beginSnap: SnapPress;
+  rowAt: (clientY: number) => string | undefined;
+  dimmed: boolean;
+  soloed: boolean;
+  flashed: boolean;
+  empty: boolean;
+  onClipMenu: (row: RowClip) => (e: ReactMouseEvent<HTMLElement>) => void;
+  onTrackMenu: (track: AudioTrack3D, index: number, onRename: () => void) => (e: ReactMouseEvent<HTMLElement>) => void;
+  onGenerate: () => void;
+}) {
+  const { track, index, rows, doc, ppf, labelWidth, origin, beginSnap, rowAt } = props;
+  const store = useStore();
+  const [over, setOver] = useState(false);
+  const [importing, setImporting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [renaming, setRenaming] = useState(false);
+  const fileRef = useRef<HTMLInputElement | null>(null);
+  const muted = track.muted === true;
+
+  return (
+    <div
+      className={`sound-row sound-track-row${muted ? " is-muted" : ""}${props.dimmed ? " is-unsoloed" : ""}${
+        over ? " is-over" : ""
+      }${props.flashed ? " is-revealed" : ""}`}
+      data-sound-row={track.id}
+      data-testid={`sound-row-${track.id}`}
+      onDragOver={(e) => {
+        if (!e.dataTransfer.types.includes("Files")) return;
+        e.preventDefault();
+        setOver(true);
+      }}
+      onDragLeave={() => setOver(false)}
+      onDrop={(e) => {
+        if (!e.dataTransfer.types.includes("Files")) return;
+        e.preventDefault();
+        setOver(false);
+        importEach(store, e.dataTransfer.files, undefined, setImporting, setError, track.id);
+      }}
+    >
+      <TrackStrip
+        track={track}
+        width={labelWidth}
+        soloed={props.soloed}
+        renaming={renaming}
+        setRenaming={setRenaming}
+        onContextMenu={props.onTrackMenu(track, index, () => setRenaming(true))}
+      />
+      <div className="sound-lane">
+        {props.empty && !importing ? (
+          <span className="sound-empty" data-testid="sound-empty">
+            <span>Drop audio here, or</span>
+            <button
+              type="button"
+              className="btn is-ghost sound-empty-btn"
+              onPointerDown={(e) => e.stopPropagation()}
+              onClick={props.onGenerate}
+            >
+              + Generate
+            </button>
+            <button
+              type="button"
+              className="btn is-ghost sound-empty-btn"
+              onPointerDown={(e) => e.stopPropagation()}
+              onClick={() => store.setLibraryBrowserOpen(true, "sounds")}
+            >
+              Library
+            </button>
+            <button
+              type="button"
+              className="btn is-ghost sound-empty-btn"
+              onPointerDown={(e) => e.stopPropagation()}
+              onClick={() => fileRef.current?.click()}
+            >
+              Import
+            </button>
+            <input
+              ref={fileRef}
+              type="file"
+              accept={AUDIO_FILE_ACCEPT}
+              multiple
+              hidden
+              data-testid="sound-file-input"
+              onChange={(e) => {
+                importEach(store, e.currentTarget.files, undefined, setImporting, setError, track.id);
+                e.currentTarget.value = "";
+              }}
+            />
+          </span>
+        ) : null}
+        {rows.map((row) =>
+          row.layerId !== undefined ? (
+            <VideoSoundBar
+              key={`v:${row.layerId}:${row.sceneId ?? ""}`}
+              row={row}
+              doc={doc}
+              ppf={ppf}
+              origin={origin}
+              onContextMenu={props.onClipMenu(row)}
+            />
+          ) : (
+            <AudioClipBar
+              key={row.clip.id}
+              clip={row.clip}
+              asset={doc.assets[row.clip.asset]}
+              fps={doc.fps}
+              ppf={ppf}
+              offsetFrames={row.offsetFrames}
+              originFrames={origin}
+              beginSnap={beginSnap}
+              waveH={SOUND_WAVE_H}
+              mix
+              rowAt={rowAt}
+              onContextMenu={props.onClipMenu(row)}
+              {...(row.sceneId === null
+                ? {}
+                : {
+                    ownedBy: row.sceneId,
+                    limitFrames: Math.max(0, Math.trunc(doc.scenesById[row.sceneId]?.durationFrames ?? 0)),
+                    badge: `Shot ${shotNumberOf(doc, row.sceneId) ?? ""}`.trim(),
+                  })}
+            />
+          ),
+        )}
+        {error === null ? null : (
+          <p className="audio-error" role="status">
+            {error}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** A recording's sound on its track. Drawn, never dragged: its in, out and
+ *  level are the video layer's, trimmed in Rows mode's video row. */
+function VideoSoundBar(props: {
+  row: RowClip;
+  doc: Doc3D;
+  ppf: number;
+  origin: number;
+  onContextMenu: (e: ReactMouseEvent<HTMLElement>) => void;
+}) {
+  const { row, doc, ppf, origin } = props;
+  const left = frameToPx(row.masterStart - origin, ppf);
+  const width = Math.max(8, frameToPx(row.masterEnd - row.masterStart, ppf));
+  const layer = row.sceneId === null ? undefined : doc.scenesById[row.sceneId]?.layersById[row.layerId!];
+  const name = layer?.label ?? "Video";
+  return (
+    <div
+      className={`audio-clip is-video${row.clip.muted === true ? " is-muted" : ""}`}
+      data-audio-clip={row.clip.id}
+      data-readonly=""
+      style={{ left, width }}
+      title={`${name}: the recording's own sound. Trim it on the video's row in Rows.`}
+      onPointerDown={(e) => e.stopPropagation()}
+      onContextMenu={props.onContextMenu}
+    >
+      <AudioWaveform
+        clip={{ offsetFrames: row.clip.offsetFrames ?? 0, durationFrames: row.clip.durationFrames }}
+        asset={doc.assets[row.clip.asset]}
+        fps={doc.fps}
+        widthPx={width}
+        heightPx={SOUND_WAVE_H}
+      />
+      <span className="audio-clip-name">
+        <span className="audio-clip-lock" aria-hidden="true">
+          {LOCK_ICON}
+        </span>
+        {name} · video sound
+      </span>
+    </div>
+  );
+}
+
+// ── THE CHANNEL STRIP ────────────────────────────────────────────────────
+
+/**
+ * Begin a one-undo level drag on a track. `read` turns the pointer into the
+ * patch; it is called for the press too, so a press on the rail jumps there.
+ */
+function trackDrag(
+  store: Store,
+  trackId: string,
+  e: ReactPointerEvent<HTMLElement>,
+  read: (clientX: number, clientY: number) => Partial<Omit<AudioTrack3D, "id">>,
+  jump: boolean,
+): void {
+  if (e.button !== 0) return;
+  e.preventDefault();
+  e.stopPropagation();
+  if (!store.beginBlockDrag()) return;
+  if (jump) store.dragAudioTrack(trackId, read(e.clientX, e.clientY));
+  startDrag(e, {
+    onMove: (ev) => store.dragAudioTrack(trackId, read(ev.clientX, ev.clientY)),
+    onEnd: (commit) => store.endBlockDrag(commit),
+  });
+}
+
+/** Arrow keys on a level control: small steps, Shift for big ones. Stopped,
+ *  so the timeline's own arrows (edit points, nudges) do not fire too. */
+function stepKey(e: ReactKeyboardEvent<HTMLElement>, step: (by: number) => void): void {
+  const by =
+    e.key === "ArrowRight" || e.key === "ArrowUp" ? 1 : e.key === "ArrowLeft" || e.key === "ArrowDown" ? -1 : 0;
+  if (by === 0) return;
+  e.preventDefault();
+  e.stopPropagation();
+  step(by * (e.shiftKey ? 5 : 1));
+}
+
+function TrackStrip(props: {
+  track: AudioTrack3D;
+  width: number;
+  soloed: boolean;
+  renaming: boolean;
+  setRenaming: (on: boolean) => void;
+  onContextMenu: (e: ReactMouseEvent<HTMLElement>) => void;
+}) {
+  const { track, width, soloed, renaming, setRenaming } = props;
+  const store = useStore();
+  const muted = track.muted === true;
+  return (
+    <div
+      className="sound-strip-cell sound-strip"
+      style={{ width }}
+      data-testid={`sound-strip-${track.id}`}
+      onPointerDown={(e) => e.stopPropagation()}
+      onContextMenu={props.onContextMenu}
+    >
+      <div className="sound-strip-top">
+        <span className="sound-strip-dot" aria-hidden="true" />
+        {renaming ? (
+          <input
+            className="sound-strip-rename"
+            defaultValue={track.name}
+            aria-label="Track name"
+            autoFocus
+            onFocus={(e) => e.currentTarget.select()}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") e.currentTarget.blur();
+              if (e.key === "Escape") {
+                e.currentTarget.value = track.name;
+                e.currentTarget.blur();
+              }
+              e.stopPropagation();
+            }}
+            onBlur={(e) => {
+              const name = e.currentTarget.value.trim();
+              if (name !== "" && name !== track.name) store.updateAudioTrack(track.id, { name });
+              setRenaming(false);
+            }}
+          />
+        ) : (
+          <span className="sound-strip-name" title={`${track.name}: double-click to rename`} onDoubleClick={() => setRenaming(true)}>
+            {track.name}
+          </span>
+        )}
+        <button
+          type="button"
+          className={`sound-ms is-mute${muted ? " is-on" : ""}`}
+          aria-pressed={muted}
+          aria-label={`Mute ${track.name}`}
+          title={muted ? "Muted: saved with the film, so an export is silent here too" : "Mute this track"}
+          data-testid={`sound-mute-${track.id}`}
+          onClick={() => store.updateAudioTrack(track.id, { muted: !muted })}
+        >
+          M
+        </button>
+        <button
+          type="button"
+          className={`sound-ms is-solo${soloed ? " is-on" : ""}`}
+          aria-pressed={soloed}
+          aria-label={`Solo ${track.name}`}
+          title={soloed ? "Soloed in this tab only" : "Solo: hear this track alone, in this tab only"}
+          data-testid={`sound-solo-${track.id}`}
+          onClick={() => store.toggleSoloTrack(track.id)}
+        >
+          S
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function panLabel(pan: number): string {
+  if (Math.abs(pan) < 0.005) return "Centre";
+  return `${Math.round(Math.abs(pan) * 100)}% ${pan < 0 ? "left" : "right"}`;
+}
+
+/** Pan, -1..1. A vertical drag (up is right, 100px is full travel), as a
+ *  knob is turned on every console; double-click centres it. */
+function PanKnob({ track }: { track: AudioTrack3D }) {
+  const store = useStore();
+  const pan = track.pan ?? 0;
+  const angle = (pan * 135 * Math.PI) / 180;
+  const set = (p: number): number => {
+    const clamped = Math.max(-1, Math.min(1, p));
+    return Math.abs(clamped) < 0.02 ? 0 : Math.round(clamped * 100) / 100;
+  };
+  return (
+    <span
+      className="sound-pan"
+      role="slider"
+      tabIndex={0}
+      aria-label={`Pan ${track.name}`}
+      aria-valuemin={-1}
+      aria-valuemax={1}
+      aria-valuenow={pan}
+      aria-valuetext={panLabel(pan)}
+      title={`Pan: ${panLabel(pan)}. Drag up or down, double-click to centre.`}
+      data-testid={`sound-pan-${track.id}`}
+      onPointerDown={(e) => {
+        const y0 = e.clientY;
+        trackDrag(store, track.id, e, (_x, y) => ({ pan: set(pan - (y - y0) / 100) }), false);
+      }}
+      onDoubleClick={() => store.updateAudioTrack(track.id, { pan: 0 })}
+      onKeyDown={(e) => stepKey(e, (by) => store.updateAudioTrack(track.id, { pan: set(pan + by * 0.05) }))}
+    >
+      <svg width="18" height="18" viewBox="0 0 18 18" aria-hidden="true">
+        <circle cx="9" cy="9" r="7.5" />
+        <path d={`M9 9 L${(9 + 6 * Math.sin(angle)).toFixed(2)} ${(9 - 6 * Math.cos(angle)).toFixed(2)}`} />
+      </svg>
+    </span>
+  );
+}
+
+// ── THE MIXER COLUMN ─────────────────────────────────────────────────────
+
+/** Sound mode's right column: the peak and the one-press duck on top, then a
+ *  vertical strip per track (pan, level, its own meter), then the master's
+ *  meter. The dock's only meters: Rows and Graph show none. */
+export function SoundMixer() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const solo = useShotEditor((s) => s.soloTracks);
+  const muted = useShotEditor((s) => s.previewMuted);
+  const graph = useSyncExternalStore(subscribeMonitor, readMonitor, readMonitor);
+  useMeterTap(MASTER_METER_KEY, graph?.ctx ?? null, graph?.node ?? null);
+  if (doc === null) return null;
+  const tracks = audioTracksOf(doc);
+  const duck = voiceDuckState(doc);
+  return (
+    <div className="sound-mixer" data-testid="sound-mixer">
+      <div className="sound-mixer-head">
+        <span className="sound-mixer-title">Mixer</span>
+        {solo.length > 0 ? (
+          <button
+            type="button"
+            className="sound-solo-chip"
+            title="Solo is this tab's alone. Exports hear every track. Press to hear every track again."
+            onClick={() => {
+              for (const id of solo) store.toggleSoloTrack(id);
+            }}
+          >
+            Solo · clear
+          </button>
+        ) : (
+          <MixerPeak muted={muted} />
+        )}
+        <button
+          type="button"
+          className="sound-duck"
+          data-testid="sound-duck"
+          aria-pressed={duck.active}
+          disabled={!duck.available}
+          title={
+            duck.available
+              ? duck.active
+                ? "The other tracks dip while the voice speaks. Press to stop."
+                : "Dip the other tracks while the voice speaks"
+              : "Name a track Voice, with a clip on it, to duck the others under it"
+          }
+          onClick={() => store.setDuckUnderVoice(!duck.active)}
+        >
+          Duck under voice
+        </button>
+      </div>
+      <div className="sound-mixer-strips">
+        {tracks.map((t) => (
+          <MixerStrip
+            key={t.id}
+            track={t}
+            graph={graph}
+            dimmed={solo.length > 0 && !solo.includes(t.id)}
+            soloed={solo.includes(t.id)}
+          />
+        ))}
+        <div className="sound-mixer-strip is-master" data-testid="mixer-strip-master">
+          {/* The pan knob's slot, so the master's meters start level with
+            the tracks'. */}
+          <span className="sound-pan-slot" aria-hidden="true" />
+          <MasterHold />
+          <div className="sound-mixer-body">
+            <MeterPair meterKey={MASTER_METER_KEY} />
+          </div>
+          <span className="sound-mixer-name" title="Master: what the mix sends out, before the preview volume">
+            Master
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** The master strip's number: its held peak, the louder channel. A leaf, so
+ *  a reading re-renders this span and not the strips. */
+function MasterHold() {
+  const left = useMeterReading(meterChannelKey(MASTER_METER_KEY, "L"));
+  const right = useMeterReading(meterChannelKey(MASTER_METER_KEY, "R"));
+  return (
+    <span className="sound-mixer-db" data-testid="mixer-master-hold">
+      {dbLabel(Math.max(left.hold, right.hold), false)}
+    </span>
+  );
+}
+
+/** "−6.2 dB peak": the master's held peak, the louder channel. */
+function MixerPeak({ muted }: { muted: boolean }) {
+  const left = useMeterReading(meterChannelKey(MASTER_METER_KEY, "L"));
+  const right = useMeterReading(meterChannelKey(MASTER_METER_KEY, "R"));
+  return (
+    <span className="sound-mixer-peak" data-testid="sound-mixer-peak">
+      {muted ? "Preview muted" : `${dbLabel(Math.max(left.hold, right.hold))} peak`}
+    </span>
+  );
+}
+
+function MixerStrip(props: {
+  track: AudioTrack3D;
+  graph: ReturnType<typeof readMonitor>;
+  dimmed: boolean;
+  soloed: boolean;
+}) {
+  const { track, graph } = props;
+  const store = useStore();
+  const key = `track:${track.id}`;
+  useMeterTap(key, graph?.ctx ?? null, graph?.tracks.get(track.id) ?? null);
+  const gain = track.gain ?? 1;
+  const muted = track.muted === true;
+  return (
+    <div
+      className={`sound-mixer-strip${muted ? " is-muted" : ""}${props.dimmed ? " is-unsoloed" : ""}`}
+      data-testid={`mixer-strip-${track.id}`}
+    >
+      <PanKnob track={track} />
+      <span className="sound-mixer-db">{dbLabel(gain, false)}</span>
+      <div className="sound-mixer-body">
+        <MeterPair meterKey={key} />
+        <VFader
+          label={`${track.name} level`}
+          gain={gain}
+          onBegin={() => store.beginBlockDrag()}
+          onDrag={(g) => store.dragAudioTrack(track.id, { gain: g })}
+          onEnd={(commit) => store.endBlockDrag(commit)}
+          onReset={() => store.updateAudioTrack(track.id, { gain: 1 })}
+          onStep={(g) => store.updateAudioTrack(track.id, { gain: g })}
+        />
+      </div>
+      <span className="sound-mixer-ms">
+        <button
+          type="button"
+          className={`sound-ms is-mute${muted ? " is-on" : ""}`}
+          aria-pressed={muted}
+          aria-label={`Mute ${track.name}`}
+          onClick={() => store.updateAudioTrack(track.id, { muted: !muted })}
+        >
+          M
+        </button>
+        <button
+          type="button"
+          className={`sound-ms is-solo${props.soloed ? " is-on" : ""}`}
+          aria-pressed={props.soloed}
+          aria-label={`Solo ${track.name}`}
+          onClick={() => store.toggleSoloTrack(track.id)}
+        >
+          S
+        </button>
+      </span>
+      <span className="sound-mixer-name" title={track.name}>
+        {track.name}
+      </span>
+    </div>
+  );
+}
+
+/** Linear amplitude to a percentage of the meter. Logarithmic, because a
+ *  linear meter spends four fifths of its length on the top 6 dB and shows
+ *  nothing at all for dialogue sitting at -18.
+ *
+ *  `METER_FLOOR_DB` is `meterMath.ts`'s because the publisher's gate is
+ *  defined against this scale: two levels the floor flattens into the same 0%
+ *  are the same picture. Below the floor the meter is empty rather than
+ *  negative, here as there. */
+export function meterPercent(amplitude: number): number {
+  if (!Number.isFinite(amplitude) || amplitude <= 0) return 0;
+  const db = 20 * Math.log10(amplitude);
+  if (db <= METER_FLOOR_DB) return 0;
+  return Math.min(100, (1 - db / METER_FLOOR_DB) * 100);
+}
+
+/** Two vertical bars, L and R, each with its held peak. */
+function MeterPair({ meterKey }: { meterKey: string }) {
+  return (
+    <span className="sound-meter-pair" aria-hidden="true">
+      <MeterBar meterKey={meterKey} channel="L" />
+      <MeterBar meterKey={meterKey} channel="R" />
+    </span>
+  );
+}
+
+function MeterBar({ meterKey, channel }: { meterKey: string; channel: "L" | "R" }) {
+  const level = useMeterReading(meterChannelKey(meterKey, channel));
+  const lit = meterPercent(level.rms);
+  const held = meterPercent(level.hold);
+  return (
+    <span className="sound-meter">
+      <span className={`sound-meter-lit${lit > 95 ? " is-hot" : ""}`} style={{ height: `${lit}%` }} />
+      {held > 0 ? <span className="sound-meter-hold" style={{ bottom: `${held}%` }} /> : null}
+    </span>
+  );
+}
+
+/** A track's level: a vertical fader on the fader law. A press on the thumb
+ *  drags from where it is; a press on the rail jumps there first. */
+function VFader(props: {
+  label: string;
+  gain: number;
+  onBegin?: () => boolean;
+  onDrag: (gain: number) => void;
+  onEnd?: (commit: boolean) => void;
+  onReset: () => void;
+  onStep?: (gain: number) => void;
+}) {
+  const pos = faderPos(props.gain);
+  const write = (p: number): number => faderGain(p);
+  return (
+    <span
+      className="sound-vfader"
+      role="slider"
+      tabIndex={0}
+      aria-orientation="vertical"
+      aria-label={props.label}
+      aria-valuemin={0}
+      aria-valuemax={MAX_AUDIO_GAIN}
+      aria-valuenow={props.gain}
+      aria-valuetext={dbLabel(props.gain)}
+      title={`${dbLabel(props.gain)}. Drag to set, double-click for 0 dB.`}
+      onPointerDown={(e) => {
+        if (e.button !== 0) return;
+        e.preventDefault();
+        e.stopPropagation();
+        if (props.onBegin !== undefined && !props.onBegin()) return;
+        const rail = e.currentTarget.getBoundingClientRect();
+        const onThumb = (e.target as HTMLElement).classList.contains("sound-vfader-thumb");
+        const y0 = e.clientY;
+        const start = onThumb ? pos : (rail.bottom - e.clientY) / Math.max(1, rail.height);
+        if (!onThumb) props.onDrag(write(start));
+        startDrag(e, {
+          onMove: (ev) => props.onDrag(write(start - (ev.clientY - y0) / Math.max(1, rail.height))),
+          onEnd: (commit) => props.onEnd?.(commit),
+        });
+      }}
+      onDoubleClick={props.onReset}
+      onKeyDown={(e) => stepKey(e, (by) => (props.onStep ?? props.onDrag)(write(pos + by * 0.01)))}
+    >
+      <span className="sound-vfader-thumb" style={{ bottom: `${pos * 100}%` }} />
+    </span>
+  );
+}
+
+// ── TEMPO ────────────────────────────────────────────────────────────────
+
+/** The head's BPM chip and its popover. */
+export function TempoChip() {
+  const tempo = useShotEditor((s) => s.doc?.tempo);
+  const [open, setOpen] = useState(false);
+  const anchor = useRef<HTMLButtonElement | null>(null);
+  return (
+    <>
+      <button
+        ref={anchor}
+        type="button"
+        className={`sound-bpm-chip${tempo === undefined ? " is-unset" : ""}`}
+        data-testid="sound-bpm-chip"
+        aria-expanded={open}
+        title="The film's tempo: bar lines, beat snap and the bar readout"
+        onClick={() => setOpen((v) => !v)}
+      >
+        {METRONOME_ICON}
+        <span>{tempo === undefined ? "Set tempo" : tempoLabel(tempo)}</span>
+      </button>
+      <Popover open={open} anchor={anchor} onClose={() => setOpen(false)} className="sound-tempo-pop">
+        {open ? <TempoPopover /> : null}
+      </Popover>
+    </>
+  );
+}
+
+const BEATS_PER_BAR = [3, 4, 6, 7] as const;
+/** Taps further apart than this start a new count. */
+const TAP_RESET_MS = 2000;
+/** The tap tempo commits once the author stops tapping for this long. */
+const TAP_COMMIT_MS = 1500;
+
+export function TempoPopover() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const snap = useShotEditor((s) => s.snapBeats);
+  const tempo = doc?.tempo;
+  const [draft, setDraft] = useState<string>(tempo === undefined ? "" : String(Math.round(tempo.bpm * 100) / 100));
+  const [warning, setWarning] = useState<string | null>(null);
+  const [detecting, setDetecting] = useState(false);
+  const taps = useRef<number[]>([]);
+  const pending = useRef<{ timer: ReturnType<typeof setTimeout>; bpm: number } | null>(null);
+
+  useEffect(() => {
+    if (tempo !== undefined) setDraft(String(Math.round(tempo.bpm * 100) / 100));
+  }, [tempo?.bpm]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const write = (patch: Partial<Tempo3D>): void => {
+    const s = store.getState().doc?.tempo;
+    const bpm = patch.bpm ?? s?.bpm ?? 120;
+    store.setTempo({ ...(s ?? {}), ...patch, bpm });
+  };
+  const flush = (): void => {
+    const p = pending.current;
+    if (p === null) return;
+    clearTimeout(p.timer);
+    pending.current = null;
+    write({ bpm: p.bpm });
+  };
+  // A pending tap count is not lost when the popover closes.
+  useEffect(() => flush, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const commitDraft = (): void => {
+    const bpm = Number(draft);
+    if (draft.trim() === "" || !Number.isFinite(bpm)) return;
+    const clamped = Math.min(TEMPO_BPM_MAX, Math.max(TEMPO_BPM_MIN, Math.round(bpm * 100) / 100));
+    setDraft(String(clamped));
+    if (clamped !== tempo?.bpm) write({ bpm: clamped });
+  };
+
+  const tap = (): void => {
+    const now = performance.now();
+    const last = taps.current[taps.current.length - 1];
+    taps.current = last !== undefined && now - last > TAP_RESET_MS ? [now] : [...taps.current, now].slice(-8);
+    const t = taps.current;
+    if (t.length < 2) return;
+    const bpm = Math.round((60000 * (t.length - 1)) / (t[t.length - 1]! - t[0]!));
+    const clamped = Math.min(TEMPO_BPM_MAX, Math.max(TEMPO_BPM_MIN, bpm));
+    setDraft(String(clamped));
+    if (pending.current !== null) clearTimeout(pending.current.timer);
+    pending.current = { bpm: clamped, timer: setTimeout(flush, TAP_COMMIT_MS) };
+  };
+
+  const detect = async (): Promise<void> => {
+    if (doc === null) return;
+    const s = store.getState();
+    const all = authoredAudioClips(doc).filter((m) => m.layerId === undefined);
+    const source =
+      all.find((m) => s.selectedAudio.includes(m.clip.id)) ??
+      all.find((m) => s.frame >= m.clip.frame && s.frame < m.clip.frame + m.clip.durationFrames) ??
+      all[0];
+    if (source === undefined) {
+      setWarning("Add a music clip first: the tempo is read from its beat analysis.");
+      return;
+    }
+    const asset = doc.assets[source.clip.asset];
+    const name = clipLabel(source.clip, asset);
+    if (asset === undefined) return;
+    setDetecting(true);
+    setWarning(null);
+    try {
+      const bytes = await fetchAssetBytes(audioAnalysisFileName(asset.path));
+      const analysis = JSON.parse(new TextDecoder().decode(bytes)) as {
+        beats?: { bpm: number | null; reliable: boolean; gridPhaseSeconds: number | null };
+      };
+      const beats = analysis.beats;
+      if (beats === undefined || beats.bpm === null || !(beats.bpm > 0)) {
+        setWarning(`${name} has no steady beat to read. Set the tempo by hand or tap it.`);
+        return;
+      }
+      const bpm = Math.min(TEMPO_BPM_MAX, Math.max(TEMPO_BPM_MIN, Math.round(beats.bpm * 100) / 100));
+      const perBar = Math.max(1, Math.trunc(store.getState().doc?.tempo?.beatsPerBar ?? 4));
+      const fps = doc.fps.num / doc.fps.den;
+      // The file's first grid line, on the master timeline: where the source's
+      // second 0 sits, plus the phase. Folded back by whole bars so the grid
+      // starts at or after frame 0.
+      const raw = source.clip.frame - (source.clip.offsetFrames ?? 0) + (beats.gridPhaseSeconds ?? 0) * fps;
+      const bar = ((60 * fps) / bpm) * perBar;
+      const startFrame = Math.round(((raw % bar) + bar) % bar);
+      write({ bpm, startFrame });
+      setDraft(String(bpm));
+      if (!beats.reliable) {
+        setWarning(`${name} reads as ${bpm} BPM, but its beat grid is not reliable. Check it by ear before you snap.`);
+      }
+    } catch {
+      setWarning(`${name} has no beat analysis yet. Re-import it, or set the tempo by hand.`);
+    } finally {
+      setDetecting(false);
+    }
+  };
+
+  const perBar = Math.max(1, Math.trunc(tempo?.beatsPerBar ?? 4));
+  return (
+    <div className="sound-tempo" data-testid="sound-tempo">
+      <div className="sound-tempo-head">
+        <span className="sound-tempo-title">Tempo</span>
+        <span className="sound-tempo-scope">this doc</span>
+      </div>
+      <div className="sound-tempo-bpm">
+        <input
+          className="text-input sound-tempo-input"
+          inputMode="decimal"
+          aria-label="Beats per minute"
+          data-testid="sound-tempo-bpm"
+          value={draft}
+          placeholder="120"
+          onChange={(e) => setDraft(e.currentTarget.value)}
+          onBlur={commitDraft}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") commitDraft();
+          }}
+        />
+        <span className="sound-tempo-unit">BPM</span>
+        <button type="button" className="btn is-outline sound-tempo-tap" data-testid="sound-tempo-tap" onClick={tap}>
+          Tap
+        </button>
+      </div>
+      <div className="sound-tempo-field">
+        <span className="sound-tempo-label">Beats per bar</span>
+        <span className="sound-tempo-seg" role="radiogroup" aria-label="Beats per bar">
+          {BEATS_PER_BAR.map((n) => (
+            <button
+              key={n}
+              type="button"
+              role="radio"
+              aria-checked={perBar === n}
+              className={`sound-tempo-seg-btn${perBar === n ? " is-on" : ""}`}
+              onClick={() => write({ beatsPerBar: n })}
+            >
+              {n}
+            </button>
+          ))}
+        </span>
+      </div>
+      <div className="sound-tempo-field">
+        <span className="sound-tempo-label">
+          Snap to beats
+          <span className="sound-tempo-hint">This tab only</span>
+        </span>
+        <Toggle checked={snap} onChange={(on) => store.setSnapBeats(on)} ariaLabel="Snap to beats" />
+      </div>
+      <span className="sound-tempo-rule" aria-hidden="true" />
+      <div className="sound-tempo-actions">
+        <button
+          type="button"
+          className="btn is-outline sound-tempo-detect"
+          data-testid="sound-tempo-detect"
+          disabled={detecting}
+          onClick={() => void detect()}
+        >
+          {detecting ? "Reading…" : "Detect from clip"}
+        </button>
+        {tempo === undefined ? null : (
+          <button type="button" className="btn is-ghost" onClick={() => store.setTempo(null)}>
+            Remove
+          </button>
+        )}
+      </div>
+      {warning === null ? null : (
+        <p className="sound-tempo-warn" role="status" data-testid="sound-tempo-warn">
+          {warning}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/** The head's two sound verbs: the library's sounds and the Generate drawer.
+ *  Generate shows once the host says some kind is available, or, hosted, that
+ *  only the workspace's own ElevenLabs key is missing (`needsKey`): the drawer
+ *  then says who adds it. A local studio without the key has no dead button. */
+export function SoundHeadTools(props: { generateOpen: boolean; onGenerate: () => void }) {
+  const store = useStore();
+  const project = useShotEditor((s) => s.name);
+  const [canGenerate, setCanGenerate] = useState(false);
+  useEffect(() => {
+    if (project === null) return;
+    let live = true;
+    generationStatus(project).then(
+      (s) => {
+        if (live) setCanGenerate(s.needsKey !== undefined || Object.values(s.kinds).some((k) => k.ok));
+      },
+      () => {
+        if (live) setCanGenerate(false);
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [project]);
+  return (
+    <>
+      <button
+        type="button"
+        className="btn is-outline sound-head-btn"
+        data-testid="sound-library"
+        title="Browse the library's sounds"
+        onClick={() => store.setLibraryBrowserOpen(true, "sounds")}
+      >
+        {LIBRARY_ICON}
+        Library
+      </button>
+      {canGenerate || props.generateOpen ? (
+        <button
+          type="button"
+          className="btn sound-head-btn is-accent"
+          data-testid="sound-generate"
+          aria-pressed={props.generateOpen}
+          title="Generate a sound effect, music or a voice"
+          onClick={props.onGenerate}
+        >
+          {SPARKLES_ICON}
+          Generate
+        </button>
+      ) : null}
+    </>
+  );
+}