@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/snap.ts

@@ -16,22 +16,20 @@
 // the pull feels the same size at every zoom. A threshold in frames would get
 // stronger as the author zoomed out until a whole scene was one sticky point;
 // the store's layout snapping is divided by the view zoom for the same reason.
-import { sceneWindows } from "@dailies-studio/shot/doc";
+import { beatFrames, masterAudioClips, sceneWindows } from "@dailies-studio/shot/doc";
 import type { Doc3D } from "@dailies-studio/shot/doc";
 import { lifespanOf } from "./model.js";
 
 /** How close a moving edge has to come, in SCREEN px. */
 export const TIMELINE_SNAP_PX = 6;
 
-export type SnapKind = "playhead" | "marker" | "scene" | "block" | "lifespan" | "audio";
+export type SnapKind = "playhead" | "marker" | "scene" | "lifespan" | "audio" | "beat";
 
 export interface SnapTarget {
   /** MASTER frame. Every target in one space, because a gesture that crosses a
-   *  scene boundary has to compare a scene-2 block edge with a scene-1 one. */
+   *  scene boundary has to compare a scene-2 lifespan edge with a scene-1 one. */
   frame: number;
   kind: SnapKind;
-  /** What the guide would say if the UI ever labelled it. */
-  label: string;
 }
 
 export interface SnapHit {
@@ -56,28 +54,64 @@ export interface SnapScope {
    *
    * Without it every drag is pinned at zero travel: the bar under the pointer
    * is always exactly on its own edge, so it wins every comparison and the
-   * gesture never leaves the ground.
-   *
-   * `blockId` narrows that to the ONE bar. A lifespan drag moves the layer's bar
-   * and every block on it, so the whole layer really is in motion and none of its
-   * edges is a target. A block drag moves exactly one bar: its siblings and the
-   * layer's own lifespan stay put, and butting a During block against the In
-   * block's end — or onto the lifespan in, which is the pairing the lifespan row
-   * exists to make visible — is the most natural alignment in the lane. Excluding
-   * them buys nothing and disables it.
+   * gesture never leaves the ground. A lifespan drag moves the layer's bar and
+   * every key on it, so the whole layer is in motion and none of its edges is a
+   * target.
    */
   exclude?: {
     sceneId?: string;
     layerId?: string;
-    blockId?: string;
-    /** The audio clip a gesture is moving. Document-level, so it carries no
-     *  scene: `doc.audio` is timed on MASTER frames. */
+    /**
+     * EVERY bar a gesture is moving an edge of, for the single-bar reason above
+     * read once per bar: a body drag over a selection of four clips has four
+     * bars sitting exactly on their own edges, and any one of them wins every
+     * comparison and pins the whole gesture at zero travel.
+     *
+     * A ROLL is the other list, and it is a PAIR rather than a selection: the
+     * seam is one layer's `out` and the next layer's `in` at the same frame, so
+     * the partner's edge sits exactly on the frame under the pointer and pins
+     * the drag just as surely as the pressed bar's own edge would. Naming both
+     * sides is what makes a seam drag able to leave the ground.
+     *
+     * Carries no scene, on the same ground `audioClipId` and `markerId` state:
+     * a layer id is document-unique (`usedIdsOf` mints against every home at
+     * once), so the id identifies the bar without one.
+     */
+    layerIds?: readonly string[];
+    /** The audio clip a gesture is moving. Carries no scene even when a shot
+     *  owns the clip: the id is document-unique across both homes (`usedIdsOf`
+     *  mints against all of them), so it identifies the clip on its own. */
     audioClipId?: string;
     /** The marker a gesture is moving. Same reason as `audioClipId`, and it is
      *  not optional politeness: a marker sits exactly on its own target, so
      *  without this a marker drag is pinned at zero travel. */
     markerId?: string;
+    /** A shot's out trim RIPPLES: every scene, lifespan and shot-owned
+     *  audio edge at or past this master frame moves with the trim, so none of
+     *  them is a target. The playhead, the markers and the Project's audio stay
+     *  put. */
+    rippleFromFrame?: number;
   };
+  /**
+   * WHERE THE MOVING EDGE MAY LEGALLY LAND, in master frames.
+   *
+   * Applied AT COLLECTION TIME, so an illegal target is simply not on the list.
+   * That is one code path rather than two: a trim bounded by `legalTrimRange`
+   * and a seam bounded by `legalRollRange` can only ever snap to a frame their
+   * op accepts, so an edge never appears to stick to a guide and then slip off
+   * it when the op clamps the same gesture back inside the range.
+   *
+   * An EMPTY range filters everything out, which is the right answer and needs
+   * no extra branch: `LegalRange` marks an empty intersection by carrying a
+   * `min` above its `max`, and no frame is both. An edge with nowhere legal to
+   * go has nothing legal to snap to.
+   *
+   * Omitted means unbounded above; frame 0 remains the floor either way.
+   */
+  legal?: { min: number; max: number };
+  /** Offer the beat grid's frames too (gap 8), when the document has a
+   *  `tempo`. The dock's per-tab toggle (`snapBeats`). */
+  beats?: boolean;
 }
 
 /**
@@ -89,53 +123,78 @@ export interface SnapScope {
  *
  * Deduped by frame, first writer wins, which makes the push order below a
  * PRIORITY order: the playhead and the markers are what the author put there on
- * purpose, so a guide at a frame that is also a scene boundary names the marker.
+ * purpose, so a hit on a frame that is also a scene boundary comes back as the
+ * marker.
  */
 export function collectSnapTargets(doc: Doc3D, opts: SnapScope): SnapTarget[] {
   const out: SnapTarget[] = [];
   const seen = new Set<number>();
-  const push = (frame: number, kind: SnapKind, label: string): void => {
+  // Frame 0 is the floor whether or not a legal range was given, so the two
+  // bounds fold into one pair and `push` keeps one comparison per side.
+  const lo = Math.max(0, opts.legal?.min ?? 0);
+  const hi = opts.legal?.max ?? Infinity;
+  const ripple = opts.exclude?.rippleFromFrame ?? Infinity;
+  /** `rides`: the edge moves under a ripple trim (`exclude.rippleFromFrame`). */
+  const push = (frame: number, kind: SnapKind, rides = true): void => {
     const at = Math.round(frame);
-    if (at < 0 || seen.has(at)) return;
+    if (at < lo || at > hi || seen.has(at) || (rides && at >= ripple)) return;
     seen.add(at);
-    out.push({ frame: at, kind, label });
+    out.push({ frame: at, kind });
   };
+  // The bars a multi-bar drag is moving. Built once: `exclude.layerIds` is read
+  // inside the layer loop, and a list scan per layer per scene is the only part
+  // of this walk that would grow with the selection.
+  const moving = new Set(opts.exclude?.layerIds ?? []);
 
-  push(opts.playhead, "playhead", "playhead");
+  push(opts.playhead, "playhead", false);
   for (const marker of doc.markers ?? []) {
     if (marker.id === opts.exclude?.markerId) continue;
-    push(marker.frame, "marker", marker.label ?? "marker");
+    push(marker.frame, "marker", false);
   }
 
-  // Audio edges are MASTER frames already, so they need no scene offset — and
-  // they come before the scene loop because landing a block on the start of the
-  // music is the alignment this lane is for.
-  for (const clip of Object.values(doc.audio)) {
+  // Audio edges, THROUGH THE FLATTEN so a clip its shot owns is a target too —
+  // its scene-local frames arrive here already shifted onto the master base
+  // every other target on this list is in. They come before the scene loop
+  // because landing a layer on the start of the music is the alignment this
+  // lane is for.
+  for (const { clip, layerId, sceneId } of masterAudioClips(doc)) {
     if (clip.id === opts.exclude?.audioClipId) continue;
-    push(clip.frame, "audio", "audio in");
-    push(clip.frame + clip.durationFrames, "audio", "audio out");
+    // A RECORDING'S OWN SOUND IS THE OTHER HALF OF THE BAR BEING DRAGGED, and
+    // without this line it defeats the whole exclusion below. The flatten
+    // places `video.sound` at `max(lifetime.in, offsetFrames)` for the rest of
+    // the window, so a video layer contributes an "audio" target on the very
+    // lifespan edge the layer loop is careful to withhold: a clip drag then had
+    // a target at distance zero from its own anchor and was pinned at zero
+    // travel for the first frame of pointer travel.
+    if (layerId !== undefined && (moving.has(layerId) || layerId === opts.exclude?.layerId)) continue;
+    push(clip.frame, "audio", sceneId !== null);
+    push(clip.frame + clip.durationFrames, "audio", sceneId !== null);
   }
 
   for (const window of sceneWindows(doc)) {
     const scene = doc.scenesById[window.id];
     if (scene === undefined) continue;
-    push(window.start, "scene", `${scene.name} start`);
-    push(window.end, "scene", `${scene.name} end`);
+    push(window.start, "scene");
+    push(window.end, "scene");
     for (const layer of Object.values(scene.layersById)) {
-      const moving =
-        opts.exclude?.sceneId === window.id && opts.exclude.layerId === layer.id ? opts.exclude : undefined;
-      // The whole layer only when the whole layer moves — see SnapScope.exclude.
-      if (moving !== undefined && moving.blockId === undefined) continue;
-      const life = lifespanOf(layer, scene);
-      push(window.start + life.in, "lifespan", `${layer.label} in`);
-      push(window.start + life.out, "lifespan", `${layer.label} out`);
-      for (const block of layer.blocks) {
-        if (block.id === moving?.blockId) continue;
-        push(window.start + block.frame, "block", `${layer.label} ${block.preset}`);
-        push(window.start + block.frame + block.durationFrames, "block", `${layer.label} ${block.preset} end`);
-      }
+      // A BAR THIS GESTURE CARRIES offers neither of its edges: the whole
+      // layer is in motion (see SnapScope.exclude).
+      if (moving.has(layer.id)) continue;
+      if (opts.exclude?.sceneId === window.id && opts.exclude.layerId === layer.id) continue;
+      const life = lifespanOf(layer, scene.durationFrames);
+      push(window.start + life.in, "lifespan");
+      push(window.start + life.out, "lifespan");
     }
   }
+  // BEATS LAST, the lowest priority: a beat is a grid nobody placed on this
+  // frame, so a marker, a cut or a clip edge on the same frame wins it. The
+  // grid runs to the furthest edge already listed plus a bar, so a clip can
+  // still be dragged out past the film's end onto a beat.
+  if (opts.beats === true && doc.tempo !== undefined) {
+    const last = out.reduce((max, t) => Math.max(max, t.frame), 0);
+    const bar = Math.ceil((60 * doc.fps.num * (doc.tempo.beatsPerBar ?? 4)) / (doc.fps.den * doc.tempo.bpm));
+    for (const beat of beatFrames(doc.tempo, doc.fps, lo, Math.min(hi + 1, last + bar + 1))) push(beat.frame, "beat", false);
+  }
   return out;
 }
 
@@ -162,6 +221,16 @@ export function snapFrame(
   return best === null ? { frame: rounded, target: null } : { frame: best.frame, target: best };
 }
 
+// ── ONE ANCHOR PER GESTURE ───────────────────────────────────────────────────
+//
+// There is no multi-edge pairing here, and a `snapDelta` that offered one was
+// deleted rather than wired: nothing called it, and the rows do not work that
+// way. A body drag picks ONE anchor at the press (`LifespanRow`: "WHAT THE
+// POINTER IS CARRYING is what snaps") and moves the rest by the delta that
+// anchor came back with, which is why `SnapPress` below is a one-candidate
+// closure. Wanting several edges in play is a real change to that type and to
+// every row that presses, not a missing call.
+
 /**
  * What a row is handed at the press: give it the frame you want and it gives
  * back the frame you get, having told the dock where to draw the guide.
@@ -173,6 +242,19 @@ export function snapFrame(
 export type SnapPress = (
   exclude: SnapScope["exclude"],
   suppressed: boolean,
+  /**
+   * WHERE THIS GESTURE MAY LEGALLY LAND, in MASTER frames — the row's own range
+   * already shifted onto the base every target is collected in.
+   *
+   * A third argument rather than something the dock could derive, because only
+   * the row knows which bound it is under: a clip's `in` edge is bounded by its
+   * footage and its own `out`, a seam by both sides' footage at once, and the
+   * dock sees a candidate frame and nothing else. Omitted by every gesture with
+   * no bound, which is every gesture but a clip's two edges and its seam. See
+   * `SnapScope.legal` for why it filters at collection rather than clamping
+   * after.
+   */
+  legal?: SnapScope["legal"],
 ) => (candidateMasterFrame: number) => number;
 
 /**

package/src/panels/timeline/staggerPreview.tsx

@@ -0,0 +1,92 @@
+// THE STAGGER'S ON-SCREEN HALF (Paper page 23, "8 · Stagger").
+//
+// A stagger moves several rows at once, and each row draws its own ghost, so the
+// press-time picture has to reach rows the pressed one does not own. It is
+// transient pointer state, not editor state: nothing is saved, undone or synced,
+// so it lives here rather than in the store.
+//
+// ponytail: one module-level slot, because there is one pointer. Two editors
+// dragging at once in one page would share it; scope it per store if that ever
+// becomes a real case.
+import { useSyncExternalStore } from "react";
+import { frameToPx } from "@dailies-studio/timeline";
+import { formatCombo } from "../../state/shortcuts.js";
+
+export interface StaggerPreview {
+  /** Each moving bar's `in` at the press, in LANE frames (drawing clock). */
+  from: Readonly<Record<string, number>>;
+  /** The bar (or the key row) the pointer holds: it carries the readout. */
+  grabbed: string;
+  /** The step in frames, not the total: what the author is choosing. */
+  step: number;
+  /** Where a key row's readout sits, in lane pixels. A bar row places its own,
+   *  beside the bar. */
+  anchor?: number;
+}
+
+let preview: StaggerPreview | null = null;
+const listeners = new Set<() => void>();
+
+export function setStaggerPreview(next: StaggerPreview | null): void {
+  preview = next;
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** This row's press-time `in`, or null when it is not in a running stagger.
+ *  A primitive, so only the rows whose answer changed re-render. */
+export function useStaggerGhost(id: string): number | null {
+  return useSyncExternalStore(subscribe, () => preview?.from[id] ?? null);
+}
+
+/** The running stagger when `id` holds its readout, else null. The slot's own
+ *  object, so the snapshot is stable between two sets. */
+export function useStaggerReadout(id: string): StaggerPreview | null {
+  return useSyncExternalStore(subscribe, () => (preview?.grabbed === id ? preview : null));
+}
+
+/** "Stagger +20f": the sign always shows, so a step left reads as one. */
+export function staggerLabel(step: number): string {
+  return `Stagger ${step < 0 ? "−" : "+"}${Math.abs(step)}f`;
+}
+
+/** The dashed box where a bar started, and the accent rule as long as its shift. */
+export function StaggerGhost({
+  fromFrame,
+  width,
+  shift,
+  ppf,
+}: {
+  fromFrame: number;
+  width: number;
+  shift: number;
+  ppf: number;
+}) {
+  const left = frameToPx(fromFrame, ppf);
+  const travel = frameToPx(Math.abs(shift), ppf);
+  return (
+    <span className="stagger-ghost" data-stagger-ghost="" style={{ left, width }} aria-hidden="true">
+      {shift === 0 ? null : (
+        // Leftward from the ghost's left edge for a step back, rightward otherwise.
+        <span
+          className="stagger-shift"
+          style={shift < 0 ? { right: "100%", width: travel } : { left: 0, width: travel }}
+        />
+      )}
+    </span>
+  );
+}
+
+/** The floating readout beside the grabbed bar. */
+export function StaggerChip({ step, left }: { step: number; left: number }) {
+  return (
+    <span className="stagger-chip" data-testid="stagger-readout" role="status" style={{ left }}>
+      <span className="stagger-chip-step">{staggerLabel(step)}</span>
+      <span className="stagger-chip-key">{formatCombo("⌥")}</span>
+    </span>
+  );
+}

package/src/panels/timeline/takeMeasure.ts

@@ -0,0 +1,72 @@
+// Measuring a generated take in this tab, for the Generate drawer's choice
+// between two: decode it, then the shared measuring functions over its PCM
+// (`@dailies-studio/shot/measure`), into the facts `rankSfxTakes` reads.
+//
+// A CHUNK OF ITS OWN: the drawer imports this module with `import()` when two
+// takes arrive, and the three functions are imported here BY NAME. A dynamic
+// import of the measure entry itself keeps every export it has, the probe's
+// lazy mediabunny among them, which put a 75 kB chunk in the build for code
+// this never runs.
+//
+// It ADVISES a choice and nothing more: the decode is the browser's, whose
+// resampler the spec leaves open, so these numbers are close to a sidecar's,
+// not equal to it, and nothing stored or exported reads them. A take that
+// cannot be measured here is shown unranked, and the drawer says to listen.
+import { rankSfxTakes, takeFacts, toneCheck } from "@dailies-studio/shot/doc";
+import type { TakeFacts } from "@dailies-studio/shot/doc";
+import type { GenerationTake } from "../../api.js";
+import { measureLoudness, rmsEnvelopeDb, spectralBalance } from "@dailies-studio/shot/measure";
+
+const RATE = 48_000;
+
+/**
+ * The takes as the drawer shows them: the one that measures better first,
+ * the reasons, and the tone check on it. A take this browser cannot measure
+ * leaves both unranked, with a word to listen instead.
+ */
+export async function judgeTakes(
+  takes: readonly GenerationTake[],
+  requestedSeconds: number,
+): Promise<{ order: GenerationTake[]; reasons: string[]; tone: string | null }> {
+  const facts = await Promise.all(takes.map((take) => measureTake(take.url, requestedSeconds)));
+  if (facts.some((f) => f === null)) {
+    return { order: [...takes], reasons: takes.length > 1 ? ["These takes could not be measured in this browser, so listen to both."] : [], tone: null };
+  }
+  const measured = facts as TakeFacts[];
+  if (takes.length < 2) return { order: [...takes], reasons: [], tone: measured[0] === undefined ? null : toneCheck(measured[0]) };
+  const ranked = rankSfxTakes(measured);
+  const pick = takes[ranked.pick]!;
+  return { order: [pick, ...takes.filter((take) => take !== pick)], reasons: ranked.reasons, tone: toneCheck(measured[ranked.pick]!) };
+}
+
+/** The take at `url` as the facts a ranking reads, or null when this browser
+ *  cannot decode it. `requestedSeconds` is the length that was asked for. */
+export async function measureTake(url: string, requestedSeconds: number): Promise<TakeFacts | null> {
+  try {
+    const Context = globalThis.OfflineAudioContext;
+    if (Context === undefined) return null;
+    const bytes = await (await fetch(url)).arrayBuffer();
+    const buffer = await new Context(2, 1, RATE).decodeAudioData(bytes);
+    const left = buffer.getChannelData(0);
+    const right = buffer.numberOfChannels > 1 ? buffer.getChannelData(1) : left;
+    const frames = buffer.length;
+    const samples = new Int16Array(frames * 2);
+    for (let i = 0; i < frames; i++) {
+      samples[i * 2] = Math.max(-32768, Math.min(32767, Math.round(left[i]! * 32768)));
+      samples[i * 2 + 1] = Math.max(-32768, Math.min(32767, Math.round(right[i]! * 32768)));
+    }
+    const wav = { sampleRate: buffer.sampleRate, channels: 2, frames, samples };
+    return takeFacts(
+      {
+        rmsDb: rmsEnvelopeDb(wav),
+        hopSamples: 960,
+        sampleRate: buffer.sampleRate,
+        loudness: measureLoudness(wav),
+        spectral: spectralBalance(wav),
+      },
+      requestedSeconds,
+    );
+  } catch {
+    return null;
+  }
+}

package/src/panels/timeline/useLive.ts

@@ -0,0 +1,48 @@
+// IS THE PLAYHEAD INSIDE THIS BAR RIGHT NOW.
+//
+// The timeline's one live state, and the reason `--bar-live` exists: a bar is
+// green while the clock is in it and the hueless ink wash otherwise, so the
+// strip says what is playing without the author tracing the playhead down forty
+// rows to see which bars it crosses.
+//
+// ── WHY THIS IS A BOOLEAN SUBSCRIPTION AND NOT A FRAME ONE ─────────────────
+//
+// `useSyncExternalStore` notifies a component only when the SELECTED value
+// changes, so selecting the predicate rather than the frame means a bar
+// re-renders exactly twice per playhead pass-through — once on the way in and
+// once on the way out — instead of once per playback frame. Forty bars on
+// screen at 30fps is 80 renders over the length of a shot rather than 1200 a
+// second, and the lane holding them never re-renders at all.
+//
+// `MarkerLane` found this shape first (`s.frame === marker.frame`); this is the
+// same trick over a half-open range. The rule it protects is `TimelineDock`'s
+// own header: THE FRAME STAYS OUT OF THAT COMPONENT. A dock root subscribed to
+// the frame re-renders every scene group, camera row, track row and block bar
+// thirty times a second, which is the performance hole this lane has already
+// paid for once.
+//
+// The hot channel is right here and nowhere higher: `useShotEditorHot` is the
+// one that fires on a frame-only `set`, and its own contract is that it lives
+// "at the smallest leaf that must repaint every tick".
+import { useShotEditorHot } from "../../state/context.js";
+import { laneFrame } from "./model.js";
+
+/**
+ * @param startLane  The bar's left edge in LANE frames — the same number its
+ *                   `left` is drawn from, which is what keeps the highlight and
+ *                   the pixels from disagreeing about where the bar is.
+ * @param endLane    Its right edge, HALF-OPEN: a bar that ends at frame 60 is
+ *                   not live at 60, because the next one starts there and two
+ *                   adjacent bars must never both be lit.
+ * @param origin     The lane's re-zero, as `laneFrame` means it (a shot's
+ *                   master start, or 0 in the scene and definition contexts).
+ *                   `laneFrame` picks the master clock or the definition's own,
+ *                   so a bar in a component reads `defFrame` with no extra
+ *                   argument here.
+ */
+export function useLive(startLane: number, endLane: number, origin: number): boolean {
+  return useShotEditorHot((s) => {
+    const frame = laneFrame(s, origin);
+    return frame >= startLane && frame < endLane;
+  });
+}