@ossclip/core 0.1.33 → 0.1.35

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;