@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/inspector/storyboard/VideoStill.tsx

@@ -0,0 +1,120 @@
+// A VIDEO REFERENCE'S STILL: the video seeked to the card's frame, and
+// "Extract still" beside it, which draws that frame to a canvas and uploads it
+// as an image card in the same lane, carrying where it came from. Same-origin
+// bytes, so the canvas is not tainted; drawn only after `seeked` with data in
+// hand. It lives in the inspector: the lead is the one place a card is
+// looked at up close.
+//
+// IT DRAWS THE LEAD BOX ITSELF, and a frame past the recording's end is said in
+// its own row UNDER the box. The notice used to sit inside the 16:9 lead after
+// a video 100% tall, and the lead clips, so the one message that explained a
+// frozen still was never seen.
+import { useEffect, useRef, useState } from "react";
+import { useLocked } from "@dailies-studio/ui";
+import { useStore } from "../../../state/context.js";
+import { storyboardVideoSeconds } from "../../../state/storyboardModel.js";
+
+const assetUrl = (path: string): string => `/studio/assets/${encodeURIComponent(path)}`;
+
+export function VideoStill(props: { id: string; assetId: string; path: string; frame: number; fps: { num: number; den: number }; label: string }) {
+  const store = useStore();
+  const video = useRef<HTMLVideoElement | null>(null);
+  const [ready, setReady] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Extract still WRITES (a new card, and its picture uploaded), so a
+  // viewer's locked panel takes it with the section's other write verbs.
+  const locked = useLocked();
+  const tolerance = Math.max(0.002, props.fps.den / props.fps.num / 2);
+
+  useEffect(() => {
+    const el = video.current;
+    if (el === null) return;
+    setReady(false);
+    setError(null);
+    const decoded = (): void => {
+      const seconds = storyboardVideoSeconds(props.frame, props.fps, el.duration);
+      if (seconds !== null && !el.seeking && el.readyState >= 2 && Math.abs(el.currentTime - seconds) <= tolerance) {
+        setReady(true);
+      }
+    };
+    const seek = (): void => {
+      const seconds = storyboardVideoSeconds(props.frame, props.fps, el.duration);
+      if (seconds === null) {
+        setError(`Frame ${props.frame} is outside this video's duration.`);
+        return;
+      }
+      el.currentTime = seconds;
+      decoded();
+    };
+    el.addEventListener("seeked", decoded);
+    el.addEventListener("loadeddata", decoded);
+    el.addEventListener("loadedmetadata", seek);
+    if (el.readyState >= 1) seek();
+    return () => {
+      el.removeEventListener("loadedmetadata", seek);
+      el.removeEventListener("loadeddata", decoded);
+      el.removeEventListener("seeked", decoded);
+    };
+  }, [tolerance, props.frame, props.fps, props.path]);
+
+  const extract = async (): Promise<void> => {
+    const el = video.current;
+    if (el === null || !ready || busy || el.seeking || el.readyState < 2) return;
+    const seconds = storyboardVideoSeconds(props.frame, props.fps, el.duration);
+    if (seconds === null || Math.abs(el.currentTime - seconds) > tolerance) return;
+    // Capture identity, lane and provenance before either async boundary.
+    // The store registers the provenance with the new card in ONE edit.
+    const doc = store.getState().doc;
+    const item = doc?.resources?.references?.find((r) => r.id === props.id);
+    if (doc === null || item?.type !== "asset" || item.asset !== props.assetId || doc.assets[item.asset]?.path !== props.path) return;
+    const source = { frame: props.frame, asset: props.assetId };
+    const lane = item.part ?? null;
+    setBusy(true);
+    try {
+      const canvas = document.createElement("canvas");
+      canvas.width = el.videoWidth;
+      canvas.height = el.videoHeight;
+      const ctx = canvas.getContext("2d");
+      if (ctx === null) throw new Error("Could not read this video frame.");
+      ctx.drawImage(el, 0, 0);
+      const blob = await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, "image/png"));
+      if (blob === null) throw new Error("Could not encode this video frame.");
+      if (store.getState().doc?.id !== doc.id) return;
+      await store.addReferenceFromFile(new File([blob], `${props.label}-f${source.frame}.png`, { type: "image/png" }), lane, source);
+    } catch (e) {
+      store.reportError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <>
+      <div className="insp-reference-lead">
+        <video
+          ref={video}
+          className="insp-video-still"
+          src={assetUrl(props.path)}
+          preload="metadata"
+          muted
+          playsInline
+        />
+        <button
+          type="button"
+          className="btn"
+          disabled={!ready || busy || locked}
+          title="Save this frame as an image card in the same lane"
+          onClick={() => void extract()}
+        >
+          {busy ? "Saving…" : "Extract still"}
+        </button>
+      </div>
+      {error === null ? null : (
+        <div className="insp-notice is-warn" role="status">
+          {error}
+        </div>
+      )}
+    </>
+  );
+}

package/src/panels/inspector/timeModel.ts

@@ -0,0 +1,190 @@
+// THE TIME SECTION'S ARITHMETIC, WITH NO REACT AND NO DOCUMENT WRITE IN IT.
+//
+// Everything here is a pure function over facts the caller already has, for the
+// reason `panels/timeline/model.ts` exists one lane over: a number the panel
+// derives inline is a number no test can reach, and this lane has paid for that
+// before — a strip that drew a hold one frame off merely looked fine.
+//
+// ── WHAT IS DELIBERATELY NOT HERE ───────────────────────────────────────
+//
+// The clip arithmetic itself. `videoClipOf` (shot/media.ts) is THE seam for
+// `(f - offsetFrames) * timeScale` and its header refuses a second copy by
+// name, so this file consumes a `VideoClipInfo` and never rebuilds one. The
+// EDITS are not here either: `trimLayer`, `slipLayer`, `retimeVideo` and
+// `setVideoSource` already own the clamps, the refusals and the fade repair,
+// and `writeLifespan` (panels/timeline/model.ts) already routes a video edge
+// through them and a plain layer's edge around them. A second spelling of any
+// of that would be the drift those files were written to stop.
+//
+// What is left is the three questions a PANEL asks that nothing else does:
+// which edge actually ends this clip, where `out` would have to be for the
+// recording to play through once, and what a linear gain reads as in dB.
+import { MAX_AUDIO_GAIN, gainToDb } from "@dailies-studio/shot/doc";
+import type { VideoClipInfo } from "@dailies-studio/shot/doc";
+import type { Rational } from "@dailies-studio/engine";
+import { timecode } from "../timeline/model.js";
+
+/**
+ * WHICH EDGE ACTUALLY ENDS THE CLIP.
+ *
+ * Three different things can stop a recording being on screen and an author
+ * looking at a bar cannot tell them apart:
+ *
+ *   `out`     the clip's own window end, which is the one they authored;
+ *   `source`  the footage running out (or, played backwards, reaching its own
+ *             start) somewhere INSIDE that window, after which every remaining
+ *             frame is the same frozen picture;
+ *   `shot`    the shot ending first, which cuts the window off wherever it is.
+ *
+ * The three are ranked by WHICH HAPPENS FIRST, because that is the one that
+ * decides what the viewer sees. A frozen tail is the expensive one to miss: the
+ * bar is full width, the export is the right length, and the last second of it
+ * is a still nobody noticed.
+ */
+export type ClipCloseKind = "out" | "source" | "shot";
+
+export interface ClipClose {
+  kind: ClipCloseKind;
+  /** SCENE-LOCAL frame where it happens. For `source` this is the crossing,
+   *  which is where the picture stops changing, not where the bar stops. */
+  frame: number;
+}
+
+/**
+ * `timeScale` is passed rather than read off the clip, because `VideoClipInfo`
+ * deliberately does not carry it: the sign is what decides WHICH of the two
+ * crossings the seam reports is the tail one, and `videoClipOf`'s header says
+ * so ("a consumer that shades 'frozen from here' reads the sign of
+ * `timeScale`"). Asking the caller for the field it already read is cheaper
+ * than widening the seam's return for one consumer.
+ *
+ * THE CROSSING MAY LIE OUTSIDE THE WINDOW, which the seam also states, and both
+ * ends of that matter here:
+ *
+ *   at or before `in`  the WHOLE clip is one frozen picture. Nothing closes at
+ *     the tail, so the tail is still the window's own end or the shot's — the
+ *     caption must not claim an edge the viewer never reaches.
+ *   at or after `out`  the seam already answers null, so there is nothing to
+ *     rank: the window ends before the footage does.
+ */
+export function closingEdge(
+  clip: VideoClipInfo,
+  sceneDurationFrames: number,
+  timeScale: number,
+): ClipClose {
+  const shotEnd = Math.max(0, Math.trunc(sceneDurationFrames));
+  // Played backwards the source counts DOWN, so the frozen end is the t=0
+  // crossing (`leadFrom`) and not the run-out one. A zero or non-finite rate
+  // cannot reach the document (validate refuses it) and reads as forward here
+  // rather than as a fourth case.
+  const freeze = timeScale < 0 ? clip.leadFrom : clip.holdFrom;
+  const windowEnd = Math.min(clip.out, shotEnd);
+  if (freeze !== null && freeze > clip.in && freeze < windowEnd) {
+    return { kind: "source", frame: freeze };
+  }
+  // AT EQUALITY THE SHOT WINS. A window that ends exactly on the shot's last
+  // frame is bounded by the shot whatever the author typed, and a layer with no
+  // `lifetime` at all lands here by construction: its out IS the shot's end.
+  return clip.out >= shotEnd ? { kind: "shot", frame: shotEnd } : { kind: "out", frame: clip.out };
+}
+
+/**
+ * The caption, as ONE line of prose.
+ *
+ * Separate from the ranking above so the decision is testable without matching
+ * on a sentence, and so the sentence can be read for its own sake: it is the
+ * only place in the rail that names a frozen tail, and an author who cannot
+ * tell a hold from a still has no other way to find out.
+ */
+export function closingCaption(close: ClipClose, fps: Rational, timeScale: number): string {
+  const at = `frame ${formatFrame(close.frame)} (${timecode(close.frame, fps)})`;
+  if (close.kind === "shot") return `Ends with the shot, at ${at}.`;
+  if (close.kind === "out") return `Ends on its own out, at ${at}.`;
+  return timeScale < 0
+    ? `Ends on the recording: it reaches its own start at ${at}, and the first frame holds to the out.`
+    : `Ends on the recording: it runs out at ${at}, and the last frame holds to the out.`;
+}
+
+/** A crossing is a BOUNDARY and may be fractional when the rate is
+ *  (`videoClipOf` refuses to round it, because an op wants the true number).
+ *  A caption is prose, so it shows at most one decimal and never `12.0000001`. */
+function formatFrame(frame: number): string {
+  if (!Number.isFinite(frame)) return "?";
+  return Number.isInteger(frame) ? String(frame) : frame.toFixed(1);
+}
+
+/**
+ * WHERE `out` WOULD HAVE TO BE for the window to play the recording through
+ * once from where it currently starts, or null when there is no such frame.
+ *
+ * Null covers three real states and they are not errors:
+ *   nobody has probed the asset, so its length is unknown (`sourceDurationFrames`
+ *     is null, which the seam's own doc says is "unknown", never "empty");
+ *   the rate is not usable (a document that never passed the save gate);
+ *   the answer lands at or before `in`, which is a clip whose footage is already
+ *     behind it — there is no natural length left to ask for.
+ *
+ * PLAYED BACKWARDS the recording ends when its own t=0 arrives, which is
+ * `offsetFrames` itself, so the forward `duration / rate` term does not apply.
+ * Both are the same statement — "run until the source clamps" — read through
+ * the sign.
+ *
+ * ROUNDED, because a lifetime is integer. The caller hands the result to
+ * `writeLifespan`, so the footage clamp and the scene clamp are applied by
+ * `trimLayer`, once, where they already live.
+ */
+export function naturalOutFrame(
+  clip: VideoClipInfo,
+  offsetFrames: number,
+  timeScale: number,
+): number | null {
+  const duration = clip.sourceDurationFrames;
+  if (duration === null || !Number.isFinite(timeScale) || timeScale === 0) return null;
+  if (!Number.isFinite(offsetFrames)) return null;
+  const end = timeScale > 0 ? offsetFrames + duration / timeScale : offsetFrames;
+  if (!Number.isFinite(end)) return null;
+  const at = Math.round(end);
+  return at > clip.in ? at : null;
+}
+
+/**
+ * Linear gain as dB, and back.
+ *
+ * `gainToDb` is the document plane's (audioLoudness.ts) and is imported rather
+ * than restated, because the loudness lane compares its answer against stored
+ * targets — two spellings of one conversion would make a level match by half a
+ * decibel and nothing would say which half.
+ *
+ * The inverse is not there because nothing in the data plane needed it: dB is
+ * how a MIXER FACE is labelled, and the document stores the linear number the
+ * engine multiplies by. So it lives here, next to the face that needs it, and
+ * the round trip is pinned by this file's test.
+ *
+ * SILENCE IS THE FLOOR, not minus infinity. `gainToDb(0)` answers -120 by
+ * contract, and anything at or below that reads back as a true 0 rather than
+ * as 1e-6: a muted-by-level clip must be able to come back.
+ */
+export const MIN_GAIN_DB = -120;
+
+export function dbToGain(db: number): number {
+  if (!Number.isFinite(db) || db <= MIN_GAIN_DB) return 0;
+  return Math.pow(10, db / 20);
+}
+
+/** The dB a field SHOWS for a stored gain: one decimal, which is the finest
+ *  step a level fader is read at, and the floor rather than -Infinity. */
+export function gainAsDb(gain: number): number {
+  const db = gainToDb(Number.isFinite(gain) ? gain : 1);
+  return Math.round(Math.max(MIN_GAIN_DB, db) * 10) / 10;
+}
+
+/**
+ * The mixer's ceiling, in dB, and it is NOT `gainAsDb(MAX_AUDIO_GAIN)`.
+ *
+ * EXACT, deliberately. A level field's hard `max` is what every commit path
+ * clamps to, so rounding it to the one decimal the field DISPLAYS would put the
+ * ceiling at 6.0 dB — a gain of 1.9953 — and the top of the fader would be a
+ * number the author can see (2) and never reach. The display rounds; the limit
+ * does not.
+ */
+export const MAX_GAIN_DB = gainToDb(MAX_AUDIO_GAIN);