@ossclip/core 0.1.33 → 0.1.35

package/assets/sfx/ATTRIBUTION.md

@@ -0,0 +1,29 @@
+# Starter SFX pack — sources and licenses
+
+Every file is license-clean for redistribution inside this repo and in
+published, monetized videos.
+
+## Kenney "Interface Sounds" — CC0 (public domain)
+
+Source: https://kenney.nl/assets/interface-sounds (zip:
+`kenney_interface-sounds.zip`, downloaded 2026-08-29). License: Creative
+Commons CC0. Transcoded to mono mp3 128k with ffmpeg.
+
+| file | original |
+|---|---|
+| ding.mp3 | Audio/confirmation_001.ogg |
+| pop.mp3 | Audio/drop_002.ogg |
+| click.mp3 | Audio/click_002.ogg |
+| error-buzz.mp3 | Audio/error_004.ogg |
+| scratch.mp3 | Audio/scratch_003.ogg |
+
+## Synthesized in-repo — CC0
+
+`whoosh-soft`, `whoosh-fast`, `swoosh-exit`, `riser-short`, `boom-dramatic`
+and `tape-stop` are generated from pure ffmpeg expressions by
+`synthesize.sh` in this directory (no third-party samples involved) and are
+dedicated to the public domain under CC0. Rerun the script to regenerate.
+
+The originally-planned "vine-boom"/"bruh" style voice memes are deliberately
+NOT bundled — no CC0 source exists for them. Users who want them drop their
+own files into `~/.ossclip/sfx/<pack>/` with a `pack.json`.

package/assets/sfx/pack.json

@@ -0,0 +1,16 @@
+{
+  "name": "ossclip-starter",
+  "sounds": [
+    { "id": "whoosh-soft", "kind": "sound", "file": "whoosh-soft.mp3", "whenToUse": "A graphic or scene sliding in; gentle transitions between points.", "tags": [], "gain": 0.9, "durationSec": 0.7 },
+    { "id": "whoosh-fast", "kind": "sound", "file": "whoosh-fast.mp3", "whenToUse": "Quick cuts, list items landing, fast pace moments.", "tags": [], "gain": 0.9, "durationSec": 0.35 },
+    { "id": "swoosh-exit", "kind": "sound", "file": "swoosh-exit.mp3", "whenToUse": "Something being dismissed, deleted, or leaving the frame.", "tags": [], "gain": 0.9, "durationSec": 0.6 },
+    { "id": "riser-short", "kind": "sound", "file": "riser-short.mp3", "whenToUse": "Build-up right before a reveal, result, or big claim.", "tags": [], "gain": 0.8, "durationSec": 1.1 },
+    { "id": "ding", "kind": "sound", "file": "ding.mp3", "whenToUse": "Confirmation that something works; a key takeaway landing.", "tags": [], "gain": 1, "durationSec": 0.6 },
+    { "id": "pop", "kind": "sound", "file": "pop.mp3", "whenToUse": "A small element appearing; a light touch on a minor point.", "tags": [], "gain": 1, "durationSec": 0.3 },
+    { "id": "click", "kind": "sound", "file": "click.mp3", "whenToUse": "Describing a UI interaction: clicking, selecting, toggling.", "tags": [], "gain": 1, "durationSec": 0.2 },
+    { "id": "error-buzz", "kind": "sound", "file": "error-buzz.mp3", "whenToUse": "Something failing, a wrong approach, a bug being shown.", "tags": [], "gain": 0.9, "durationSec": 0.5 },
+    { "id": "scratch", "kind": "sound", "file": "scratch.mp3", "whenToUse": "A record-scratch 'wait, what?' pivot or sudden correction.", "tags": ["meme"], "gain": 1, "durationSec": 0.4 },
+    { "id": "boom-dramatic", "kind": "sound", "file": "boom-dramatic.mp3", "whenToUse": "Dramatic emphasis on an absurd or shocking statement.", "tags": ["meme"], "gain": 0.85, "durationSec": 1.6 },
+    { "id": "tape-stop", "kind": "sound", "file": "tape-stop.mp3", "whenToUse": "Everything stopping for an interjection or hard pivot.", "tags": ["meme"], "gain": 0.85, "durationSec": 1.1 }
+  ]
+}

package/assets/sfx/synthesize.sh

@@ -0,0 +1,19 @@
+#!/bin/sh
+# Synthesizes the non-Kenney starter sounds from pure ffmpeg expressions, so
+# the bundled pack carries zero third-party license risk beyond Kenney's CC0.
+# Re-run to regenerate byte-similar (encoder-dependent) sources: sh synthesize.sh <outdir>
+set -e
+OUT="${1:-.}"
+FF="${FFMPEG:-ffmpeg}"
+# whoosh-soft: pink noise through a fading band sweep
+$FF -y -f lavfi -i "anoisesrc=color=pink:duration=0.7:seed=7" -af "highpass=f=300,lowpass=f=2400,afade=t=in:d=0.15,afade=t=out:st=0.35:d=0.35,volume=1.4" "$OUT/whoosh-soft.wav"
+# whoosh-fast: brighter, shorter
+$FF -y -f lavfi -i "anoisesrc=color=white:duration=0.35:seed=11" -af "highpass=f=800,lowpass=f=5000,afade=t=in:d=0.05,afade=t=out:st=0.15:d=0.2,volume=1.2" "$OUT/whoosh-fast.wav"
+# swoosh-exit: whoosh-soft reversed
+$FF -y -f lavfi -i "anoisesrc=color=pink:duration=0.6:seed=13" -af "highpass=f=300,lowpass=f=2400,afade=t=in:d=0.1,afade=t=out:st=0.3:d=0.3,areverse,volume=1.3" "$OUT/swoosh-exit.wav"
+# riser-short: quadratic pitch ramp + swelling noise
+$FF -y -f lavfi -i "aevalsrc='0.35*sin(2*PI*(180+520*t*t)*t)*min(1,2.5*t)':d=1.1" -f lavfi -i "anoisesrc=color=pink:duration=1.1:seed=17" -filter_complex "[1]volume='0.25*t':eval=frame,highpass=f=600[n];[0][n]amix=inputs=2:duration=first,afade=t=out:st=0.95:d=0.15" "$OUT/riser-short.wav"
+# boom-dramatic: sub sine thump with harmonic and long decay (the vine-boom register)
+$FF -y -f lavfi -i "aevalsrc='0.95*sin(2*PI*55*t)*exp(-2.5*t)+0.3*sin(2*PI*110*t)*exp(-4*t)':d=1.6" -af "alimiter=limit=0.9" "$OUT/boom-dramatic.wav"
+# tape-stop: 440->0 pitch slide via falling-rate expression
+$FF -y -f lavfi -i "aevalsrc='0.5*sin(2*PI*330*(t-2.2*t*t/2/1.1))*(1-t/1.1)':d=1.1" -af "lowpass=f=3000" "$OUT/tape-stop.wav"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/assemble.ts

@@ -1,6 +1,8 @@
 import type { Transcript } from "./schema";
 import type { Scene, SceneCue } from "./scene-schema";
 import { resolveSceneProps } from "./scene-registry";
+import type { LoadedSfxSound } from "./sfx-pack";
+import type { SfxPlacement, SfxValidationIssue } from "./producer/sfx";
 import type { TimeMap } from "./timemap";
 
 /** Scenes shorter than this on screen get extended; still shorter → dropped. */
@@ -121,3 +123,199 @@ export function assembleScenes(
 
   return { cues, dropped };
 }
+
+/**
+ * One sound effect, ready for the renderer: a staged file, an OUTPUT-time
+ * instant, and the mix level it plays at. No word index survives — by this
+ * point the anchor has done its job (timemap.ts:13's "all overlay timings live
+ * in OUTPUT time").
+ */
+export interface SfxCue {
+  /** Path under the render's public dir — `sfx/<id>.<ext>`, POSIX-literal. */
+  soundFile: string;
+  atSec: number;
+  /** The sound's own gain times the placement's, resolved once here. */
+  gain: number;
+}
+
+/** Where staged sounds live inside the render's public dir. */
+export const SFX_PUBLIC_SUBDIR = "sfx";
+
+/**
+ * The staged name for a sound, keyed on its ID rather than its own filename:
+ * two packs may both ship a `whoosh.mp3`, and the id is what the plan actually
+ * references (ids are unique by construction — `loadSfxLibrary` merges by id).
+ *
+ * POSIX-literal `/`, never `join()` — this is a URL `staticFile()` resolves,
+ * not a filesystem path, and a Windows `\` here would be served verbatim
+ * (produce.ts's `sideImageDestRel` lesson). The extension is taken with a
+ * regex rather than `extname` to keep this module free of node built-ins.
+ */
+export function sfxStagedFile(sound: { id: string; file: string }): string {
+  const ext = /\.[^./\\]+$/.exec(sound.file)?.[0] ?? "";
+  return `${SFX_PUBLIC_SUBDIR}/${sound.id}${ext}`;
+}
+
+/**
+ * Scene id → the output second that scene STARTS on, the scene-timing context
+ * `resolveSfxCues` places a scene-anchored placement against (2026-08-29).
+ *
+ * Built from the FINAL cue list — after `applyOverrides`, the splits, the
+ * pinned-timing reclamp and the hidden-cue drop — because that is the only
+ * list that knows where the user actually put the graphic. Feeding it the
+ * producer's raw scenes would reintroduce the exact field failure the scene
+ * link exists to fix.
+ *
+ * Keyed on the ROOT id (`splitCues` mints a second half as `<root>@<split
+ * id>`) and keeping the EARLIEST start, because a sound marks an ENTRANCE: a
+ * half the user split off later is the same graphic continuing, not a second
+ * appearance. A hidden scene is absent from the cues and therefore from this
+ * map, which is what makes "scene gone" a fact the resolver can report.
+ *
+ * Pure and cue-shaped rather than `SceneCue`-typed so the EDITOR can build the
+ * same map from the cue list its player is drawing — one implementation, or
+ * the diamond and the render's cue disagree about where scene-3 starts.
+ */
+export function sceneStartSeconds(
+  cues: readonly { id: string; startSec: number }[],
+): Map<string, number> {
+  const starts = new Map<string, number>();
+  for (const c of cues) {
+    const root = c.id.split("@")[0]!;
+    const prev = starts.get(root);
+    if (prev === undefined || c.startSec < prev) starts.set(root, c.startSec);
+  }
+  return starts;
+}
+
+/**
+ * Word-anchored SFX placements → output-timed cues, the `assembleScenes`
+ * contract for a track of instants rather than spans (PHASE1 §5).
+ *
+ * Every drop is reported with the SAME machine-readable `reason` vocabulary
+ * the planning passes use, so `formatSfxAccounting` can count planning drops
+ * and render drops in one line. `placement` is the index in the plan handed
+ * in, which is the plan `production.json` stores — the editor can name the
+ * entry a warning is about.
+ *
+ * `exists` is injected (the `defaultProviderName(env, hasBin)` seam): the
+ * check is a real one — a user who deletes a pack between planning and
+ * re-rendering must get a dropped cue, not a Remotion 404 after the render has
+ * already spent its minutes — but the filesystem stays the CALLER's business,
+ * so the whole matrix is testable without writing mp3s to a tmp dir. The
+ * default assumes present: a caller that cannot see a filesystem has no basis
+ * for dropping anything.
+ *
+ * `sceneStarts` is the other injected seam (`sceneStartSeconds` builds it):
+ * a placement carrying a `sceneId` fires at that scene's FINAL start — the
+ * user's moves and trims already in it — instead of at the word the model
+ * rationalised it against. Defaults to empty, which is honest rather than
+ * silent: with no scene context every scene link reports "scene gone" and
+ * falls back to its word, which is exactly what happens when the scene really
+ * is gone.
+ *
+ * Not every entry in `dropped` is a drop. "scene gone" is an ISSUE — the cue
+ * is still emitted, on the word anchor — and is named in the same list so the
+ * console and report.txt say why the effect moved (`SfxDropReasonSchema` owns
+ * the distinction, and `DROP_REASONS` keeps it out of the casualty count).
+ */
+export function resolveSfxCues(
+  placements: readonly SfxPlacement[],
+  transcript: Transcript,
+  map: TimeMap,
+  sounds: readonly LoadedSfxSound[],
+  opts: {
+    exists?: (absPath: string) => boolean;
+    sceneStarts?: ReadonlyMap<string, number>;
+  } = {},
+): { cues: SfxCue[]; dropped: SfxValidationIssue[] } {
+  const exists = opts.exists ?? (() => true);
+  const sceneStarts = opts.sceneStarts ?? new Map<string, number>();
+  const byId = new Map(sounds.map((s) => [s.id, s]));
+  const cues: SfxCue[] = [];
+  const dropped: SfxValidationIssue[] = [];
+
+  for (let i = 0; i < placements.length; i++) {
+    const p = placements[i]!;
+    // Identity first, then position — `normalizeSfxPlan`'s pass order, so a
+    // placement naming a sound that no longer exists reads as an unknown
+    // sound whether it was dropped at planning or here.
+    const sound = byId.get(p.soundId);
+    if (!sound) {
+      dropped.push({
+        placement: i,
+        reason: "unknown sound",
+        issue: `"${p.soundId}" is not in the sound library any more`,
+      });
+      continue;
+    }
+    if (!exists(sound.absPath)) {
+      dropped.push({
+        placement: i,
+        reason: "missing file",
+        issue: `"${p.soundId}" points at ${sound.absPath}, which is gone`,
+      });
+      continue;
+    }
+    // The SCENE anchor outranks the word (field report, 2026-08-29): a sound
+    // placed "as the TitleCard enters" has to follow the card when the user
+    // moves or trims it, and the map already carries the scene's final start.
+    // The word passes below are SKIPPED when it resolves, deliberately — the
+    // graphic is on screen whether or not the speech that motivated it
+    // survived the cut, so a cut-word drop here would silence an effect that
+    // has a perfectly good instant to fire on.
+    let atSec = p.sceneId === undefined ? undefined : sceneStarts.get(p.sceneId);
+    if (atSec === undefined) {
+      if (p.sceneId !== undefined) {
+        // An ISSUE, not a drop: `word` is required precisely so a placement
+        // outlives the scene it was synced to (deleted, hidden or renumbered
+        // by a re-plan are all normal). Printed so report.txt says why the
+        // whoosh is back on the speech.
+        dropped.push({
+          placement: i,
+          reason: "scene gone",
+          issue: `"${p.soundId}" scene ${p.sceneId} gone — using word anchor`,
+        });
+      }
+      const word = transcript.words[p.word];
+      if (!word) {
+        dropped.push({
+          placement: i,
+          reason: "outside transcript",
+          issue: `word ${p.word} is beyond this transcript (${transcript.words.length} words)`,
+        });
+        continue;
+      }
+      // The cut check, `assembleScenes`' rule for a single anchor: a scene whose
+      // words were cut is dropped rather than slid to the nearest kept instant,
+      // and an effect is even less forgiving — it would fire over speech that
+      // never motivated it.
+      const mapped = map.mapWord(word);
+      if (mapped === null) {
+        dropped.push({
+          placement: i,
+          reason: "cut word",
+          issue: `"${p.soundId}" was anchored to word ${p.word} ("${word.text}"), which this cut removed`,
+        });
+        continue;
+      }
+      // The word's START: the effect fires as the word lands, which is what
+      // the model was asked to place ("the effect fires at that word").
+      atSec = mapped.start;
+    }
+    cues.push({
+      soundFile: sfxStagedFile(sound),
+      atSec,
+      // ONE multiplication, here — the renderer receives a number and does no
+      // mixing arithmetic of its own, so what the editor shows as a gain and
+      // what the render plays can never disagree.
+      gain: sound.gain * (p.gain ?? 1),
+    });
+  }
+
+  // Sorted by time: the plan is already word-sorted, but a cut can only ever
+  // preserve order, and a track the renderer walks in time order is one a
+  // human reading render-props.json can check against the video.
+  cues.sort((a, b) => a.atSec - b.atSec);
+  return { cues, dropped };
+}

package/src/browser.ts

@@ -11,6 +11,13 @@ export * from "./overrides";
 // The editor derives its plain takes with the SAME function the pipeline
 // uses — a copy would drift and the two timelines would disagree.
 export * from "./fill";
+// The SFX lane positions scene-anchored markers off the SAME map produce
+// resolves their cues from (`resolveSfxCues`) — a second "where does scene-3
+// start" is how the editor's diamond and the render's cue would disagree.
+// `assemble.ts` is browser-safe (type imports plus `scene-registry`, already
+// on this surface), but only this one function is exposed: the rest of the
+// module is the pipeline's, not the bundle's.
+export { sceneStartSeconds } from "./assemble";
 export { ZOOM_MAX_SCALE, zoomScaleAt, type ZoomSegment } from "./zoom";
 // Pure geometry only — the ffmpeg/cache half lives in ./content-rect-detect
 // and must never enter the Remotion bundle.

package/src/config.ts

@@ -76,6 +76,38 @@ export interface OssclipConfig {
    * (`resolveCoverInVideo`), the `watermark` contract exactly.
    */
   coverInVideo?: boolean;
+  /**
+   * Place sound effects on every produce run (`--sfx`), so a creator who
+   * always wants sound design writes it once instead of typing the flag.
+   * DEFAULT OFF: effects are an editorial choice, and inheriting them
+   * silently would change how every existing project sounds. `--sfx` wins
+   * per run (`resolveSfx`, the `watermark` contract).
+   */
+  sfx?: boolean;
+  /**
+   * How much sound design `--sfx` places: "subtle" | "normal" (the default) |
+   * "meme". File-only, the `resolution` posture: validated where it is USED
+   * (`resolveSfxLevel` in produce.ts), so a hand-edited "loud" earns one
+   * warning and `normal` rather than a coerced level — and never `meme`,
+   * which is the one that unlocks the meme-tagged sounds.
+   */
+  sfxLevel?: string;
+  /**
+   * Whether the bundled starter pack feeds the sound-effect menu. DEFAULT ON —
+   * it is the whole library for anyone who never wrote a pack. Set `false` and
+   * only `~/.ossclip/sfx` is loaded, which is the ask of someone whose own pack
+   * overrides a few stock ids and who wants the REST of them (pop, click,
+   * riser-short…) out of the model's menu entirely — overriding ids one at a
+   * time cannot do that.
+   *
+   * Config-level on purpose, with no CLI flag: which packs you own is a
+   * property of the machine, not of a run. File-only, the `sfxLevel` posture:
+   * validated where it is USED (`resolveSfxBundledPack`, next to the loader in
+   * sfx-pack.ts, because the edit server needs the same answer), so a
+   * hand-edited `"no"` earns one warning and the bundled pack, never a coerced
+   * exclusion.
+   */
+  sfxBundledPack?: boolean;
   /**
    * Terms of art the speaker uses — "JSON", "ossclip", "Genkit" — biasing
    * transcription (whisper `--prompt`), vouching repair corrections, and
@@ -152,6 +184,14 @@ export interface OssclipConfig {
    * (`publishConfigured` in the CLI), never coerced.
    */
   postizUrl?: string;
+  /**
+   * `--resolution`'s default for this machine: "auto" (keep what the source
+   * has, capped at 2160), "1080" (the built-in default), "1440" or "2160".
+   * File-only, the `watermark` posture: validated where it is USED
+   * (`resolveResolution` in produce.ts), so a hand-edited "4k" earns one
+   * warning and the 1080 default rather than a coerced render size.
+   */
+  resolution?: string;
   /**
    * USD per million tokens, keyed by model id or family substring — overrides
    * the built-in assumptions in `producer/usage.ts` so a run's cost line
@@ -218,22 +258,39 @@ export function loadConfig(): OssclipConfig {
   } catch {
     // no config file — fine
   }
+  return resolveConfig(fileCfg, process.env);
+}
+
+/**
+ * The pure half of `loadConfig` — the file-vs-env-vs-default resolution with
+ * no homedir read, so the mapping itself is testable (config.test.ts). Split
+ * out after the 2026-08-27 publish E2E: `postizUrl` sat on the TYPE and in
+ * the docs but this hand-written mapping never copied it, so publish reported
+ * "missing postizUrl" against a config.json that plainly had it — a key that
+ * exists only in the type is invisible at runtime, and nothing could say so
+ * while the mapping lived behind the filesystem.
+ */
+export function resolveConfig(
+  fileCfg: Partial<OssclipConfig>,
+  env: NodeJS.ProcessEnv,
+): OssclipConfig {
   return {
-    ffmpegPath: process.env.OSSCLIP_FFMPEG ?? fileCfg.ffmpegPath ?? DEFAULTS.ffmpegPath,
-    ffprobePath: process.env.OSSCLIP_FFPROBE ?? fileCfg.ffprobePath ?? DEFAULTS.ffprobePath,
-    whisperPath: process.env.OSSCLIP_WHISPER ?? fileCfg.whisperPath ?? DEFAULTS.whisperPath,
-    modelDir: process.env.OSSCLIP_MODEL_DIR ?? fileCfg.modelDir ?? DEFAULTS.modelDir,
-    model: process.env.OSSCLIP_MODEL ?? fileCfg.model ?? DEFAULTS.model,
-    fastModel: process.env.OSSCLIP_FAST_MODEL ?? fileCfg.fastModel,
+    ffmpegPath: env.OSSCLIP_FFMPEG ?? fileCfg.ffmpegPath ?? DEFAULTS.ffmpegPath,
+    ffprobePath: env.OSSCLIP_FFPROBE ?? fileCfg.ffprobePath ?? DEFAULTS.ffprobePath,
+    whisperPath: env.OSSCLIP_WHISPER ?? fileCfg.whisperPath ?? DEFAULTS.whisperPath,
+    modelDir: env.OSSCLIP_MODEL_DIR ?? fileCfg.modelDir ?? DEFAULTS.modelDir,
+    model: env.OSSCLIP_MODEL ?? fileCfg.model ?? DEFAULTS.model,
+    fastModel: env.OSSCLIP_FAST_MODEL ?? fileCfg.fastModel,
     // File-only, the `dictionary` posture — and deliberately NO env spelling
     // (flag + config are the whole interface): validated where it is USED
     // (`resolveLlmEffort` in produce.ts), so a hand-edited `"max"` earns one
     // warning there and agy's default, never a coerced effort.
     llmEffort: fileCfg.llmEffort,
-    speaker: process.env.OSSCLIP_SPEAKER ?? fileCfg.speaker,
-    openEditorAfterProduce: (process.env.OSSCLIP_OPEN_EDITOR ??
-      fileCfg.openEditorAfterProduce) as OpenEditorPref | undefined,
-    browserExecutable: process.env.OSSCLIP_BROWSER ?? fileCfg.browserExecutable,
+    speaker: env.OSSCLIP_SPEAKER ?? fileCfg.speaker,
+    openEditorAfterProduce: (env.OSSCLIP_OPEN_EDITOR ?? fileCfg.openEditorAfterProduce) as
+      | OpenEditorPref
+      | undefined,
+    browserExecutable: env.OSSCLIP_BROWSER ?? fileCfg.browserExecutable,
     // File-only, like `pricing`: an env spelling would arrive as a string,
     // and "false" is truthy — parse-don't-coerce says no such trap. The
     // strict `=== true` check lives at the consumer (produce's
@@ -245,6 +302,18 @@ export function loadConfig(): OssclipConfig {
     // non-boolean stays OFF — the safe default for something that paints over
     // the first frames of the hook.
     coverInVideo: fileCfg.coverInVideo,
+    // File-only, `watermark`'s posture again: the strict `=== true` lives at
+    // the consumer (produce's `resolveSfx`) and the level is zod-parsed there
+    // (`resolveSfxLevel`), so a hand-edited non-boolean stays OFF and a
+    // misspelled level earns a warning and `normal`.
+    sfx: fileCfg.sfx,
+    sfxLevel: fileCfg.sfxLevel,
+    // File-only too, and NO env spelling for the `watermark` reason: "false"
+    // arrives truthy from an environment. The typeof check lives at the
+    // consumer (`resolveSfxBundledPack` in sfx-pack.ts), where an absent or
+    // malformed value keeps the bundled pack — the safe default, since the
+    // alternative is a library that may be empty.
+    sfxBundledPack: fileCfg.sfxBundledPack,
     // File-only for the same reason as `watermark`: these are structured
     // values a hand-editable JSON file supplies, and parse-don't-coerce says
     // the strict checks live at the consumer — `validDictionary` /
@@ -272,5 +341,10 @@ export function loadConfig(): OssclipConfig {
     thumbnailBrief: fileCfg.thumbnailBrief,
     thumbnailModel: fileCfg.thumbnailModel,
     pricing: fileCfg.pricing,
+    // File-only, non-secret by declaration (the field's own doc): the API key
+    // deliberately lives in the environment (publish.ts's
+    // `publishConfigured`), so this is only the instance URL.
+    postizUrl: fileCfg.postizUrl,
+    resolution: fileCfg.resolution,
   };
 }

package/src/exec.ts

@@ -12,13 +12,24 @@ export interface ExecResult {
 export function run(
   bin: string,
   args: string[],
-  opts: { allowNonZero?: boolean; stdin?: string } = {},
+  opts: {
+    allowNonZero?: boolean;
+    stdin?: string;
+    /** Per-chunk stdout tap, IN ADDITION to collection — the delivery
+     * encode's `-progress pipe:1` stream needs live chunks, not the
+     * post-mortem transcript. */
+    onStdout?: (chunk: string) => void;
+  } = {},
 ): Promise<ExecResult> {
   return new Promise((resolve, reject) => {
     const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
-    child.stdout.on("data", (c: Buffer) => (stdout += c.toString()));
+    child.stdout.on("data", (c: Buffer) => {
+      const text = c.toString();
+      stdout += text;
+      opts.onStdout?.(text);
+    });
     child.stderr.on("data", (c: Buffer) => (stderr += c.toString()));
     child.on("error", (err) => reject(new Error(`${bin} failed to start: ${err.message}`)));
     child.on("close", (code) => {

package/src/grounding.ts

@@ -102,6 +102,39 @@ function stringsOf(value: unknown): string[] {
   return [];
 }
 
+/**
+ * The tokens in `text` that the transcript nowhere supports, in text order,
+ * duplicates kept. This IS the grounding rule — `checkGrounding` walks scene
+ * fields through it, and the publish panel's caption regenerate runs it over
+ * a rewritten caption as an ADVISORY (captions legitimately contain brand and
+ * platform words never spoken, so its callers show notes, never a block).
+ * One spelling on purpose: the module header's §17 history is what a second
+ * copy of the supported() relaxation would eventually re-earn.
+ *
+ * The spoken set is rebuilt per call — cheap at real transcript sizes, and
+ * the price of keeping the rule callable on a single string.
+ *
+ * The transcript parameter demands only spoken text, which is all the rule
+ * reads: a full `Transcript` satisfies it, and so does the edit server's
+ * leniently-read transcript.json (words filtered to those with string text,
+ * timing not re-validated for a check that never looks at it).
+ */
+export function ungroundedTokens(
+  text: string,
+  transcript: { words: ReadonlyArray<{ text: string }> },
+  speaker?: string,
+): string[] {
+  const spoken = new Set([
+    ...transcript.words.flatMap((w) => tokenize(w.text)),
+    ...(speaker ? tokenize(speaker) : []),
+  ]);
+  const supported = (token: string): boolean =>
+    spoken.has(token) ||
+    spoken.has(`${token}s`) ||
+    (token.endsWith("s") && spoken.has(token.slice(0, -1)));
+  return tokenize(text).filter((token) => needsSupport(token) && !supported(token));
+}
+
 export function checkGrounding(
   scenes: readonly Scene[],
   transcript: Transcript,
@@ -113,25 +146,14 @@ export function checkGrounding(
    */
   speaker?: string,
 ): GroundingIssue[] {
-  const spoken = new Set([
-    ...transcript.words.flatMap((w) => tokenize(w.text)),
-    ...(speaker ? tokenize(speaker) : []),
-  ]);
-  const supported = (token: string): boolean =>
-    spoken.has(token) ||
-    spoken.has(`${token}s`) ||
-    (token.endsWith("s") && spoken.has(token.slice(0, -1)));
-
   const issues: GroundingIssue[] = [];
   for (const scene of scenes) {
     const fields = CHECKED_FIELDS[scene.component] ?? [];
     const merged = { ...scene.props, ...scene.overrides };
     for (const field of fields) {
       for (const text of stringsOf(merged[field])) {
-        for (const token of tokenize(text)) {
-          if (needsSupport(token) && !supported(token)) {
-            issues.push({ sceneId: scene.id, component: scene.component, field, token });
-          }
+        for (const token of ungroundedTokens(text, transcript, speaker)) {
+          issues.push({ sceneId: scene.id, component: scene.component, field, token });
         }
       }
     }

package/src/index.ts

@@ -19,6 +19,7 @@ export * from "./blooper";
 export * from "./retake";
 export * from "./captions";
 export * from "./fonts";
+export * from "./sfx-pack";
 export * from "./dictionary";
 export * from "./zoom";
 export * from "./grounding";
@@ -42,4 +43,5 @@ export * from "./export-premiere-xml";
 export * from "./export-premiere-project";
 export * from "./export-xmeml-util";
 export * from "./config";
+export * from "./resolution";
 export { run } from "./exec";

package/src/ingest.ts

@@ -137,7 +137,7 @@ export interface MezzanineScale {
 }
 
 /** Nearest even dimension — yuv420 chroma subsampling needs both axes even. */
-function evenDim(v: number): number {
+export function evenDim(v: number): number {
   return Math.max(2, 2 * Math.round(v / 2));
 }