@ossclip/core 0.1.33 → 0.1.35

package/src/resolution.ts

@@ -0,0 +1,114 @@
+import { z } from "zod/v4";
+
+/**
+ * How big the output actually renders (2026-08-27).
+ *
+ * ossclip rendered 1080×1920 unconditionally, and three separate stages
+ * enforced it: the folder-concat target, the mezzanine's scale filter, and
+ * the render. A 4K take therefore lost three quarters of its pixels before
+ * anything looked at it — invisible on LinkedIn/Instagram/TikTok, which cap
+ * at 1080p anyway, but real on YouTube, which keeps 4K and gives it a better
+ * codec tier.
+ *
+ * This is the ONE place that decides the size, so those three stages cannot
+ * disagree. It returns a SCALE FACTOR, not a stage to build from: the
+ * composition must stay 1080-wide because `captionFontSizeFor` (scenes/
+ * stage.ts) answers in ABSOLUTE px — 64 portrait, 44 landscape — so a
+ * composition built at 2160 would draw captions a quarter of their intended
+ * size. Remotion's own `scale` renders that same composition larger, fonts
+ * and strokes included.
+ */
+
+/** `--resolution`: an explicit short-edge height, or `auto` from the source. */
+export const RESOLUTION_CHOICES = ["auto", "1080", "1440", "2160"] as const;
+
+export type ResolutionChoice = (typeof RESOLUTION_CHOICES)[number];
+
+/** The gate every user-supplied resolution passes through — flag AND config,
+ * so a hand-edited `"resolution": "4k"` earns the same refusal as a typo'd
+ * flag rather than a silent fallback (CLAUDE.md: parse, never coerce). */
+export const ResolutionChoiceSchema = z.enum(RESOLUTION_CHOICES);
+
+/**
+ * The ceiling `auto` will not cross, as a short-edge height. An 8K source
+ * answers 2160 rather than 4320: h264 at 8K is not universally playable, and
+ * the render cost grows with the pixel count.
+ */
+export const MAX_AUTO_HEIGHT = 2160;
+
+/** The base short edge both frames share — the unit every choice divides by. */
+const BASE_SHORT_EDGE = 1080;
+
+/**
+ * `auto` snaps DOWN to a half step (1, 1.5, 2). Two reasons, both hard:
+ * h264 needs EVEN dimensions, and 1080/1920 times a half step is always even
+ * while an arbitrary factor is not (1.125 → 1215, odd); and rounding odd
+ * dimensions to even would drift the frame off 9:16, which the platforms
+ * letterbox. Snapping down rather than up keeps the promise that auto never
+ * invents detail the source does not have.
+ */
+const AUTO_STEP = 0.5;
+
+export interface OutputFrame {
+  /** What Remotion renders the 1080-wide composition at. */
+  scale: number;
+  /** The resulting file's dimensions — what `production.json` records. */
+  width: number;
+  height: number;
+}
+
+/**
+ * The clip a FOLDER input can honestly be sized by: the smallest.
+ *
+ * A folder concat letterboxes every take into one frame (`buildConcatFilter`),
+ * so the frame carries only what the weakest clip has — sizing by the largest
+ * would upscale every other take and charge render time for invented pixels.
+ * Clips that failed to probe are ignored rather than counted as zero, and a
+ * listing with nothing usable answers `null` so the caller falls back to its
+ * default instead of sizing a render off a guess.
+ */
+export function smallestSource(
+  sizes: ReadonlyArray<{ width: number; height: number }>,
+): { width: number; height: number } | null {
+  const usable = sizes.filter((s) => s.width > 0 && s.height > 0);
+  if (usable.length === 0) return null;
+  return usable.reduce((min, s) => (s.width * s.height < min.width * min.height ? s : min));
+}
+
+export function resolveOutputFrame(args: {
+  frame: { width: number; height: number };
+  /** The source's DISPLAY dimensions (rotation already applied by the probe). */
+  source: { width: number; height: number };
+  resolution: ResolutionChoice;
+}): OutputFrame {
+  const { frame, source, resolution } = args;
+  const at = (scale: number): OutputFrame => ({
+    scale,
+    width: Math.round(frame.width * scale),
+    height: Math.round(frame.height * scale),
+  });
+  if (resolution !== "auto") {
+    return at(Number(resolution) / BASE_SHORT_EDGE);
+  }
+  // A probe that answered nothing cannot size anything: today's 1080p is the
+  // honest fallback, never a throw in the middle of a render.
+  if (!(source.width > 0) || !(source.height > 0)) return at(1);
+
+  // The pixels that SURVIVE the crop, not the ones the file advertises. The
+  // source is fitted to the output's aspect and the overflow is cropped
+  // (produce's own `force_original_aspect_ratio=increase,crop=`), so the
+  // usable width is whichever edge binds.
+  const frameAspect = frame.width / frame.height;
+  const sourceAspect = source.width / source.height;
+  const usableWidth =
+    sourceAspect > frameAspect
+      ? source.height * frameAspect // wider than the frame: sides are cropped
+      : source.width; //               taller than the frame: top/bottom cropped
+
+  const raw = usableWidth / frame.width;
+  const snapped = Math.floor(raw / AUTO_STEP) * AUTO_STEP;
+  const capped = Math.min(snapped, MAX_AUTO_HEIGHT / BASE_SHORT_EDGE);
+  // Never below today's output: a 720p source still renders 1080p, which is
+  // what every caller already depends on.
+  return at(Math.max(capped, 1));
+}

package/src/schema.ts

@@ -99,6 +99,43 @@ export type RenderSettings = z.infer<typeof RenderSettingsSchema>;
 
 import { SceneSchema, ThemeSchema } from "./scene-schema";
 
+/**
+ * The sound-effect plan as `production.json` STORES it: the level it was
+ * planned at plus the surviving placements.
+ *
+ * Restated here rather than imported from `producer/sfx.ts` on purpose, and
+ * the duplication is load-bearing: this module is in the EDITOR's runtime
+ * graph (browser.ts → overrides.ts → `RemovalReasonSchema`), while
+ * `producer/sfx.ts` reaches `beats.ts` → `cover.ts` → `node:child_process`.
+ * Importing the model-facing schema here would drag the whole producer — and
+ * node — into the Remotion/editor bundle. The two shapes are pinned equal by
+ * a test (`sfx-production-slot.test.ts`), which is what keeps this from
+ * becoming a silent second truth: the model-facing one caps `rationale` on the
+ * way IN (R27 §123's `cappedText`), and by the time a placement is stored the
+ * cap has already been applied.
+ */
+export const ProductionSfxSchema = z.object({
+  level: z.enum(["subtle", "normal", "meme"]),
+  placements: z.array(
+    z.object({
+      soundId: z.string(),
+      /** Index into the REPAIRED transcript — word indices, never seconds. */
+      word: z.number().int().nonnegative(),
+      /**
+       * The scene whose ENTRANCE this sound marks, when it has one
+       * (2026-08-29). Optional and absent-means-speech-synced, so every plan
+       * written before the field parses byte-identically. `word` above stays
+       * required beside it — it is the fallback when the scene is deleted or
+       * re-planned away (`SfxPlacementSchema` owns the full argument).
+       */
+      sceneId: z.string().optional(),
+      gain: z.number().min(0).max(2).optional(),
+      rationale: z.string().optional(),
+    }),
+  ),
+});
+export type ProductionSfx = z.infer<typeof ProductionSfxSchema>;
+
 /** The single source of truth for a production. Every pipeline stage is a pure function over this. */
 export const ProductionSchema = z.object({
   version: z.literal(1),
@@ -184,6 +221,18 @@ export const ProductionSchema = z.object({
     })
     .optional(),
   scenes: z.array(SceneSchema).optional(),
+  /**
+   * The `--sfx` placement plan (level + word-anchored placements), post
+   * `normalizeSfxPlan`. Optional and absent-means-no-sound-design, so every
+   * pre-feature `production.json` parses unchanged — and so a run without the
+   * flag writes a file byte-identical to what it always wrote.
+   *
+   * WORDS, not seconds, like every other anchor in this file: the cutlist can
+   * change under a re-render, and a second-stamped placement would drift off
+   * the moment it does (the resolver re-derives output time through the
+   * TimeMap, `resolveSfxCues`).
+   */
+  sfx: ProductionSfxSchema.optional(),
   /**
    * WHO planned this production (R16 §78). `usage.json` answers "what did
    * that cost", but it describes one run and a fully-cached re-run makes no

package/src/sfx-pack.ts

@@ -0,0 +1,281 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod/v4";
+import { CONFIG_DIR } from "./config";
+
+/**
+ * One sound in a pack. `kind` is a `z.literal("sound")` rather than a plain
+ * string BECAUSE the field is reserved for future video memes: when that ships
+ * the literal becomes an enum, and until then an entry declaring any other
+ * kind must be skipped with a warning instead of loaded as a sound (a video
+ * clip handed to `<Audio>` is a broken render, not a degraded one).
+ *
+ * `tags` is free-form, but "meme" is the ONE tag with semantics: it gates the
+ * sound out of the menu below `--sfx-level meme`. Anything else is metadata a
+ * pack author writes for themselves.
+ */
+export const SfxSoundSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/),
+  kind: z.literal("sound"),
+  /** Relative to the pack directory — never absolute, never escaping it. */
+  file: z.string().min(1),
+  /**
+   * The line the LLM reads when picking this sound. Capped rather than
+   * unbounded because the whole library goes into every placement prompt;
+   * this is pack metadata (a human wrote it), so a bare `.max` that REJECTS
+   * is right here — the §112 "degrade instead of die" rule is about model
+   * output, and a pack author gets a named issue and a skipped entry.
+   */
+  whenToUse: z.string().min(1).max(200),
+  tags: z.array(z.string()).default([]),
+  /** Mix level for this sound, multiplied by any per-placement gain. */
+  gain: z.number().min(0).max(2).default(1),
+  durationSec: z.number().positive().optional(),
+});
+export type SfxSound = z.infer<typeof SfxSoundSchema>;
+
+export const SfxPackSchema = z.object({
+  name: z.string().min(1),
+  sounds: z.array(SfxSoundSchema),
+});
+export type SfxPack = z.infer<typeof SfxPackSchema>;
+
+/** The only tag the pipeline reads — see `SfxSoundSchema.tags`. */
+export const SFX_MEME_TAG = "meme";
+
+/** A sound resolved to a file on disk, with the pack it came from. */
+export interface LoadedSfxSound extends SfxSound {
+  absPath: string;
+  packName: string;
+}
+
+/**
+ * Why a pack, or one entry in it, is not in the library. Every path that
+ * skips something emits one of these; nothing here throws, because a
+ * hand-written pack in `~/.ossclip/sfx` is user input and a typo in it must
+ * cost sound effects, not the produce run.
+ */
+export interface SfxPackIssue {
+  /** Pack directory name, or the pack's declared name for the bundled pack. */
+  pack: string;
+  issue: string;
+}
+
+export interface SfxLibrary {
+  sounds: LoadedSfxSound[];
+  issues: SfxPackIssue[];
+}
+
+/**
+ * The bundled starter pack's directory. `import.meta.url` rather than a path
+ * relative to cwd, the `nastaliqFontFile()` shape (fonts.ts) — and the
+ * packaging test (R22 §111) scans for exactly that shape to prove `assets`
+ * rides in the npm tarball.
+ */
+export function bundledSfxDir(): string {
+  return fileURLToPath(new URL("../assets/sfx", import.meta.url));
+}
+
+/** Where user packs live: `~/.ossclip/sfx/<pack>/pack.json`. */
+export function userSfxDir(): string {
+  return join(CONFIG_DIR, "sfx");
+}
+
+/**
+ * Read one pack directory. Returns the sounds it can resolve plus an issue
+ * per entry it cannot — a missing mp3, an id that is not a slug, a `kind`
+ * this version does not render. Never throws: unreadable JSON is one issue
+ * for the whole pack.
+ */
+function readPack(dir: string, label: string): SfxLibrary {
+  const issues: SfxPackIssue[] = [];
+  const manifest = join(dir, "pack.json");
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(manifest, "utf8"));
+  } catch (e) {
+    return { sounds: [], issues: [{ pack: label, issue: `unreadable pack.json: ${String(e)}` }] };
+  }
+  // Parsed shallowly first so ONE bad entry doesn't take the pack down with
+  // it (the scene-props batch fail-soft posture): the pack's own fields are
+  // validated here, each sound separately below.
+  const shell = z.object({ name: z.string().min(1), sounds: z.array(z.unknown()) }).safeParse(raw);
+  if (!shell.success) {
+    return { sounds: [], issues: [{ pack: label, issue: `invalid pack.json: ${shell.error.message}` }] };
+  }
+  const packName = shell.data.name;
+  const sounds: LoadedSfxSound[] = [];
+  for (const entry of shell.data.sounds) {
+    // Read `kind` BEFORE the schema so a future video-meme pack gets the
+    // reason it was skipped instead of a literal-mismatch error nobody can
+    // act on. v1 renders sounds only.
+    const kind = (entry as { kind?: unknown } | null)?.kind;
+    const id = (entry as { id?: unknown } | null)?.id;
+    const named = typeof id === "string" ? id : "<unnamed>";
+    if (typeof kind === "string" && kind !== "sound") {
+      issues.push({ pack: packName, issue: `skipped "${named}": kind "${kind}" is not supported yet` });
+      continue;
+    }
+    const parsed = SfxSoundSchema.safeParse(entry);
+    if (!parsed.success) {
+      issues.push({ pack: packName, issue: `skipped "${named}": ${parsed.error.message}` });
+      continue;
+    }
+    const absPath = join(dir, parsed.data.file);
+    if (!existsSync(absPath)) {
+      issues.push({ pack: packName, issue: `skipped "${parsed.data.id}": missing file ${parsed.data.file}` });
+      continue;
+    }
+    sounds.push({ ...parsed.data, absPath, packName });
+  }
+  return { sounds, issues };
+}
+
+/**
+ * The bundled starter pack's label in `SfxPackIssue.pack` — the pack's declared
+ * name, which is also what `readPack` falls back to when its manifest is
+ * unreadable and there is no declared name to quote.
+ */
+const BUNDLED_PACK_LABEL = "ossclip-starter";
+
+/**
+ * The `sfxBundledPack` config key, resolved. Default TRUE — the bundled pack is
+ * the library everyone who never wrote a pack has, so an absent key must keep
+ * the shipped behaviour.
+ *
+ * `typeof === "boolean"`, never truthiness (CLAUDE.md's parse-don't-coerce):
+ * a hand-edited `"sfxBundledPack": "no"` is a string, and coercing it would
+ * read as `true` — the opposite of what its author typed. It earns one warning
+ * and the default instead, and the warning is RETURNED rather than printed so
+ * this stays pure (`resolveSfxLevel`'s shape).
+ *
+ * It lives HERE, next to the loader, rather than beside its siblings in the
+ * CLI's produce.ts, because BOTH consumers need it — produce's sfx step and
+ * the edit server's sfx routes — and produce.ts already imports edit.ts, so
+ * the reverse import that would share it is a cycle. Two copies of this rule
+ * is the failure the editor cannot afford: it would offer sounds produce
+ * refuses to use.
+ */
+export function resolveSfxBundledPack(configValue: unknown): {
+  include: boolean;
+  warning?: string;
+} {
+  if (typeof configValue === "boolean") return { include: configValue };
+  if (configValue === undefined) return { include: true };
+  return {
+    include: true,
+    warning:
+      "⚠ config sfxBundledPack ignored — expected true or false, " +
+      "keeping the bundled pack in the library",
+  };
+}
+
+/**
+ * The bundled pack plus every user pack under `userDir`, merged by id.
+ *
+ * `includeBundled: false` (config `sfxBundledPack`) drops the bundled pack
+ * entirely, so ONLY `~/.ossclip/sfx` feeds the placement menu. It is not the
+ * same as overriding ids one by one: a user with their own pack still met
+ * `pop`, `click` and `riser-short` in every prompt, and the only way to get
+ * them out of the model's menu is to not load them.
+ *
+ * Duplicate policy:
+ *  - user pack over bundled, silently — overriding a stock sound with your own
+ *    recording is the WANTED case, not an error.
+ *  - user vs user: the alphabetically first pack directory wins, with an issue,
+ *    so the outcome is stable across filesystems that enumerate differently
+ *    (readdir order is not a promise) and the loser is named out loud.
+ *
+ * `userDir` is a parameter with a default rather than a read of `homedir()`
+ * inside, so tests point it at a tmp dir and never touch a real home.
+ */
+export function loadSfxLibrary(
+  opts: { userDir?: string; includeBundled?: boolean } = {},
+): SfxLibrary {
+  const userDir = opts.userDir ?? userSfxDir();
+  const includeBundled = opts.includeBundled ?? true;
+  const issues: SfxPackIssue[] = [];
+  const byId = new Map<string, LoadedSfxSound>();
+  /** Which pack currently owns each id, and whether it was a user pack. */
+  const owner = new Map<string, { pack: string; user: boolean }>();
+
+  if (includeBundled) {
+    const bundled = readPack(bundledSfxDir(), BUNDLED_PACK_LABEL);
+    issues.push(...bundled.issues);
+    for (const s of bundled.sounds) {
+      byId.set(s.id, s);
+      owner.set(s.id, { pack: s.packName, user: false });
+    }
+  }
+
+  let dirs: string[] = [];
+  try {
+    dirs = readdirSync(userDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    // No user pack directory at all is the normal case, not an issue.
+    dirs = [];
+  }
+  for (const name of dirs) {
+    const dir = join(userDir, name);
+    if (!existsSync(join(dir, "pack.json"))) continue; // not a pack, not an error
+    const pack = readPack(dir, name);
+    issues.push(...pack.issues);
+    for (const s of pack.sounds) {
+      const held = owner.get(s.id);
+      if (held?.user) {
+        issues.push({
+          pack: s.packName,
+          issue: `duplicate id "${s.id}" — keeping the one from "${held.pack}" (first pack alphabetically)`,
+        });
+        continue;
+      }
+      byId.set(s.id, s);
+      owner.set(s.id, { pack: s.packName, user: true });
+    }
+  }
+
+  // Sorted by id so the menu, the hash and every report read the same on
+  // every machine — merge order must not leak into the prompt.
+  const sounds = [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+  // Excluded the only pack there was. Every caller already warns-and-skips on
+  // an empty library, but "no usable sounds" alone reads as a packaging bug in
+  // ossclip; the user turned this off in config and has nothing else on disk,
+  // and only the loader knows that. So it is named here, as an issue like any
+  // other, and the existing zero-sounds path prints it verbatim.
+  if (!includeBundled && sounds.length === 0) {
+    issues.push({
+      pack: BUNDLED_PACK_LABEL,
+      issue:
+        `bundled pack excluded ("sfxBundledPack": false) and no user packs found in ` +
+        `${userDir} — add a pack there, or set "sfxBundledPack": true to get it back`,
+    });
+  }
+  return { sounds, issues };
+}
+
+/**
+ * A fingerprint of the library as the MODEL sees it — id, whenToUse, tags,
+ * gain — and deliberately not the audio bytes or the file paths.
+ *
+ * This rides the placement cache key, so hashing the mp3s would re-bill an
+ * LLM call every time a pack is re-encoded at a different bitrate, for a
+ * prompt that is byte-identical. Conversely an edited `whenToUse` DOES change
+ * what the model was asked, so it must invalidate.
+ */
+export function sfxLibraryHash(sounds: readonly SfxSound[]): string {
+  const material = [...sounds]
+    .map((s) => ({
+      id: s.id,
+      whenToUse: s.whenToUse,
+      // Sorted: tag order is authoring noise, not a different library.
+      tags: [...s.tags].sort(),
+      gain: s.gain,
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+  return createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}

package/src/transcribe.ts

@@ -235,6 +235,16 @@ export interface WhisperOptions {
    * silently dropping the user's terms.
    */
   prompt?: string;
+  /**
+   * whisper's TRANSLATE task (`-tr`): decode non-English speech straight to
+   * ENGLISH text (2026-08-29). Orthogonal to `language`, which only says what
+   * is being SPOKEN — `-l ur` alone emits Urdu script, correct for Urdu
+   * captions and wrong for an English-captioned short. Pass both together:
+   * whisper still needs to know the source language to decode it well.
+   *
+   * Left unset, the spawned args stay byte-identical to every prior run.
+   */
+  translate?: boolean;
 }
 
 /**
@@ -261,6 +271,9 @@ export function whisperArgs(opts: WhisperOptions, wavPath: string): string[] {
     "--no-prints",
   ];
   if (opts.language !== undefined) args.push("-l", opts.language);
+  // AFTER `-l`: whisper reads the pair as "this language, translated", and
+  // keeping the order fixed is what makes the arg list assertable.
+  if (opts.translate === true) args.push("-tr");
   if (opts.prompt !== undefined) args.push("--prompt", opts.prompt);
   return args;
 }