@ossclip/core 0.1.33 → 0.1.34

package/package.json

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

package/src/config.ts

@@ -152,6 +152,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 +226,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
@@ -272,5 +297,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

@@ -42,4 +42,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));
 }
 

package/src/producer/caption-regen.ts

@@ -0,0 +1,132 @@
+import { z } from "zod/v4";
+import type { LlmProvider } from "./provider";
+import { YOUTUBE_TRANSCRIPT_CHAR_CAP } from "./youtube";
+import { truncateAtWordBoundary } from "../publish/captions";
+
+/**
+ * Regenerate ONE network's caption from the editor's publish panel
+ * (handoff 2026-08-29 item 4). The prompt carries the transcript, the
+ * caption AS THE PANEL HOLDS IT (the user's manual edits included — the
+ * model must see what the user sees) and the user's correction, and returns
+ * replacement text only: nothing here writes to the pack or sends anything.
+ *
+ * Pure prompt builder separated from the provider call, the
+ * `buildYoutubePrompt` split, so the include/cap matrix is testable without
+ * an LLM.
+ */
+
+export const CaptionRegenSchema = z.object({ caption: z.string() });
+
+export interface CaptionRegenArgs {
+  /** The network the caption posts to ("linkedin", "x", …) — named in the
+   * prompt so the rewrite keeps that platform's idiom. */
+  network: string;
+  /** What the panel's box holds right now, manual edits and all. */
+  currentCaption: string;
+  /** The user's correction — the whole reason this call exists. */
+  instruction: string;
+  /** The transcript as plain text — the only source of factual claims. */
+  transcriptText: string;
+  /** The platform's caption cap (publish/captions.ts's captionCap). */
+  charCap: number;
+}
+
+/** What a truncated transcript ends with — the model must know it is reading
+ * an excerpt (buildYoutubePrompt's TRUNCATION_NOTE rule, restated because
+ * that constant is module-private and this note's wording is its own). */
+const TRUNCATION_NOTE = "[transcript truncated — the video continues]";
+
+/**
+ * Platform idiom the model is told to write toward — the author's own
+ * per-platform shapes (his voice guide), not generic social-media advice.
+ * Keyed by publish provider name; absence falls through to nothing extra.
+ */
+const NETWORK_PRACTICES: Record<string, string> = {
+  linkedin:
+    "LinkedIn: the fullest version — the reader's gap first, then what was built, one " +
+    "technical detail worth defending, the honest limitation inline, warm low-key close. " +
+    "Short paragraphs, but never one-line 'broetry' stacked for the algorithm.",
+  "linkedin-page":
+    "LinkedIn page: same shape as a personal LinkedIn post — gap first, specifics over " +
+    "adjectives, honest limitation inline, no broetry.",
+  youtube:
+    "YouTube description: plain what-it-does in the first two lines (that is all most " +
+    "viewers see), keep any existing timestamps/chapters and links intact.",
+  facebook:
+    "Facebook: conversational, front-load the reader's problem in the first sentence, " +
+    "shorter than LinkedIn.",
+  instagram:
+    "Instagram: short — the visual leads, the caption carries ONE specific. Links do not " +
+    "work in captions, so 'link in bio' phrasing, never a raw URL. Keep existing hashtags " +
+    "unless instructed.",
+  threads:
+    "Threads: short and conversational like Instagram; one specific, no hashtag walls.",
+  x: "X: the gap and the one surprising detail — nothing padded.",
+  tiktok: "TikTok: short hook line plus existing hashtags.",
+};
+
+export function buildCaptionRegenPrompt(args: CaptionRegenArgs): { system: string; user: string } {
+  const system =
+    "You rewrite ONE social media caption for a finished video, applying the user's " +
+    "instruction. Hard rules:\n" +
+    "- Every factual claim in the caption must be supported by the transcript. If the video " +
+    "uses a number or story as an EXAMPLE or hypothetical, never state it as a fact — this " +
+    "exact failure has shipped: a video said \"imagine 50 teams applied\" as an example, and " +
+    "the published caption stated \"50 teams applied\" as fact.\n" +
+    "- NEVER use an em-dash (—) or en-dash (–) anywhere in the caption. Where a pause or " +
+    "soft pivot is needed, use an ellipsis (\"...\") — that is the author's voice, not a typo " +
+    "to clean up.\n" +
+    "- Specifics over adjectives: no \"powerful\", \"seamless\", \"game-changing\". Name the " +
+    "actual number or detail, and only numbers the transcript supports.\n" +
+    "- No engagement bait (\"thoughts?\", \"drop a comment\", \"who else...\"), no emoji " +
+    "bullets or rocket emoji; at most a single \":)\".\n" +
+    "- Respect the character cap given for this network — the platform truncates or rejects " +
+    "anything longer.\n" +
+    "- Keep the author's voice and structure from the current caption unless the instruction " +
+    "says otherwise: this is a correction, not a rewrite from scratch.\n" +
+    "- Output only the caption text, nothing else.";
+  const practice = NETWORK_PRACTICES[args.network];
+  // The same cap buildYoutubePrompt applies, imported rather than restated:
+  // slice + say so, so the model knows it is reading an excerpt.
+  const capped =
+    args.transcriptText.length > YOUTUBE_TRANSCRIPT_CHAR_CAP
+      ? `${args.transcriptText.slice(0, YOUTUBE_TRANSCRIPT_CHAR_CAP)}\n${TRUNCATION_NOTE}`
+      : args.transcriptText;
+  const user =
+    `Network: ${args.network} (character cap: ${args.charCap})\n` +
+    (practice ? `Platform practice: ${practice}\n` : "") +
+    "\n" +
+    `Current caption:\n${args.currentCaption}\n\n` +
+    `Instruction from the author:\n${args.instruction}\n\n` +
+    `Transcript:\n${capped}`;
+  return { system, user };
+}
+
+/**
+ * The em/en-dash ban enforced mechanically — the prompt asks, this
+ * guarantees. Ellipsis replaces a mid-sentence dash (the author's own pause
+ * idiom); a dash already followed by ellipsis-like punctuation just drops.
+ */
+export function stripDashes(text: string): string {
+  return text.replace(/\s*[—–]\s*/g, "... ").replace(/\.\.\.\s+(?=[.…])/g, "");
+}
+
+/** One editorial call → the replacement caption, capped at a word boundary
+ * as the belt-and-braces backstop (the schema cannot express a length cap
+ * the model is guaranteed to honor). */
+export async function generateCaptionRegen(
+  provider: LlmProvider,
+  args: CaptionRegenArgs,
+): Promise<string> {
+  const { system, user } = buildCaptionRegenPrompt(args);
+  const { caption } = await provider.complete({
+    system,
+    user,
+    schema: CaptionRegenSchema,
+    schemaName: "caption_regen",
+    // Editorial on purpose: this rewrites the copy real accounts publish,
+    // which is exactly the judgement tier the beat sheet buys.
+    tier: "editorial",
+  });
+  return truncateAtWordBoundary(stripDashes(caption), args.charCap);
+}

package/src/producer/index.ts

@@ -27,6 +27,7 @@ export * from "./provider";
 export * from "./usage";
 export * from "./beats";
 export * from "./youtube";
+export * from "./caption-regen";
 export * from "./scene-props";
 export * from "./repair";
 export { AnthropicProvider, DEFAULT_CLAUDE_MODEL } from "./anthropic";

package/src/publish/captions.ts

@@ -15,6 +15,13 @@ import type { YoutubePack } from "../producer/youtube";
 export const CAPTION_CAPS: Record<string, number> = {
   x: 280,
   linkedin: 1500,
+  // A company page is the same network with the same limit — Postiz reports
+  // it as its own provider (`linkedin-page`), so it needs its own entry or it
+  // silently takes DEFAULT_CAPTION_CAP (2026-08-27 live E2E).
+  "linkedin-page": 1500,
+  // Threads' own hard limit, well under the generic default it used to
+  // inherit (2026-08-28).
+  threads: 500,
   instagram: 2200,
   tiktok: 2200,
   facebook: 2200,
@@ -61,9 +68,25 @@ export function deriveCaption(pack: YoutubePack, provider: string): string {
 export function captionForProvider(pack: YoutubePack, provider: string): string {
   const captions = pack.platformCaptions;
   const authored =
-    provider === "linkedin"
+    // `linkedin-page` (a company page) reads the SAME authored field: same
+    // network, same idiom, same cap. Without this arm a page fell through to
+    // the title-plus-hashtags floor while the personal feed published the
+    // authored post — the shape the 2026-08-27 live E2E caught in its dry run.
+    // YouTube's caption is the DESCRIPTION box, and `description` is the one
+    // pack field written for exactly it (the title rides `settings.title`,
+    // set by `buildPublishPosts`). Without this arm a pack carrying a full
+    // description published the title-plus-hashtags floor — 94 characters of
+    // it — which the 2026-08-28 channel connection showed in its dry run.
+    provider === "youtube"
+      ? pack.description
+      : provider === "linkedin" || provider === "linkedin-page"
       ? pack.linkedinPost
-      : provider === "instagram"
+      : // Threads has no field of its own, and this module never invents
+      // copy — so it borrows the closest idiom the pack DOES write. Same
+      // company, same audience, same short-video framing; the 500-char cap
+      // above trims it at a word boundary rather than letting Threads
+      // reject it (2026-08-28, a real connected account).
+      provider === "instagram" || provider === "threads"
         ? captions?.instagram
         : provider === "tiktok"
           ? captions?.tiktok

package/src/publish/delivery.ts

@@ -0,0 +1,303 @@
+import { existsSync } from "node:fs";
+import { rename, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { run } from "../exec";
+import { evenDim, probe, type IngestTools } from "../ingest";
+import { parseFfmpegProgress, type FfmpegProgress } from "./progress";
+import type { Probe } from "../schema";
+
+/**
+ * Delivery encode for `ossclip publish` (2026-08-29 handoff, item 1).
+ *
+ * The first real multi-platform publish uploaded the MASTER render — 589MB at
+ * ~56 Mbps after `--resolution auto` kept the 4K source's pixels — and failed
+ * 5/6 channels. Every platform re-encodes to 6–12 Mbps on ingest, so master
+ * quality buys nothing but upload failures (Instagram 2207077, opaque
+ * Facebook/Threads errors, and enough bytes to make LinkedIn's ranged-GET
+ * issue fatal). The fix is a delivery encode: ≤1080p h264/aac at ~10 Mbps,
+ * built lazily at publish time and cached in the workdir. The master stays
+ * untouched for the archive.
+ */
+
+/** Delivery caps: 1920×1080 landscape, 1080×1920 portrait. */
+export const DELIVERY_MAX_SHORT_EDGE = 1080;
+export const DELIVERY_MAX_LONG_EDGE = 1920;
+
+/**
+ * 10 Mbps target, 12 Mbps ceiling — the top of the range platforms transcode
+ * to, so nothing visible is lost that the platform would have kept anyway.
+ * The same 12k ceiling doubles as the skip threshold: a master already at or
+ * under it gains nothing from a re-encode.
+ */
+export const DELIVERY_VIDEO_BITRATE_KBPS = 10000;
+export const DELIVERY_MAX_BITRATE_KBPS = 12000;
+
+/** What encodeDelivery's `-b:a` always is — fitBitrateKbps must budget for it. */
+export const DELIVERY_AUDIO_BITRATE_KBPS = 192;
+
+/**
+ * Below ~1 Mbps, 1080p h264 is visibly broken — a size cap that forces the
+ * video bitrate under this floor is unattainable, and refusing the channel
+ * beats publishing mush the platform would host forever.
+ */
+export const DELIVERY_MIN_VIDEO_BITRATE_KBPS = 1000;
+
+/**
+ * mp4 container overhead margin (~3%) between raw stream bitrates and the
+ * bytes on disk. Checked against the field data (2026-08-29): a 2000k video +
+ * 192k audio encode of a 321s take landed at 88MB, i.e. within this margin of
+ * the naive stream sum — so budgeting streams at cap/1.03 keeps the file
+ * under the cap without giving away real bitrate.
+ */
+const DELIVERY_MUX_OVERHEAD = 1.03;
+
+/**
+ * The video bitrate (kbps, floored) that fits a delivery file under
+ * `capBytes`: total byte budget shrunk by the mux-overhead margin, minus the
+ * audio's share. May come out below the quality floor (or negative) for long
+ * videos — `deliveryEncodePlan` turns that into an explicit `unattainable`
+ * verdict rather than clamping.
+ */
+export function fitBitrateKbps(
+  capBytes: number,
+  durationSec: number,
+  audioKbps: number = DELIVERY_AUDIO_BITRATE_KBPS,
+): number {
+  const totalKbps = (capBytes * 8) / DELIVERY_MUX_OVERHEAD / durationSec / 1000;
+  return Math.floor(totalKbps - audioKbps);
+}
+
+export interface DeliverySource {
+  width: number;
+  height: number;
+  fps: number;
+  /** Seconds, from probe. */
+  duration: number;
+  /** From stat — with duration this measures the real bitrate, no probe schema change needed. */
+  sizeBytes: number;
+}
+
+export interface DeliveryPlan {
+  width: number;
+  height: number;
+  videoBitrateKbps: number;
+  fileName: string;
+}
+
+/**
+ * The delivery file's name, which IS its cache key (mezzanine precedent,
+ * `mezzanineFileName`): the encode parameters live in the name so a rule
+ * change misses the old cache instead of silently serving it.
+ */
+export function deliveryFileName(width: number, height: number, videoBitrateKbps: number): string {
+  return `delivery-${width}x${height}@${videoBitrateKbps}k.mp4`;
+}
+
+/**
+ * The verdict when a size cap cannot be met above the quality floor —
+ * distinct from null (no encode NEEDED) so a caller can refuse the channel
+ * with the number that doomed it. The verdict lives in the plan's return
+ * rather than a separate `sizeCapAttainable()` checker because the fit
+ * arithmetic would then exist twice and drift — a caller cannot plan and
+ * forget to check when the plan IS the check.
+ */
+export interface DeliveryUnattainable {
+  unattainable: true;
+  /** The video kbps the cap would have needed — for the refusal message. */
+  fittedKbps: number;
+}
+
+/**
+ * What the delivery encode should be, or null when the master is already
+ * uploadable as-is (dims within caps AND measured bitrate ≤ the ceiling —
+ * masters are always h264/aac out of Remotion, so codec never enters the
+ * rule).
+ *
+ * Scale factor caps BOTH orientations without caring which one this is:
+ * min(1, 1080/short-edge, 1920/long-edge) lands landscape on 1920×1080 and
+ * portrait on 1080×1920, and never upscales — a small master re-encoded
+ * larger would soften every frame for zero bytes saved.
+ *
+ * `sizeCapBytes` is the per-platform upload ceiling (2026-08-29, live:
+ * Instagram's URL-fetch ingest rejected the 409MB 10 Mbps delivery file with
+ * 2207077 twice, then published the same 1080p take at 88MB/2 Mbps — see
+ * `PLATFORM_SIZE_CAP_BYTES`). When set, the bitrate is fitted under the cap;
+ * the null-skip additionally requires the master itself to fit, since an
+ * in-spec master can still be over a platform's byte ceiling.
+ */
+export function deliveryEncodePlan(src: DeliverySource): DeliveryPlan | null;
+export function deliveryEncodePlan(
+  src: DeliverySource,
+  opts: { sizeCapBytes?: number },
+): DeliveryPlan | DeliveryUnattainable | null;
+export function deliveryEncodePlan(
+  src: DeliverySource,
+  opts: { sizeCapBytes?: number } = {},
+): DeliveryPlan | DeliveryUnattainable | null {
+  if (src.width <= 0 || src.height <= 0 || src.duration <= 0) return null;
+  const k = Math.min(
+    1,
+    DELIVERY_MAX_SHORT_EDGE / Math.min(src.width, src.height),
+    DELIVERY_MAX_LONG_EDGE / Math.max(src.width, src.height),
+  );
+  const measuredKbps = (src.sizeBytes * 8) / src.duration / 1000;
+  const fitsCap = opts.sizeCapBytes === undefined || src.sizeBytes <= opts.sizeCapBytes;
+  if (k === 1 && measuredKbps <= DELIVERY_MAX_BITRATE_KBPS && fitsCap) return null;
+  // At k === 1 keep the exact source dims — even-rounding a size that is not
+  // being rescaled would manufacture a 1px no-op rescale (mezzanineScale
+  // learned the same lesson).
+  const width = k < 1 ? evenDim(src.width * k) : src.width;
+  const height = k < 1 ? evenDim(src.height * k) : src.height;
+  let videoBitrateKbps = DELIVERY_VIDEO_BITRATE_KBPS;
+  if (opts.sizeCapBytes !== undefined) {
+    const fitted = fitBitrateKbps(opts.sizeCapBytes, src.duration);
+    if (fitted < DELIVERY_MIN_VIDEO_BITRATE_KBPS) {
+      return { unattainable: true, fittedKbps: fitted };
+    }
+    videoBitrateKbps = Math.min(DELIVERY_VIDEO_BITRATE_KBPS, fitted);
+  }
+  return {
+    width,
+    height,
+    videoBitrateKbps,
+    fileName: deliveryFileName(width, height, videoBitrateKbps),
+  };
+}
+
+/**
+ * Run the delivery encode. `+faststart` is load-bearing: it moves the moov
+ * atom up front, which is what makes platforms' progressive/ranged fetches
+ * work (LinkedIn's 206 consumer was the victim of a tail-moov master).
+ */
+export async function encodeDelivery(
+  tools: IngestTools,
+  src: { path: string; width: number; height: number },
+  dest: string,
+  plan: DeliveryPlan,
+  opts: { onProgress?: (p: FfmpegProgress) => void } = {},
+): Promise<void> {
+  const scaling = plan.width !== src.width || plan.height !== src.height;
+  // ffmpeg's -progress stream vs. chunk boundaries: a data event can split a
+  // line mid-value ("out_time_us=12" + "345\n" parses as the wrong number),
+  // so only complete lines reach the parser and the tail carries over. The
+  // merged latest goes out per chunk — undefined never overwrites a value
+  // already seen.
+  let carry = "";
+  const latest: { outTimeSec?: number; speed?: number } = {};
+  const onStdout = (chunk: string): void => {
+    const text = carry + chunk;
+    const lastNewline = text.lastIndexOf("\n");
+    if (lastNewline < 0) {
+      carry = text;
+      return;
+    }
+    carry = text.slice(lastNewline + 1);
+    const parsed = parseFfmpegProgress(text.slice(0, lastNewline + 1));
+    if (parsed.outTimeSec === undefined && parsed.speed === undefined) return;
+    if (parsed.outTimeSec !== undefined) latest.outTimeSec = parsed.outTimeSec;
+    if (parsed.speed !== undefined) latest.speed = parsed.speed;
+    opts.onProgress?.({ ...latest });
+  };
+  // Encode to a sibling temp path, rename only on success (R27 §125): ffmpeg
+  // writes the container header as it goes, so an encode that dies mid-run
+  // leaves a valid-looking file, and the existence-keyed cache below would
+  // reuse that corpse forever.
+  const partial = `${dest}.partial.mp4`;
+  try {
+    await run(tools.ffmpegPath, [
+      "-y", "-i", src.path,
+      // Machine-readable progress on stdout, and -nostats so the human
+      // frame-counter doesn't spam stderr alongside it.
+      "-progress", "pipe:1", "-nostats",
+      ...(scaling ? ["-vf", `scale=${plan.width}:${plan.height}`] : []),
+      "-c:v", "libx264", "-preset", "medium", "-pix_fmt", "yuv420p",
+      "-b:v", `${plan.videoBitrateKbps}k`,
+      "-maxrate", `${DELIVERY_MAX_BITRATE_KBPS}k`, "-bufsize", "20000k",
+      // The audio rate fitBitrateKbps budgets for — one constant, no drift.
+      "-c:a", "aac", "-b:a", `${DELIVERY_AUDIO_BITRATE_KBPS}k`,
+      "-movflags", "+faststart",
+      partial,
+    ], { onStdout });
+    await rename(partial, dest);
+  } catch (err) {
+    await rm(partial, { force: true });
+    throw err;
+  }
+}
+
+export interface DeliveryResult {
+  /** The file to upload: the delivery encode, or the master when no encode is needed. */
+  path: string;
+  /** True when this call ran ffmpeg (vs. skip or cache hit). */
+  encoded: boolean;
+  /** The MASTER's probe — callers need its duration for the duration caps. */
+  probe: Probe;
+}
+
+/**
+ * The delivery file for a master, encoding it on first need and caching it in
+ * the workdir. A cache hit requires the delivery file to exist AND be no
+ * older than the master: a re-render writes the same master filename, so
+ * existence alone would silently publish the PREVIOUS render's delivery
+ * encode.
+ */
+export async function ensureDeliveryFile(
+  tools: IngestTools,
+  workdir: string,
+  masterPath: string,
+  opts: {
+    onStart?: (fileName: string) => void;
+    /** Live encode progress (percent/ETA are the caller's arithmetic —
+     * both already hold the master's duration). Never fires on a skip or a
+     * cache hit, which is why the consumers keep a static fallback line. */
+    onProgress?: (p: FfmpegProgress) => void;
+    /**
+     * Per-platform upload ceiling (`PLATFORM_SIZE_CAP_BYTES`) — the bitrate
+     * fits under it, and the bitrate-bearing filename caches the capped
+     * variant BESIDE the default one (delivery-1920x1080@10000k.mp4 and
+     * @2106k.mp4 coexist), so a multi-platform publish encodes each at most
+     * once.
+     */
+    sizeCapBytes?: number;
+  } = {},
+): Promise<DeliveryResult> {
+  const [masterProbe, masterStat] = await Promise.all([probe(tools, masterPath), stat(masterPath)]);
+  const plan = deliveryEncodePlan(
+    {
+      width: masterProbe.width,
+      height: masterProbe.height,
+      fps: masterProbe.fps,
+      duration: masterProbe.duration,
+      sizeBytes: masterStat.size,
+    },
+    { sizeCapBytes: opts.sizeCapBytes },
+  );
+  if (!plan) return { path: masterPath, encoded: false, probe: masterProbe };
+  if ("unattainable" in plan) {
+    // A throw, not a silent fallback: falling back to the 10 Mbps file would
+    // re-run the exact 2207077 failure the cap exists to prevent. Callers
+    // that want to refuse the channel gracefully pre-check with the pure
+    // deliveryEncodePlan before spending an encode.
+    throw new Error(
+      `a ${opts.sizeCapBytes} byte cap needs ~${plan.fittedKbps} kbps for ` +
+        `${Math.round(masterProbe.duration)}s of video — under the ` +
+        `${DELIVERY_MIN_VIDEO_BITRATE_KBPS} kbps quality floor; the video is too long for this platform's size cap`,
+    );
+  }
+  const deliveryPath = join(workdir, plan.fileName);
+  if (existsSync(deliveryPath)) {
+    const deliveryStat = await stat(deliveryPath);
+    if (deliveryStat.mtimeMs >= masterStat.mtimeMs) {
+      return { path: deliveryPath, encoded: false, probe: masterProbe };
+    }
+  }
+  opts.onStart?.(plan.fileName);
+  await encodeDelivery(
+    tools,
+    { path: masterPath, width: masterProbe.width, height: masterProbe.height },
+    deliveryPath,
+    plan,
+    { onProgress: opts.onProgress },
+  );
+  return { path: deliveryPath, encoded: true, probe: masterProbe };
+}

package/src/publish/index.ts

@@ -1,3 +1,6 @@
 export * from "./provider";
 export * from "./captions";
+export * from "./delivery";
+export * from "./limits";
 export * from "./postiz";
+export * from "./progress";

package/src/publish/limits.ts

@@ -0,0 +1,52 @@
+import type { PublishTarget } from "./provider";
+
+/**
+ * Per-platform video duration caps, by the provider identifier the backend
+ * reports (the `CAPTION_CAPS` shape, applied to duration). Only platforms
+ * with a cap under long-form appear; absence means unlimited — a wrong
+ * refusal is worse than a platform error, so an unknown provider is never
+ * capped (2026-08-29 handoff: the 5:20 take was doomed on Threads' 5:00 cap
+ * before a single byte uploaded).
+ */
+export const PLATFORM_DURATION_CAPS_SEC: Record<string, number> = {
+  threads: 300,
+  tiktok: 600,
+  instagram: 900,
+};
+
+/**
+ * Per-platform upload size caps, in bytes, same shape and posture as the
+ * duration caps: absence means uncapped, because a wrong refusal is worse
+ * than a platform error. The Instagram number is empirical (2026-08-29,
+ * live): its URL-fetch ingest rejected the 409MB 10 Mbps delivery file with
+ * error 2207077 TWICE, then published the very same 1080p landscape take at
+ * 88MB (2 Mbps, same 192k audio) — the ceiling sits around 100MB, and 95MB
+ * leaves margin under it. LinkedIn took the 409MB file fine the same day, so
+ * capped platforms get their own smaller encode and everyone else keeps the
+ * 10 Mbps file.
+ */
+export const PLATFORM_SIZE_CAP_BYTES: Record<string, number> = {
+  instagram: 95_000_000,
+};
+
+export interface DurationViolation {
+  target: PublishTarget;
+  capSec: number;
+}
+
+/**
+ * The targets this video is too long for. Semantics downstream: refuse the
+ * violating channels, publish the rest — the platform hard-fails an over-cap
+ * upload anyway, so there is no `--force` for duration.
+ */
+export function checkDurationCaps(targets: PublishTarget[], durationSec: number): DurationViolation[] {
+  const violations: DurationViolation[] = [];
+  for (const target of targets) {
+    const capSec = PLATFORM_DURATION_CAPS_SEC[target.provider];
+    // Strictly over: a video exactly at the cap is what the cap permits.
+    if (capSec !== undefined && durationSec > capSec) {
+      violations.push({ target, capSec });
+    }
+  }
+  return violations;
+}

package/src/publish/postiz.ts

@@ -68,26 +68,88 @@ export function parseIntegrations(json: unknown): PublishTarget[] {
  * sends the minimum and surfaces Postiz's errors verbatim rather than
  * duplicating (and drifting from) that matrix. YouTube is the one platform
  * whose settings carry a required title, so a post's `title` passes through.
+ *
+ * Media comes in two shapes because posts can carry per-post files now
+ * (2026-08-29: Instagram's size cap gets its own smaller encode, everyone
+ * else shares the default — `PublishPost.videoPath`): a single upload keeps
+ * the original one-file contract for callers with no per-post media (the
+ * CLI's dry-run placeholder included), while the map form pairs every
+ * distinct `videoPath` with its upload and REQUIRES the default path the
+ * lookup falls back to — the union makes forgetting it a type error, not a
+ * runtime surprise.
  */
-export function buildPostsPayload(args: {
-  posts: PublishPost[];
-  when: PublishWhen;
-  dateIso: string;
-  media: PostizUpload;
-}): Record<string, unknown> {
-  const image = [{ id: args.media.id, path: args.media.path }];
+export type PostsPayloadMedia =
+  | { media: PostizUpload; defaultVideoPath?: undefined }
+  | { media: ReadonlyMap<string, PostizUpload>; defaultVideoPath: string };
+
+export function buildPostsPayload(
+  args: {
+    posts: PublishPost[];
+    when: PublishWhen;
+    dateIso: string;
+  } & PostsPayloadMedia,
+): Record<string, unknown> {
+  // instanceof on the property does not narrow the sibling `defaultVideoPath`
+  // through the union, so split the two shapes once up front.
+  const byPath = args.media instanceof Map ? (args.media as ReadonlyMap<string, PostizUpload>) : null;
+  const single = byPath === null ? (args.media as PostizUpload) : null;
+  const uploadFor = (p: PublishPost): PostizUpload => {
+    if (single !== null) {
+      // Single-upload shape: there is no path→upload pairing to consult, so a
+      // post asking for its own file would silently get the WRONG video —
+      // worse than any throw (2207077 at least fails; a LinkedIn post carrying
+      // the Instagram encode publishes).
+      if (p.videoPath !== undefined) {
+        throw new Error(
+          `post for ${p.target.provider} carries its own videoPath but buildPostsPayload got a single upload — pass the media map`,
+        );
+      }
+      return single;
+    }
+    const path = p.videoPath ?? args.defaultVideoPath;
+    const upload = path === undefined ? undefined : byPath!.get(path);
+    // publish() derives its upload set from the same `p.videoPath ??
+    // default` expression, so a miss is a caller bug — but see above: wrong
+    // video beats no video for worst outcome.
+    if (upload === undefined) throw new Error(`no upload for media path ${path}`);
+    return upload;
+  };
   return {
     type: args.when.kind === "now" ? "now" : "schedule",
     date: args.when.kind === "at" ? args.when.iso : args.dateIso,
     shortLink: false,
-    posts: args.posts.map((p) => ({
-      integration: { id: p.target.id },
-      value: [{ content: p.caption, image }],
-      settings: {
-        __type: p.target.provider,
-        ...(p.title !== undefined ? { title: p.title } : {}),
-      },
-    })),
+    // Required by /posts' DTO as a top-level array ("tags should not be null
+    // or undefined" — the 2026-08-27 live E2E's first real request bounced on
+    // it). Always empty: calendar tags are a Postiz-UI concept ossclip has no
+    // gesture for.
+    tags: [],
+    posts: args.posts.map((p) => {
+      const upload = uploadFor(p);
+      return {
+        integration: { id: p.target.id },
+        value: [{ content: p.caption, image: [{ id: upload.id, path: upload.path }] }],
+        settings: {
+          __type: p.target.provider,
+          ...(p.title !== undefined ? { title: p.title } : {}),
+          // YouTube's privacy status is REQUIRED by Postiz's DTO (`type`,
+          // @IsDefined) — without it the whole /posts call is rejected at
+          // validation and nothing publishes, not just the YouTube post
+          // (2026-08-28). `private` is the default on purpose: the other
+          // platforms post publicly, but an accidental `--all` must not push to
+          // a subscriber list, and making a private video public in YouTube
+          // Studio is one click where un-publishing is not.
+          ...(p.target.provider === "youtube"
+            ? { type: p.youtubePrivacy ?? "private" }
+            : {}),
+          // Instagram's own required setting (`post_type`, @IsDefined — the
+          // second one a real publish found, at the same cost: a 400 AFTER the
+          // whole video had uploaded). Always `post`: ossclip renders a
+          // finished short, and a story expires in 24 hours, which nobody
+          // publishing a produced video is asking for.
+          ...(p.target.provider === "instagram" ? { post_type: "post" } : {}),
+        },
+      };
+    }),
   };
 }
 
@@ -132,7 +194,14 @@ export class PostizHttpError extends Error {
       status === 401 || status === 403
         ? " — Postiz rejected the API key (Settings → Public API in your Postiz instance)"
         : status === 413
-          ? " — the upload exceeds the Postiz instance's size limit"
+          ? // Usually NOT Postiz: a reverse proxy in front of it refuses the
+            // body first (Cloudflare's free plan caps a proxied upload at
+            // 100MB — a 171MB render bounced on it during the 2026-08-27 live
+            // E2E, with Cloudflare's own HTML as the "Postiz" answer). Name the
+            // proxy and the way through, since tuning Postiz would do nothing.
+            " — the upload was refused as too large. A reverse proxy in front of Postiz is the" +
+            " usual cause (Cloudflare's free plan caps proxied uploads at 100MB); point" +
+            " postizUrl at the instance directly (its LAN/VPN address) or raise the proxy's limit"
           : status === 429
             ? " — Postiz rate limit (90 posts/hour per self-hosted instance)"
             : "";
@@ -192,20 +261,38 @@ export function createPostizProvider(opts: PostizProviderOptions): PublishProvid
       return parseIntegrations(await request("GET", "/integrations"));
     },
     async publish(req: PublishRequest): Promise<PublishReceipt> {
-      // openAsBlob streams the file into multipart form-data without ever
-      // holding the whole video in memory — a rendered short is routinely
-      // hundreds of MB, and a string/Buffer round-trip would double it.
       const { openAsBlob } = await import("node:fs");
-      const blob = await openAsBlob(req.videoPath, { type: "video/mp4" });
-      const form = new FormData();
-      form.append("file", blob, basename(req.videoPath));
-      const media = PostizUploadSchema.parse(await request("POST", "/upload", form));
+      // Each DISTINCT file uploads exactly once: a size-capped platform
+      // carries its own smaller encode (`PublishPost.videoPath`, 2026-08-29)
+      // while the rest share the request default, and posts then map to
+      // their own media in the payload. Sequential on purpose — uploads are
+      // hundreds of MB, and parallelism buys contention, not time.
+      const paths = [...new Set(req.posts.map((p) => p.videoPath ?? req.videoPath))];
+      const uploads = new Map<string, PostizUpload>();
+      for (const path of paths) {
+        // openAsBlob streams the file into multipart form-data without ever
+        // holding the whole video in memory — a rendered short is routinely
+        // hundreds of MB, and a string/Buffer round-trip would double it.
+        const blob = await openAsBlob(path, { type: "video/mp4" });
+        const form = new FormData();
+        form.append("file", blob, basename(path));
+        try {
+          uploads.set(path, PostizUploadSchema.parse(await request("POST", "/upload", form)));
+        } catch (err) {
+          // "POST /upload failed" alone no longer says WHICH file when
+          // several are in flight — name it.
+          throw new Error(
+            `${err instanceof Error ? err.message : String(err)}\n(while uploading ${path})`,
+          );
+        }
+      }
 
       const payload = buildPostsPayload({
         posts: req.posts,
         when: req.when,
         dateIso: new Date().toISOString(),
-        media,
+        media: uploads,
+        defaultVideoPath: req.videoPath,
       });
       let answer: unknown;
       try {
@@ -215,9 +302,10 @@ export function createPostizProvider(opts: PostizProviderOptions): PublishProvid
       } catch (err) {
         // The media is already up — say so, so a retry is one request, not
         // a re-upload of the whole video.
+        const ids = [...uploads.values()].map((u) => u.id).join(", ");
         throw new Error(
           `${err instanceof Error ? err.message : String(err)}\n` +
-            `(the video uploaded fine — media id ${media.id}; retrying will re-upload it)`,
+            `(the video uploaded fine — media id ${ids}; retrying will re-upload it)`,
         );
       }
       return {

package/src/publish/progress.ts

@@ -0,0 +1,75 @@
+/**
+ * Encode progress for the delivery encode (2026-08-29): a real 5-minute video
+ * spends minutes in x264 with zero feedback — the CLI line and the editor
+ * panel both need percent + ETA, so the parsing lives here, pure, where both
+ * can reach it.
+ *
+ * ffmpeg's `-progress pipe:1` emits key=value lines on stdout roughly twice a
+ * second; this module turns those into { outTimeSec, speed } and the ETA
+ * arithmetic. No spawning here — encodeDelivery owns the ffmpeg call.
+ */
+
+export interface FfmpegProgress {
+  /** How far into the OUTPUT the encode is, in seconds. */
+  outTimeSec?: number;
+  /** Encode speed as a multiple of realtime (`speed=1.53x` → 1.53). */
+  speed?: number;
+}
+
+/**
+ * Parse a chunk of ffmpeg's `-progress` key=value stream. Returns the LAST
+ * value seen per key in this chunk — the stream repeats the block every
+ * ~500ms, and only the newest matters. `N/A` values (the first block, before
+ * ffmpeg has numbers) are ignored, and unparseable text yields nothing rather
+ * than a guess. The caller keeps a running latest across chunks; feeding only
+ * complete lines is also the caller's job (a chunk boundary can split a line
+ * mid-value, and half a number parses as the wrong number).
+ */
+export function parseFfmpegProgress(chunk: string): FfmpegProgress {
+  const out: FfmpegProgress = {};
+  for (const line of chunk.split(/\r?\n/)) {
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    if (value.length === 0 || value === "N/A") continue;
+    // out_time_us preferred; out_time_ms is ALSO microseconds despite the
+    // name (long-standing ffmpeg quirk — trusting the name would report a
+    // 1000x-too-long encode), out_time is the HH:MM:SS.xx spelling.
+    if (key === "out_time_us" || key === "out_time_ms") {
+      const us = Number(value);
+      if (Number.isFinite(us) && us >= 0) out.outTimeSec = us / 1_000_000;
+    } else if (key === "out_time") {
+      const m = /^(\d+):(\d{1,2}):(\d{1,2}(?:\.\d+)?)$/.exec(value);
+      if (m !== null) {
+        out.outTimeSec = Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3]);
+      }
+    } else if (key === "speed") {
+      const n = Number(value.replace(/x$/i, ""));
+      if (Number.isFinite(n) && n >= 0) out.speed = n;
+    }
+  }
+  return out;
+}
+
+/**
+ * Seconds of encode left: (duration − done) / speed. Null when speed ≤ 0 —
+ * a division by ffmpeg's warm-up `speed=0x` would print "Infinity left".
+ * Clamped at 0: out_time can overshoot the probed duration at the tail
+ * (muxer flush), and a negative ETA reads as nonsense.
+ */
+export function encodeEta(durationSec: number, outTimeSec: number, speed: number): number | null {
+  if (speed <= 0) return null;
+  return Math.max(0, (durationSec - outTimeSec) / speed);
+}
+
+/**
+ * Seconds → "5:20". Lived in the CLI's publish.ts first (duration-cap
+ * messages); moved here so the progress lines on both sides of the wire spell
+ * time the same way — the CLI re-exports it, the panel keeps its own copy for
+ * the documented Vite-bundle reason.
+ */
+export function formatMinSec(sec: number): string {
+  const whole = Math.round(sec);
+  return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}

package/src/publish/provider.ts

@@ -27,10 +27,33 @@ export interface PublishPost {
    * Optional — most don't.
    */
   title?: string;
+  /**
+   * YouTube's privacy status — REQUIRED by Postiz's own DTO (`type`,
+   * @IsDefined), so a YouTube post without it fails validation and takes the
+   * whole /posts call with it (2026-08-28). Optional here because only
+   * YouTube has the concept; `buildPostsPayload` supplies the default.
+   */
+  youtubePrivacy?: "public" | "unlisted" | "private";
+  /**
+   * This post's media, when it must differ from the request's default
+   * `videoPath`. Size-capped platforms are the reason it exists (2026-08-29,
+   * live: Instagram bounced the 409MB delivery file with 2207077 but
+   * published the 88MB re-encode — `PLATFORM_SIZE_CAP_BYTES`): they carry
+   * their own smaller encode while everyone else keeps the 10 Mbps file.
+   * Each distinct file uploads once; posts map to their media.
+   */
+  videoPath?: string;
 }
 
 export interface PublishRequest {
-  /** Absolute path of the rendered video. */
+  /**
+   * Absolute path of the default media — the delivery encode, or the master
+   * when none is needed (`ensureDeliveryFile`). A post whose platform needs
+   * a different file sets its own `PublishPost.videoPath`; the provider
+   * uploads each distinct file once and maps posts to their media. Sending
+   * the MASTER to YouTube via that mechanism remains the noted follow-up
+   * (2026-08-29 plan).
+   */
   videoPath: string;
   posts: PublishPost[];
   when: PublishWhen;

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/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;
 }