@ossclip/core 0.1.31 → 0.1.34

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/producer/youtube.ts

@@ -30,7 +30,7 @@ import { cappedText } from "./beats";
  * changes the answer, so the Y2 pack cache key carries this (the §78
  * cache-key posture) — an old cached pack must not survive a new prompt.
  */
-export const YOUTUBE_PROMPT_VERSION = "v2";
+export const YOUTUBE_PROMPT_VERSION = "v3";
 
 export const YoutubeChapterSchema = z.object({
   /** Output-timeline seconds — the produced video's clock, not the source's. */
@@ -72,6 +72,22 @@ export const YoutubePackSchema = z.object({
   linkedinPost: cappedText(1500).optional(),
   /** A short YouTube community post for existing subscribers. Optional. */
   communityPost: cappedText(400).optional(),
+  /**
+   * Ready-to-post captions for the other short-video platforms (prompt v3,
+   * 2026-08-26), written by the same call that already has the transcript
+   * and audience in context — a publish step that derived these from titles
+   * would ship title-spam as its ceiling. Every field optional: pre-v3
+   * approved packs must keep parsing verbatim forever, and `deriveCaption`
+   * (publish/captions.ts) fills any gap deterministically at publish time.
+   */
+  platformCaptions: z
+    .object({
+      instagram: cappedText(2200).optional(),
+      tiktok: cappedText(2200).optional(),
+      x: cappedText(280).optional(),
+      facebook: cappedText(2200).optional(),
+    })
+    .optional(),
 });
 export type YoutubePack = z.infer<typeof YoutubePackSchema>;
 
@@ -295,7 +311,13 @@ export function buildYoutubePrompt(args: YoutubePromptArgs): { system: string; u
     "- linkedinPost: a story-driven LinkedIn post about this video: short lines with line " +
     "breaks, a curiosity gap, no hashtag spam, ending by pointing to the link in the comments " +
     "(the LinkedIn convention for off-platform links).\n" +
-    "- communityPost: a short, casual YouTube community post for existing subscribers.";
+    "- communityPost: a short, casual YouTube community post for existing subscribers.\n" +
+    "- platformCaptions: ready-to-post captions for the OTHER platforms this short goes to, " +
+    "each written for that platform's culture, not copies of each other: \"instagram\" — a " +
+    "hook line, short scannable lines, 3-5 hashtags at the end (max 2200 chars); \"tiktok\" — " +
+    "casual and direct, 2-4 hashtags (max 2200 chars); \"x\" — ONE punchy post, max 280 " +
+    "characters INCLUDING hashtags, no link (links go in a reply); \"facebook\" — " +
+    "conversational, a question or hook up front, minimal hashtags (max 2200 chars).";
   const capped =
     args.transcriptText.length > YOUTUBE_TRANSCRIPT_CHAR_CAP
       ? // Slice + say so: the model must know it is reading an excerpt, or it
@@ -430,5 +452,17 @@ export function formatYoutubeMarkdown(
   if (pack.hook60) lines.push("", "## First-60s hook strategy", "", pack.hook60.trimEnd());
   if (pack.linkedinPost) lines.push("", "## LinkedIn post", "", pack.linkedinPost.trimEnd());
   if (pack.communityPost) lines.push("", "## Community post", "", pack.communityPost.trimEnd());
+  const captions = pack.platformCaptions;
+  if (captions) {
+    const order = [
+      ["Instagram", captions.instagram],
+      ["TikTok", captions.tiktok],
+      ["X", captions.x],
+      ["Facebook", captions.facebook],
+    ] as const;
+    for (const [label, text] of order) {
+      if (text) lines.push("", `## ${label} caption`, "", text.trimEnd());
+    }
+  }
   return `${lines.join("\n")}\n`;
 }

package/src/publish/captions.ts

@@ -0,0 +1,102 @@
+import type { YoutubePack } from "../producer/youtube";
+
+/**
+ * Per-platform caption resolution for `ossclip publish`.
+ *
+ * The pack is the author: prompt v3 writes `platformCaptions` (and v2 already
+ * wrote `linkedinPost`) with the transcript and audience in context. This
+ * module only PICKS from the pack — and, for a pre-v3 pack that never carried
+ * a platform's caption, derives one deterministically from the fields every
+ * pack has. No LLM call at publish time: publishing must work offline-from-LLM
+ * and produce the same caption every run.
+ */
+
+/** Platform caption caps, by the provider identifier the backend reports. */
+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,
+  youtube: 5000,
+};
+
+/** The cap for an unknown provider — the smallest common long-form cap. */
+export const DEFAULT_CAPTION_CAP = 1500;
+
+export function captionCap(provider: string): number {
+  return CAPTION_CAPS[provider] ?? DEFAULT_CAPTION_CAP;
+}
+
+/**
+ * Word-boundary truncation to `max`: never slice mid-word, drop the partial
+ * word instead. A caption a few words shorter beats one ending "communi".
+ */
+export function truncateAtWordBoundary(text: string, max: number): string {
+  const trimmed = text.trim();
+  if (trimmed.length <= max) return trimmed;
+  const slice = trimmed.slice(0, max);
+  const lastSpace = slice.lastIndexOf(" ");
+  return (lastSpace > 0 ? slice.slice(0, lastSpace) : slice).trimEnd();
+}
+
+/**
+ * Fallback caption when the pack carries none for this provider: the first
+ * title (the strongest line the pack has) plus the hashtags, capped. This is
+ * deliberately the floor, not the ceiling — the prompt-v3 `platformCaptions`
+ * exist because title-plus-hashtags is what every paste-tool ships.
+ */
+export function deriveCaption(pack: YoutubePack, provider: string): string {
+  const title = pack.titles[0] ?? "";
+  const hashtags = pack.hashtags.map((h) => (h.startsWith("#") ? h : `#${h}`)).join(" ");
+  const joined = hashtags.length > 0 ? `${title}\n\n${hashtags}` : title;
+  return truncateAtWordBoundary(joined, captionCap(provider));
+}
+
+/**
+ * The caption `publish` uses for a target: the pack's own field for that
+ * platform when present (still capped — an approved pack is user data, and
+ * user data gets validated, not trusted), else the derived fallback.
+ */
+export function captionForProvider(pack: YoutubePack, provider: string): string {
+  const captions = pack.platformCaptions;
+  const authored =
+    // `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
+      : // 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
+          : provider === "x"
+            ? captions?.x
+            : provider === "facebook"
+              ? captions?.facebook
+              : undefined;
+  if (authored !== undefined && authored.trim().length > 0) {
+    return truncateAtWordBoundary(authored, captionCap(provider));
+  }
+  return deriveCaption(pack, provider);
+}

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

@@ -0,0 +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;
+}