@ossclip/scenes 0.1.34 → 0.1.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/scenes",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "ossclip's scene library and stage geometry — React components shared by preview and render",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "zod": "^3.25.0",
-    "@ossclip/core": "0.1.34"
+    "@ossclip/core": "0.1.36"
   },
   "peerDependencies": {
     "react": ">=18",

package/src/EdlVideo.tsx

@@ -1,7 +1,7 @@
 import React, { useMemo } from "react";
 import { AbsoluteFill, OffthreadVideo, Sequence, useVideoConfig } from "remotion";
 import type { KeptSpan } from "@ossclip/core/browser";
-import { frameWindow } from "./frames";
+import { frameWindow, playableSpans } from "./frames";
 import { punchScalesFor, type PunchPlan } from "./punch-plan";
 
 export interface EdlVideoProps {
@@ -30,6 +30,11 @@ export interface EdlVideoProps {
    * and lets the backdrop through.
    */
   background?: string;
+  /**
+   * Per-window user gain (cue `video.volume`), output clock. Empty/absent =
+   * unity everywhere — the pre-feature tree, byte for byte.
+   */
+  gain?: readonly GainSegment[];
 }
 
 /**
@@ -37,17 +42,43 @@ export interface EdlVideoProps {
  * Jump cuts are concealed by alternating a slight punch-in whenever the
  * removed gap is long enough to produce a visible jump.
  */
+/** One window of user audio gain on the OUTPUT clock (cue windows). */
+export interface GainSegment {
+  startSec: number;
+  endSec: number;
+  gain: number;
+}
+
+/**
+ * The user gain at one output second — 1 outside every segment. Last match
+ * wins, mirroring how later cues paint over earlier ones; windows come from
+ * cues, which tile rather than overlap, so the rule is a tiebreak, not a
+ * feature.
+ */
+export function gainAtSec(segments: readonly GainSegment[], sec: number): number {
+  let g = 1;
+  for (const s of segments) if (sec >= s.startSec && sec < s.endSec) g = s.gain;
+  return g;
+}
+
 export const EdlVideo: React.FC<EdlVideoProps> = ({
   src,
-  spans,
+  spans: rawSpans,
   punchInScale = 1.07,
   punch = null,
   punchThresholdSec = 0.15,
   audioFadeSec = 0.01,
   background = "black",
+  gain = [],
 }) => {
   const { fps } = useVideoConfig();
 
+  // A span whose source window rounds to zero frames would mount
+  // <OffthreadVideo trimBefore={n} trimAfter={n}> — a Remotion validation
+  // THROW that blanks the whole Player (the 2026-08-31 ADK crash). Filtered
+  // here, not just at the writers, so docs saved by older versions render.
+  const spans = useMemo(() => playableSpans(rawSpans, fps), [rawSpans, fps]);
+
   // Extracted to punch-plan.ts so the mask/parity interaction is testable
   // without mounting a composition; the loop there is the reference
   // implementation the Premiere export mirrors.
@@ -65,13 +96,24 @@ export const EdlVideo: React.FC<EdlVideoProps> = ({
         // duration that is one frame long also skews the fade ramp below,
         // which measures against `durationInFrames`.
         const { from, durationInFrames } = frameWindow(sp.outIn, sp.outOut, fps);
+        // premountFor 3s, up from 1s (field report 2026-08-31): each span is
+        // its own <video> seeking a large mezzanine, and one second of
+        // premount was not always enough — entering the next span played
+        // black/silent until a scrub-back forced a reload. Three seconds
+        // costs at most one extra warm element and covers a cold seek.
         return (
-          <Sequence key={i} from={from} durationInFrames={durationInFrames} premountFor={fps}>
+          <Sequence key={i} from={from} durationInFrames={durationInFrames} premountFor={fps * 3}>
             <AbsoluteFill style={{ transform: `scale(${scales[i]})` }}>
               <OffthreadVideo
                 src={src}
                 trimBefore={Math.round(sp.srcIn * fps)}
                 trimAfter={Math.round(sp.srcOut * fps)}
+                // A span whose media is STILL not ready pauses the player
+                // instead of playing on silently over a black frame — the
+                // stall is visible and recovers by itself, where the silent
+                // variant looked broken until the user scrubbed (same field
+                // report).
+                pauseWhenBuffering
                 style={{
                   width: "100%",
                   height: "100%",
@@ -80,12 +122,25 @@ export const EdlVideo: React.FC<EdlVideoProps> = ({
                   // for a portrait source, horizontal for a landscape one.
                   objectPosition: "var(--ossclip-obj-x, 50%) var(--ossclip-obj-y, 50%)",
                 }}
-                volume={(f) =>
-                  Math.max(
+                volume={(f) => {
+                  const fade = Math.max(
                     0,
                     Math.min(1, (f + 1) / fadeFrames, (durationInFrames - f) / fadeFrames),
-                  )
-                }
+                  );
+                  // User gain composes ON the fade. Boosts above 1 land in
+                  // the render via allowAmplificationDuringRender below, and
+                  // in the Player via its WebAudio gain node — which is OFF
+                  // by default: without useWebAudioApi the preview path is
+                  // literally `element.volume = Math.min(volume, 1)`
+                  // (remotion/use-amplification, shouldUseTraditionalVolume),
+                  // so a 200% take sounded identical to 100% (field report
+                  // 2026-08-31). Enabled only when a boost exists — the
+                  // routed-through-AudioContext path is the exception, not
+                  // the default audio graph.
+                  return fade * gainAtSec(gain, (from + f) / fps);
+                }}
+                allowAmplificationDuringRender
+                useWebAudioApi={gain.some((g) => g.gain > 1)}
               />
             </AbsoluteFill>
           </Sequence>

package/src/SfxTrack.tsx

@@ -0,0 +1,50 @@
+import React from "react";
+import { Audio, Sequence, staticFile, useVideoConfig } from "remotion";
+import { visibleSfxCues, type SfxCueProps } from "./sfx-track";
+
+/**
+ * The `--sfx` sound-effect track: one `<Sequence>` per cue, each mounting an
+ * `<Audio>` at its own instant.
+ *
+ * MIXED INSIDE REMOTION ON PURPOSE, and this is the whole reason the feature
+ * is cheap: the render's audio goes through loudnorm afterwards (core's
+ * ingest.ts), so a mix done here is MEASURED as part of the programme — the
+ * effects sit at a level normalized against the speech instead of being
+ * stamped on after the loudness pass, which is what a post-render ffmpeg
+ * overlay would have meant (and would have needed its own gain staging to
+ * avoid clipping the take it lands on).
+ *
+ * No duration on the Sequences: an effect plays for its own length. That is
+ * also why cues can overlap the composition's own end — Remotion truncates the
+ * tail at the last frame, and a whoosh clipped by the end of the video is the
+ * same thing an editor would do by hand.
+ *
+ * Deliberately invisible to the editor, the Watermark/CoverInVideo rule: no
+ * `data-edit-id`, nothing to hit-test, nothing rendered at all. Placement
+ * editing arrives through the overrides doc, not through the stage.
+ */
+export const SfxTrack: React.FC<{ cues: readonly SfxCueProps[] }> = ({ cues }) => {
+  const { fps, durationInFrames } = useVideoConfig();
+  return (
+    <>
+      {visibleSfxCues(cues, fps, durationInFrames).map((cue, i) => (
+        <Sequence
+          // Index in the VISIBLE list plus the frame: two effects can share a
+          // frame (different sounds, same beat), so neither alone is a stable
+          // key, and React would remount one of them on any list change.
+          key={`${cue.from}-${i}`}
+          from={cue.from}
+          layout="none"
+        >
+          <Audio
+            // An http(s) URL (or the editor's `/media/…`) passes through
+            // untouched, everything else is a name in the render's public dir
+            // — CoverInVideo's exact rule.
+            src={/^https?:\/\//.test(cue.soundFile) ? cue.soundFile : staticFile(cue.soundFile)}
+            volume={cue.gain}
+          />
+        </Sequence>
+      ))}
+    </>
+  );
+};

package/src/VideoStage.tsx

@@ -17,6 +17,7 @@ import {
   type SourceFit,
   type SpanLike,
 } from "./content-crop";
+import { colorGradeFilterId, stageFilterFor, type ColorGradeProps } from "./color-grade";
 
 /**
  * The stage (PHASE1 §1): a solid backdrop that fades in when a scene demotes
@@ -68,6 +69,13 @@ export const VideoStage: React.FC<{
    * without it there is nothing to fit and this falls back to cover.
    */
   sourceFit?: SourceFit;
+  /**
+   * The `--grade` SVG filter spec, already parsed by the composition
+   * (`colorGradePropsFor` — parse, never coerce). Absent/null means no grade
+   * and ZERO new DOM: no `<svg>`, no `url()` in the filter list, so a
+   * grade-less render builds the exact tree it always did.
+   */
+  colorGrade?: ColorGradeProps | null;
   children: React.ReactNode;
 }> = ({
   cues,
@@ -81,6 +89,7 @@ export const VideoStage: React.FC<{
   sourceSize,
   contentCropMode = "cover",
   sourceFit = "cover",
+  colorGrade,
   children,
 }) => {
   const frame = useCurrentFrame();
@@ -131,8 +140,33 @@ export const VideoStage: React.FC<{
   // consumed by it (see contentTransformFor's contract).
   const contentTransform = contentTransformFor(zoom, userScale, userDx, userDy);
 
+  // Value-derived id (see colorGradeFilterId): two stages in one document can
+  // only collide when their grades are identical, which makes the collision
+  // a no-op instead of one stage silently wearing the other's grade.
+  const gradeId = colorGrade ? colorGradeFilterId(colorGrade) : null;
+
   return (
     <AbsoluteFill>
+      {colorGrade ? (
+        // Zero-sized and absolute: the element exists only to define the
+        // filter the slot's `filter: url(#…)` references; it must never take
+        // layout space in the stage.
+        <svg width={0} height={0} style={{ position: "absolute" }} aria-hidden>
+          {/* colorInterpolationFilters="sRGB" is LOAD-BEARING: the SVG spec
+              defaults filter math to linearRGB, but core sampled the transfer
+              tables and built the matrix in sRGB (gamma) space — without the
+              override the browser un-gammas the pixels first and the whole
+              grade shifts brighter/washed. */}
+          <filter id={gradeId!} colorInterpolationFilters="sRGB">
+            <feComponentTransfer>
+              <feFuncR type="table" tableValues={colorGrade.tableR.join(" ")} />
+              <feFuncG type="table" tableValues={colorGrade.tableG.join(" ")} />
+              <feFuncB type="table" tableValues={colorGrade.tableB.join(" ")} />
+            </feComponentTransfer>
+            <feColorMatrix type="matrix" values={colorGrade.colorMatrix.join(" ")} />
+          </filter>
+        </svg>
+      ) : null}
       <AbsoluteFill style={{ background: theme.bg, opacity: backdrop }} />
       <div
         // Which scene's framing a grab on the picture edits (PLAN 2026-07-30
@@ -163,7 +197,9 @@ export const VideoStage: React.FC<{
           style={{
             position: "absolute",
             inset: 0,
-            filter: slot.blurPx > 0.5 ? `blur(${slot.blurPx}px)` : undefined,
+            // Grade before blur (stageFilterFor has the ordering argument);
+            // without a grade this is the exact blur string it always was.
+            filter: stageFilterFor(gradeId, slot.blurPx),
             transform: contentTransform,
             // Zoom toward the face, which the crop bias keeps in the upper part.
             transformOrigin: "50% 40%",

package/src/color-grade.ts

@@ -0,0 +1,82 @@
+import { z } from "zod/v4";
+
+/**
+ * The `--grade` color pipeline's render half (core's color-grade.ts owns the
+ * math: `gradeToSvgFilterSpec` decomposes the grade into per-channel transfer
+ * tables plus one 5x4 color matrix). This module is the props gate, the
+ * filter id and the CSS `filter:` composition — everything about the SVG
+ * filter that is assertable without a DOM.
+ *
+ * Pure and JSX-free (house rule, `sfx-track.ts`'s posture): the component
+ * just serializes these values into `<feFuncR tableValues>` and friends.
+ */
+
+/**
+ * The precomputed spec, verbatim from `gradeToSvgFilterSpec`: 0..1 transfer
+ * table samples per channel, and a row-major 5x4 feColorMatrix. Zod (parse,
+ * never coerce, CLAUDE.md) rather than the neighbours' hand-rolled checks
+ * because the shape is four numeric arrays — exactly what a schema states
+ * more legibly than a loop. zod/v4's `z.number()` already refuses NaN and
+ * ±Infinity, which is the whole finiteness story a hand parser would need.
+ */
+const colorGradeSchema = z.object({
+  tableR: z.array(z.number()),
+  tableG: z.array(z.number()),
+  tableB: z.array(z.number()),
+  // 20 exactly: feColorMatrix silently renders NOTHING (transparent output)
+  // on a malformed `values` list, which reads as "the video vanished", not
+  // "the grade is off" — so a truncated matrix must fail here instead.
+  colorMatrix: z.array(z.number()).length(20),
+});
+
+export type ColorGradeProps = z.infer<typeof colorGradeSchema>;
+
+/**
+ * Whether a render-props `colorGrade` field is a spec this renderer will
+ * mount — `punchPropsFor`'s posture: render-props.json is user-visible and
+ * hand-editable, every pre-feature file has no key at all, and a mangled
+ * spec must fall back to NO grade (zero new DOM) rather than an feColorMatrix
+ * that blanks the picture or tables full of `undefined`.
+ */
+export function colorGradePropsFor(value: unknown): ColorGradeProps | null {
+  const parsed = colorGradeSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * A DOM id for the filter, derived from the VALUES (FNV-1a over the sample
+ * list) rather than from a counter or a random suffix: SVG filter ids are
+ * document-global, and if two stages ever share a document (editor preview
+ * next to a thumbnail), a value-derived id makes collision harmless — equal
+ * ids mean equal filter definitions, so whichever `<filter>` wins the lookup
+ * applies the same grade. A counter would make the collision silently apply
+ * one stage's grade to the other.
+ */
+export function colorGradeFilterId(spec: ColorGradeProps): string {
+  const values = [...spec.tableR, ...spec.tableG, ...spec.tableB, ...spec.colorMatrix];
+  let hash = 0x811c9dc5;
+  for (const v of values) {
+    const s = String(v);
+    for (let i = 0; i < s.length; i++) {
+      hash ^= s.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193);
+    }
+  }
+  return `ossclip-grade-${(hash >>> 0).toString(16)}`;
+}
+
+/**
+ * The video slot's composed `filter:` value. One CSS filter list takes both
+ * an SVG `url()` reference and CSS filter functions; the grade goes FIRST so
+ * the blur softens the graded picture — blurring first would average raw
+ * pixels and then re-map the averages, visibly haloing hard edges. The 0.5px
+ * blur floor predates the grade (VideoStage has always skipped sub-pixel
+ * blurs) and is kept so a grade-less render emits the exact string it always
+ * did.
+ */
+export function stageFilterFor(gradeId: string | null, blurPx: number): string | undefined {
+  const parts: string[] = [];
+  if (gradeId) parts.push(`url(#${gradeId})`);
+  if (blurPx > 0.5) parts.push(`blur(${blurPx}px)`);
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}

package/src/frames.ts

@@ -28,3 +28,19 @@ export function frameWindow(
   const to = Math.round(endSec * fps);
   return { from, durationInFrames: Math.max(1, to - from) };
 }
+
+/**
+ * Drop spans whose SOURCE window rounds to zero frames at this fps. Such a
+ * span cannot be played — `<OffthreadVideo trimBefore={n} trimAfter={n}>` is
+ * a Remotion validation THROW, and inside the Player that error boundary
+ * blanks the entire preview and stops playback (the 2026-08-31 ADK crash:
+ * a 3-decimal-rounded user cut left a 125µs keep sliver). recut.ts absorbs
+ * new slivers at the source; this filter is the defense-in-depth for docs
+ * older versions already saved.
+ */
+export function playableSpans<T extends { srcIn: number; srcOut: number }>(
+  spans: readonly T[],
+  fps: number,
+): T[] {
+  return spans.filter((sp) => Math.round(sp.srcOut * fps) > Math.round(sp.srcIn * fps));
+}

package/src/index.ts

@@ -4,8 +4,11 @@ export { VideoStage } from "./VideoStage";
 export { SceneLayer } from "./SceneLayer";
 export { Watermark } from "./Watermark";
 export { CoverInVideo } from "./CoverInVideo";
+export { SfxTrack } from "./SfxTrack";
 export * from "./stage";
 export * from "./watermark-layout";
 export * from "./cover-in-video";
+export * from "./sfx-track";
 export * from "./punch-plan";
+export * from "./color-grade";
 export * from "./caption-visibility";

package/src/sfx-track.ts

@@ -0,0 +1,80 @@
+/**
+ * The `--sfx` sound track's props and frame math (core's `resolveSfxCues`
+ * owns the word→output-time half and the gain product).
+ *
+ * Pure and JSX-free, `cover-in-video.ts`'s posture: the props gate, the frame
+ * rounding and the volume clamp are the whole behavior, and this package
+ * carries no jsdom — none of it would be assertable inside the component.
+ */
+
+/** One effect: a staged file, an OUTPUT-time instant, a mix level. */
+export interface SfxCueProps {
+  /** File under the render's public dir — `sfx/<id>.<ext>` (or a `/media/…` URL). */
+  soundFile: string;
+  atSec: number;
+  gain: number;
+}
+
+/**
+ * The loudest a cue may play. `HTMLMediaElement.volume` THROWS an
+ * IndexSizeError above 1, so an un-clamped gain would take the editor's
+ * preview down entirely — while the render, which mixes the samples itself,
+ * would happily amplify. Preview and render must agree, so both get the clamp
+ * and the ceiling is 1.
+ */
+export const SFX_MAX_VOLUME = 1;
+
+/**
+ * Whether a render-props `sfxCues` entry is a cue this renderer will mount —
+ * `coverInVideoPropsFor`'s posture (parse, never coerce, CLAUDE.md):
+ * render-props.json is user-visible and hand-editable, every pre-feature file
+ * has no key at all, and a mangled entry must fall back to SILENCE rather than
+ * mount an `undefined` src or a NaN-frame Sequence over the take.
+ *
+ * Per ENTRY, not all-or-nothing: one bad cue costs that cue, the drop-bad-item
+ * rule the whole SFX path is built on.
+ */
+export function sfxCuesFor(value: unknown): SfxCueProps[] {
+  if (!Array.isArray(value)) return [];
+  const cues: SfxCueProps[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const v = entry as { soundFile?: unknown; atSec?: unknown; gain?: unknown };
+    if (typeof v.soundFile !== "string" || v.soundFile.length === 0) continue;
+    if (typeof v.atSec !== "number" || !Number.isFinite(v.atSec) || v.atSec < 0) continue;
+    // An absent gain is 1 (play it as recorded); a mangled one is refused
+    // rather than defaulted, because a wrong LEVEL is audible and silent
+    // about being wrong.
+    if (v.gain !== undefined && (typeof v.gain !== "number" || !Number.isFinite(v.gain))) continue;
+    cues.push({
+      soundFile: v.soundFile,
+      atSec: v.atSec,
+      gain: Math.min(SFX_MAX_VOLUME, Math.max(0, v.gain ?? 1)),
+    });
+  }
+  return cues;
+}
+
+/**
+ * The cues that actually have a frame to fire on, with that frame.
+ *
+ * `Math.round`, matching `frameWindow`'s start (FINDINGS §115) — an effect is
+ * an instant, so there is no end time whose independent rounding could collide
+ * with it. A cue at or past the composition's last frame is DROPPED rather
+ * than clamped to it: a whoosh planned for a moment the render no longer
+ * reaches must not pile onto the final frame with everything else that fell
+ * off the end.
+ */
+export function visibleSfxCues(
+  cues: readonly SfxCueProps[],
+  fps: number,
+  durationInFrames: number,
+): Array<SfxCueProps & { from: number }> {
+  const out: Array<SfxCueProps & { from: number }> = [];
+  for (const cue of cues) {
+    const from = Math.round(cue.atSec * fps);
+    if (from < 0 || from >= durationInFrames) continue;
+    out.push({ ...cue, from });
+  }
+  return out;
+}