@bendyline/squisq-cli 2.8.9 → 2.8.10

package/dist/api.js

@@ -4,15 +4,18 @@ import {
   framesToGifNativeBytes,
   framesToMp4Native,
   framesToMp4NativeBytes,
+  lastMeaningfulFfmpegLine,
   runFfmpeg
-} from "./chunk-Z3BHD4AF.js";
+} from "./chunk-RQSP3OPR.js";
 
 // src/api.ts
-import { mkdir, readFile as readFile3, writeFile } from "fs/promises";
-import { dirname as dirname2, resolve as resolvePath } from "path";
+import { randomBytes as randomBytes2 } from "crypto";
+import { mkdir as mkdir2, readFile as readFile4, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { dirname as dirname2, join as join4, resolve as resolvePath } from "path";
 import { resolveMediaSchedule as resolveMediaSchedule2 } from "@bendyline/squisq/schemas";
 import { flattenBlocks as flattenBlocks2 } from "@bendyline/squisq/doc";
-import { ffmpegGifOutputArgs, generateRenderHtml } from "@bendyline/squisq-video";
+import { ffmpegGifOutputArgs, frameTimeSeconds, generateRenderHtml } from "@bendyline/squisq-video";
 import { resolveDashboardDimensions, resolveDimensions } from "@bendyline/squisq-video";
 import {
   convert as formatsConvert,
@@ -135,13 +138,13 @@ function round3(n) {
   return Math.round(n * 1e3) / 1e3;
 }
 async function mixTimelineClips(ffmpegPath, usable, signal) {
-  const { writeFile: writeFile2, readFile: readFile4, mkdir: mkdir2, rm: rm2 } = await import("fs/promises");
-  const { join: join3 } = await import("path");
-  const { tmpdir: tmpdir2 } = await import("os");
-  const { randomBytes: randomBytes2 } = await import("crypto");
+  const { writeFile: writeFile3, readFile: readFile5, mkdir: mkdir3, rm: rm3 } = await import("fs/promises");
+  const { join: join5 } = await import("path");
+  const { tmpdir: tmpdir3 } = await import("os");
+  const { randomBytes: randomBytes3 } = await import("crypto");
   signal?.throwIfAborted();
-  const workDir = join3(tmpdir2(), `squisq-audio-mix-${randomBytes2(8).toString("hex")}`);
-  await mkdir2(workDir, { recursive: true });
+  const workDir = join5(tmpdir3(), `squisq-audio-mix-${randomBytes3(8).toString("hex")}`);
+  await mkdir3(workDir, { recursive: true });
   try {
     signal?.throwIfAborted();
     const inputs = [];
@@ -149,15 +152,15 @@ async function mixTimelineClips(ffmpegPath, usable, signal) {
     const labels = [];
     for (const { clip, buffer } of usable) {
       signal?.throwIfAborted();
-      const p = join3(workDir, `clip-${inputs.length}.mp3`);
-      await writeFile2(p, new Uint8Array(buffer));
+      const p = join5(workDir, `clip-${inputs.length}.mp3`);
+      await writeFile3(p, new Uint8Array(buffer));
       signal?.throwIfAborted();
       const i = inputs.push(p) - 1;
       filters.push(`[${i}:a]${clipFilterChain(clip)}[a${i}]`);
       labels.push(`[a${i}]`);
     }
     const graph = `${filters.join(";")};${labels.join("")}amix=inputs=${labels.length}:normalize=0:dropout_transition=0[aout]`;
-    const outputPath = join3(workDir, "mixed.mp3");
+    const outputPath = join5(workDir, "mixed.mp3");
     const args = ["-y"];
     for (const p of inputs) args.push("-i", p);
     args.push(
@@ -177,11 +180,11 @@ async function mixTimelineClips(ffmpegPath, usable, signal) {
       signal
     });
     signal?.throwIfAborted();
-    const data = await readFile4(outputPath);
+    const data = await readFile5(outputPath);
     signal?.throwIfAborted();
     return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
   } finally {
-    await rm2(workDir, { recursive: true, force: true });
+    await rm3(workDir, { recursive: true, force: true });
   }
 }
 
@@ -324,11 +327,188 @@ function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
 
+// src/util/frameSink.ts
+import { spawn } from "child_process";
+import { createHash } from "crypto";
+import { once } from "events";
+import { access, mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { isDeepStrictEqual } from "util";
+import {
+  audioBitrateArg,
+  ffmpegAudioMuxArgs,
+  ffmpegVideoQualityArgs
+} from "@bendyline/squisq-video";
+function ffmpegPipeArgs(options) {
+  const { outputPath, fps, width, height, quality, captureFormat, audioPath } = options;
+  const args = [
+    "-y",
+    "-f",
+    "image2pipe",
+    "-framerate",
+    String(fps),
+    "-c:v",
+    captureFormat === "jpeg" ? "mjpeg" : "png",
+    "-i",
+    "pipe:0"
+  ];
+  if (audioPath) args.push("-i", audioPath);
+  const range = captureFormat === "jpeg" ? ":in_range=pc:out_range=tv" : "";
+  args.push(
+    "-c:v",
+    "libx264",
+    ...ffmpegVideoQualityArgs(quality),
+    "-pix_fmt",
+    "yuv420p",
+    "-color_range",
+    "tv",
+    "-vf",
+    `scale=${width}:${height}:force_original_aspect_ratio=decrease${range},pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2`
+  );
+  if (audioPath) args.push(...ffmpegAudioMuxArgs(audioBitrateArg(quality)));
+  args.push("-movflags", "+faststart", outputPath);
+  return args;
+}
+var STDERR_TAIL_LINES = 200;
+var IDLE_POLL_MS = 5e3;
+function createFfmpegPipeSink(options) {
+  const { ffmpegPath, signal, idleTimeoutMs = 12e4 } = options;
+  const child = spawn(ffmpegPath, ffmpegPipeArgs(options), {
+    stdio: ["pipe", "ignore", "pipe"]
+  });
+  const stderrTail = [];
+  let lastActivity = Date.now();
+  let failure = null;
+  let frames = 0;
+  let exitCode;
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    lastActivity = Date.now();
+    for (const line of chunk.split(/\r?\n|\r/)) {
+      if (!line.trim()) continue;
+      stderrTail.push(line);
+      if (stderrTail.length > STDERR_TAIL_LINES) stderrTail.shift();
+    }
+  });
+  child.on("error", (err) => {
+    failure ??= err;
+  });
+  child.stdin.on("error", (err) => {
+    failure ??= err;
+  });
+  const exited = new Promise((resolve2) => {
+    child.on("exit", (code) => {
+      exitCode = code;
+      resolve2();
+    });
+    child.on("error", () => resolve2());
+  });
+  const idleTimer = setInterval(() => {
+    if (Date.now() - lastActivity > idleTimeoutMs) {
+      failure ??= new Error(`ffmpeg produced no output for ${Math.round(idleTimeoutMs / 1e3)}s`);
+      child.kill("SIGKILL");
+    }
+  }, IDLE_POLL_MS);
+  idleTimer.unref();
+  const onAbort = () => {
+    child.kill("SIGKILL");
+  };
+  signal?.addEventListener("abort", onAbort, { once: true });
+  const cleanup = () => {
+    clearInterval(idleTimer);
+    signal?.removeEventListener("abort", onAbort);
+  };
+  const describeFailure = () => {
+    const detail = lastMeaningfulFfmpegLine(stderrTail.join("\n"));
+    if (failure && failure.code === "ENOENT") {
+      return "the ffmpeg binary could not be started (ENOENT). Run `squisq doctor` to check your FFmpeg installation.";
+    }
+    const head = failure ? failure.message : exitCode === void 0 ? "ffmpeg exited unexpectedly" : `ffmpeg exited unsuccessfully (exit code ${exitCode})`;
+    return detail ? `${head} (last output: ${detail})` : head;
+  };
+  const throwIfDead = () => {
+    signal?.throwIfAborted();
+    if (failure || exitCode !== void 0) {
+      throw new Error(`ffmpeg failed: ${describeFailure()}`);
+    }
+  };
+  return {
+    get frameCount() {
+      return frames;
+    },
+    async write(frame, repeat = 1) {
+      if (!Number.isSafeInteger(repeat) || repeat < 1) {
+        throw new Error("Frame repetition count must be a positive integer");
+      }
+      throwIfDead();
+      for (let i = 0; i < repeat; i += 1) {
+        lastActivity = Date.now();
+        if (!child.stdin.write(frame)) {
+          await Promise.race([once(child.stdin, "drain").catch(() => void 0), exited]);
+        }
+        throwIfDead();
+        frames += 1;
+      }
+    },
+    async finish() {
+      throwIfDead();
+      child.stdin.end();
+      await exited;
+      cleanup();
+      signal?.throwIfAborted();
+      if (failure || exitCode !== 0) throw new Error(`ffmpeg failed: ${describeFailure()}`);
+    },
+    async abort() {
+      cleanup();
+      if (exitCode === void 0) child.kill("SIGKILL");
+      await exited;
+    }
+  };
+}
+function docRenderHash(doc) {
+  return createHash("sha256").update(JSON.stringify(doc)).digest("hex");
+}
+var MANIFEST_NAME = "manifest.json";
+async function openDirectoryFrameStore(dir, manifest, resume) {
+  await mkdir(dir, { recursive: true });
+  const manifestPath = join(dir, MANIFEST_NAME);
+  let existing = null;
+  try {
+    existing = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch {
+    existing = null;
+  }
+  const reusable = resume && existing !== null && isDeepStrictEqual(existing, manifest);
+  if (!reusable) await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  const extension = manifest.captureFormat === "jpeg" ? "jpg" : "png";
+  const path = (index) => join(dir, `frame-${String(index).padStart(6, "0")}.${extension}`);
+  return {
+    dir,
+    reusable,
+    path,
+    async has(index) {
+      try {
+        await access(path(index));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    async read(index) {
+      const bytes = await readFile(path(index));
+      return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    },
+    async write(index, frame) {
+      await writeFile(path(index), frame);
+    }
+  };
+}
+
 // src/registry.ts
 import { randomBytes } from "crypto";
-import { readFile, rm } from "fs/promises";
+import { readFile as readFile2, rm } from "fs/promises";
 import { tmpdir } from "os";
-import { join } from "path";
+import { join as join2 } from "path";
 import { defaultRegistry } from "@bendyline/squisq-formats";
 var MP4_DEFAULTS = {
   fps: 30,
@@ -363,7 +543,7 @@ function mp4Format() {
       const orientation = typeof mp4Opts.orientation === "string" ? mp4Opts.orientation : MP4_DEFAULTS.orientation;
       const coverPreRoll = typeof mp4Opts.coverPreRoll === "number" ? mp4Opts.coverPreRoll : MP4_DEFAULTS.coverPreRoll;
       const animationsEnabled = typeof mp4Opts.animationsEnabled === "boolean" ? mp4Opts.animationsEnabled : MP4_DEFAULTS.animationsEnabled;
-      const outputPath = join(tmpdir(), `squisq-mp4-${randomBytes(8).toString("hex")}.mp4`);
+      const outputPath = join2(tmpdir(), `squisq-mp4-${randomBytes(8).toString("hex")}.mp4`);
       try {
         const { renderDocToMp4: renderDocToMp42 } = await import("./api.js");
         await renderDocToMp42(input.doc, input.container, {
@@ -380,7 +560,7 @@ function mp4Format() {
           onProgress: mp4Opts.onProgress
         });
         options.signal?.throwIfAborted();
-        const data = await readFile(outputPath, { signal: options.signal });
+        const data = await readFile2(outputPath, { signal: options.signal });
         options.signal?.throwIfAborted();
         const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
         return { bytes, mimeType: "video/mp4", suggestedFilename: "", warnings: [] };
@@ -404,7 +584,7 @@ function gifFormat() {
       const portrait = orientation === "portrait";
       const defaultWidth = portrait ? GIF_DEFAULTS.height : GIF_DEFAULTS.width;
       const defaultHeight = portrait ? GIF_DEFAULTS.width : GIF_DEFAULTS.height;
-      const outputPath = join(tmpdir(), `squisq-gif-${randomBytes(8).toString("hex")}.gif`);
+      const outputPath = join2(tmpdir(), `squisq-gif-${randomBytes(8).toString("hex")}.gif`);
       try {
         const { renderDocToGif: renderDocToGif2 } = await import("./api.js");
         const result = await renderDocToGif2(input.doc, input.container, {
@@ -424,7 +604,7 @@ function gifFormat() {
           onProgress: gifOpts.onProgress
         });
         options.signal?.throwIfAborted();
-        const data = await readFile(outputPath, { signal: options.signal });
+        const data = await readFile2(outputPath, { signal: options.signal });
         options.signal?.throwIfAborted();
         const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
         return {
@@ -478,13 +658,13 @@ function createCliRegistry() {
 import { MemoryContentContainer as MemoryContentContainer2 } from "@bendyline/squisq/storage";
 
 // src/util/readInput.ts
-import { readFile as readFile2, readdir, realpath, stat } from "fs/promises";
+import { readFile as readFile3, readdir, realpath, stat } from "fs/promises";
 import {
   basename,
   dirname,
   extname,
   isAbsolute,
-  join as join2,
+  join as join3,
   posix,
   relative,
   resolve,
@@ -550,7 +730,7 @@ async function walkDir(root, prefix = "", signal) {
     throwIfAborted(signal);
     const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
     if (entry.isDirectory()) {
-      paths.push(...await walkDir(join2(root, entry.name), relPath, signal));
+      paths.push(...await walkDir(join3(root, entry.name), relPath, signal));
     } else if (entry.isFile()) {
       paths.push(relPath);
     }
@@ -601,7 +781,7 @@ async function readArrayBuffer(filePath, signal) {
 async function readBinaryFile(filePath, signal) {
   throwIfAborted(signal);
   try {
-    const data = await readFile2(filePath, { signal });
+    const data = await readFile3(filePath, { signal });
     throwIfAborted(signal);
     return data;
   } catch (error) {
@@ -612,7 +792,7 @@ async function readBinaryFile(filePath, signal) {
 async function readUtf8File(filePath, signal) {
   throwIfAborted(signal);
   try {
-    const content = await readFile2(filePath, { encoding: "utf-8", signal });
+    const content = await readFile3(filePath, { encoding: "utf-8", signal });
     throwIfAborted(signal);
     return content;
   } catch (error) {
@@ -867,7 +1047,7 @@ async function readFolder(dirPath, signal) {
   throwIfAborted(signal);
   for (const relPath of files) {
     throwIfAborted(signal);
-    const absPath = join2(dirPath, relPath);
+    const absPath = join3(dirPath, relPath);
     const data = await readBinaryFile(absPath, signal);
     throwIfAborted(signal);
     await container.writeFile(
@@ -901,11 +1081,13 @@ import {
   validateDashboardImageDimensions
 } from "@bendyline/squisq-video";
 import { ConversionError } from "@bendyline/squisq-formats";
+var RENDER_BOOT_TIMEOUT_MS = 6e4;
+var JPEG_CAPTURE_QUALITY = 92;
 var playerBundlePromise;
 var fullPlayerBundlePromise;
 var playerIconBootstrapPromise;
 function loadPlayerIconBootstrap() {
-  playerIconBootstrapPromise ??= readFile3(
+  playerIconBootstrapPromise ??= readFile4(
     new URL("../dist/squisq-player-icons.global.js", import.meta.url),
     "utf8"
   );
@@ -914,14 +1096,14 @@ function loadPlayerIconBootstrap() {
 function loadPlayerBundle() {
   playerBundlePromise ??= Promise.all([
     loadPlayerIconBootstrap(),
-    readFile3(new URL("../dist/squisq-player.global.js", import.meta.url), "utf8")
+    readFile4(new URL("../dist/squisq-player.global.js", import.meta.url), "utf8")
   ]).then(([icons, player]) => `${icons}${player}`);
   return playerBundlePromise;
 }
 function loadFullPlayerBundle() {
   fullPlayerBundlePromise ??= Promise.all([
     loadPlayerIconBootstrap(),
-    readFile3(new URL("../dist/squisq-player.full.global.js", import.meta.url), "utf8")
+    readFile4(new URL("../dist/squisq-player.full.global.js", import.meta.url), "utf8")
   ]).then(([icons, player]) => `${icons}${player}`);
   return fullPlayerBundlePromise;
 }
@@ -1055,7 +1237,7 @@ async function withRenderPage(doc, container, options, fn) {
           const player = window.SquisqPlayer;
           return root ? player?.getHandle(root)?.getRenderAPI() != null : false;
         },
-        { timeout: 15e3 }
+        { timeout: RENDER_BOOT_TIMEOUT_MS }
       );
     } catch {
       signal?.throwIfAborted();
@@ -1063,7 +1245,7 @@ async function withRenderPage(doc, container, options, fn) {
 Page errors:
   ${pageErrors.join("\n  ")}` : "\nNo page errors captured \u2014 the player may have failed to mount.";
       throw new Error(
-        `The standalone player failed to boot in headless Chromium. Render API did not initialize within 15 seconds.${errorDetail}`
+        `The standalone player failed to boot in headless Chromium. Render API did not initialize within ${RENDER_BOOT_TIMEOUT_MS / 1e3} seconds.${errorDetail}`
       );
     }
     renderAPI = await page.evaluateHandle(() => {
@@ -1074,6 +1256,13 @@ Page errors:
       return api;
     });
     signal?.throwIfAborted();
+    const mounted = await renderAPI.evaluate((api) => api.getViewport ? api.getViewport() : null);
+    signal?.throwIfAborted();
+    if (mounted && (mounted.width !== width || mounted.height !== height)) {
+      throw new Error(
+        `The player composed a ${mounted.width}x${mounted.height} viewport for a ${width}x${height} render; the output would be letterboxed. Rebuild the CLI player bundle (npm run build:cli) so the render page can pin its viewport.`
+      );
+    }
     return await fn({ page, renderAPI });
   } finally {
     signal?.removeEventListener("abort", handleAbort);
@@ -1081,10 +1270,7 @@ Page errors:
     await browser.close().catch(() => void 0);
   }
 }
-async function captureDocFrames(doc, container, options) {
-  const { fps, width, height, captionStyle, coverPreRoll, animationsEnabled, onProgress, signal } = options;
-  signal?.throwIfAborted();
-  resolveAppliedCoverPreRoll(coverPreRoll, true);
+async function requireFfmpeg(signal) {
   const ffmpegPath = (await detectFfmpegDetailed(signal))?.path ?? null;
   signal?.throwIfAborted();
   if (!ffmpegPath) {
@@ -1092,53 +1278,87 @@ async function captureDocFrames(doc, container, options) {
       "ffmpeg is required but not found in PATH.\nInstall it with:\n  macOS:   brew install ffmpeg\n  Ubuntu:  sudo apt install ffmpeg\n  Windows: winget install ffmpeg\nOr: npm install ffmpeg-static, or set SQUISQ_FFMPEG to an ffmpeg binary."
     );
   }
+  return ffmpegPath;
+}
+async function iterateDocFrames(session, options, visit) {
+  const { page, renderAPI } = session;
+  const { fps, coverPreRoll, captureFormat, signal, onProgress } = options;
+  const screenshot = () => captureFormat === "jpeg" ? page.screenshot({ type: "jpeg", quality: JPEG_CAPTURE_QUALITY }) : page.screenshot({ type: "png" });
+  const docDuration = await renderAPI.evaluate((api) => api.getDuration());
+  signal?.throwIfAborted();
+  if (docDuration <= 0) throw new Error("Document has zero duration \u2014 nothing to render");
+  const hasCover = coverPreRoll > 0 ? await renderAPI.evaluate((api) => api.hasCoverBlock()) : false;
+  const appliedCoverPreRoll = resolveAppliedCoverPreRoll(coverPreRoll, hasCover);
+  const storyFrameCount = Math.ceil(docDuration * fps);
+  const preRollFrameCount = Math.ceil(appliedCoverPreRoll * fps);
+  const totalFrames = preRollFrameCount + storyFrameCount;
+  onProgress?.("capturing frames", 20);
+  if (preRollFrameCount > 0) {
+    signal?.throwIfAborted();
+    await visit(
+      { index: 0, time: 0, isCover: true, repeat: preRollFrameCount, totalFrames },
+      async () => {
+        await renderAPI.evaluate((api) => api.showCover());
+        await page.waitForTimeout(100);
+        signal?.throwIfAborted();
+        const frame = await screenshot();
+        await renderAPI.evaluate((api) => api.hideCover());
+        return frame;
+      }
+    );
+  }
+  const progressEvery = Math.max(1, Math.floor(fps / 2));
+  for (let i = 0; i < storyFrameCount; i++) {
+    signal?.throwIfAborted();
+    const time = frameTimeSeconds(i, fps);
+    await visit(
+      { index: preRollFrameCount + i, time, isCover: false, repeat: 1, totalFrames },
+      async () => {
+        await renderAPI.evaluate((api, t) => api.seekTo(t), time);
+        signal?.throwIfAborted();
+        return screenshot();
+      }
+    );
+    if (i % progressEvery === 0 || i === storyFrameCount - 1) {
+      onProgress?.(
+        "capturing frames",
+        20 + Math.round((preRollFrameCount + i + 1) / totalFrames * 60)
+      );
+    }
+  }
+  return {
+    totalDuration: docDuration + appliedCoverPreRoll,
+    appliedCoverPreRoll,
+    totalFrames,
+    preRollFrameCount
+  };
+}
+async function captureDocFrames(doc, container, options) {
+  const { fps, width, height, captionStyle, coverPreRoll, animationsEnabled, onProgress, signal } = options;
+  signal?.throwIfAborted();
+  resolveAppliedCoverPreRoll(coverPreRoll, true);
+  const ffmpegPath = await requireFfmpeg(signal);
   const capturedFrames = new CapturedFrameCollector();
   try {
     return await withRenderPage(
       doc,
       container,
       { signal, width, height, includeAudio: true, captionStyle, animationsEnabled, onProgress },
-      async ({ page, renderAPI }) => {
-        const docDuration = await renderAPI.evaluate((api) => api.getDuration());
-        signal?.throwIfAborted();
-        if (docDuration <= 0) throw new Error("Document has zero duration \u2014 nothing to render");
-        const hasCover = coverPreRoll > 0 ? await renderAPI.evaluate((api) => api.hasCoverBlock()) : false;
-        const appliedCoverPreRoll = resolveAppliedCoverPreRoll(coverPreRoll, hasCover);
-        const storyFrameCount = Math.ceil(docDuration * fps);
-        const preRollFrameCount = Math.ceil(appliedCoverPreRoll * fps);
-        const totalFrames = preRollFrameCount + storyFrameCount;
-        onProgress?.("capturing frames", 20);
-        capturedFrames.throwIfAborted(signal);
-        if (preRollFrameCount > 0) {
-          capturedFrames.throwIfAborted(signal);
-          await renderAPI.evaluate((api) => api.showCover());
-          await page.waitForTimeout(100);
-          capturedFrames.throwIfAborted(signal);
-          const coverFrame = await page.screenshot({ type: "png" });
-          capturedFrames.throwIfAborted(signal);
-          capturedFrames.append(coverFrame, preRollFrameCount);
-          await renderAPI.evaluate((api) => api.hideCover());
-        }
-        const frameInterval = 1 / fps;
-        for (let i = 0; i < storyFrameCount; i++) {
-          capturedFrames.throwIfAborted(signal);
-          const time = i * frameInterval;
-          await renderAPI.evaluate((api, t) => api.seekTo(t), time);
-          const frame = await page.screenshot({ type: "png" });
-          capturedFrames.throwIfAborted(signal);
-          capturedFrames.append(frame);
-          if (i % Math.max(1, Math.floor(fps / 2)) === 0 || i === storyFrameCount - 1) {
-            onProgress?.(
-              "capturing frames",
-              20 + Math.round(capturedFrames.frameCount / totalFrames * 60)
-            );
+      async (session) => {
+        const loop = await iterateDocFrames(
+          session,
+          { fps, coverPreRoll, captureFormat: "png", signal, onProgress },
+          async (frame, capture) => {
             capturedFrames.throwIfAborted(signal);
+            const bytes = await capture();
+            capturedFrames.throwIfAborted(signal);
+            capturedFrames.append(bytes, frame.repeat);
           }
-        }
+        );
         return {
           frames: capturedFrames.release(),
-          totalDuration: docDuration + appliedCoverPreRoll,
-          appliedCoverPreRoll,
+          totalDuration: loop.totalDuration,
+          appliedCoverPreRoll: loop.appliedCoverPreRoll,
           ffmpegPath
         };
       }
@@ -1149,6 +1369,119 @@ async function captureDocFrames(doc, container, options) {
     throw err;
   }
 }
+async function renderDocToMp4Piped(doc, container, options, render) {
+  const { signal, onProgress } = options;
+  const { fps, quality, width, height, captureFormat } = render;
+  const coverPreRoll = options.coverPreRoll ?? 0;
+  resolveAppliedCoverPreRoll(coverPreRoll, true);
+  if (options.resume && !options.framesDir) {
+    throw new Error("resume requires framesDir so there is a spool to resume from");
+  }
+  const captionStyle = options.captionStyle === "off" ? void 0 : options.captionStyle;
+  const animationsEnabled = options.animationsEnabled ?? true;
+  const ffmpegPath = await requireFfmpeg(signal);
+  const outputPath = resolvePath(options.outputPath);
+  await mkdir2(dirname2(outputPath), { recursive: true });
+  const manifest = {
+    generatedBy: "squisq-cli",
+    docHash: docRenderHash(doc),
+    fps,
+    width,
+    height,
+    captionStyle: captionStyle ?? null,
+    animationsEnabled,
+    coverPreRoll,
+    captureFormat
+  };
+  const store = options.framesDir ? await openDirectoryFrameStore(
+    resolvePath(options.framesDir),
+    manifest,
+    options.resume === true
+  ) : null;
+  const audioPath = join4(tmpdir2(), `squisq-audio-${randomBytes2(8).toString("hex")}.mp3`);
+  let audioWritten = false;
+  let sink = null;
+  let reusedFrameCount = 0;
+  try {
+    const { loop, activeSink } = await withRenderPage(
+      doc,
+      container,
+      { signal, width, height, includeAudio: true, captionStyle, animationsEnabled, onProgress },
+      async (session) => {
+        const hasCover = coverPreRoll > 0 ? await session.renderAPI.evaluate((api) => api.hasCoverBlock()) : false;
+        const appliedCoverPreRoll = resolveAppliedCoverPreRoll(coverPreRoll, hasCover);
+        onProgress?.("mixing audio", 18);
+        const encodingAudio = await buildMixedAudioTrack(
+          doc,
+          container,
+          ffmpegPath,
+          appliedCoverPreRoll,
+          signal
+        );
+        signal?.throwIfAborted();
+        if (encodingAudio) {
+          await writeFile2(audioPath, encodingAudio);
+          audioWritten = true;
+        }
+        const pipe = createFfmpegPipeSink({
+          ffmpegPath,
+          outputPath,
+          fps,
+          width,
+          height,
+          quality,
+          captureFormat,
+          audioPath: audioWritten ? audioPath : null,
+          signal
+        });
+        sink = pipe;
+        const result = await iterateDocFrames(
+          session,
+          { fps, coverPreRoll, captureFormat, signal, onProgress },
+          async (frame, capture) => {
+            const started = Date.now();
+            let bytes;
+            let reused = false;
+            if (store?.reusable && await store.has(frame.index)) {
+              bytes = await store.read(frame.index);
+              reused = true;
+              reusedFrameCount += frame.repeat;
+            } else {
+              bytes = await capture();
+              if (store) await store.write(frame.index, bytes);
+            }
+            await pipe.write(bytes, frame.repeat);
+            options.onFrame?.({
+              index: frame.index,
+              time: frame.time,
+              isCover: frame.isCover,
+              totalFrames: frame.totalFrames,
+              reused,
+              captureMs: reused ? 0 : Date.now() - started
+            });
+          }
+        );
+        return { loop: result, activeSink: pipe };
+      }
+    );
+    onProgress?.("encoding video", 85);
+    await activeSink.finish();
+    signal?.throwIfAborted();
+    onProgress?.("done", 100);
+    return {
+      duration: loop.totalDuration,
+      frameCount: activeSink.frameCount,
+      outputPath,
+      reusedFrameCount,
+      ...store ? { framesDir: store.dir } : {}
+    };
+  } catch (err) {
+    await sink?.abort();
+    throw err;
+  } finally {
+    if (audioWritten) await rm2(audioPath, { force: true }).catch(() => void 0);
+  }
+}
 async function renderDocCoverToPng(doc, container, options = {}) {
   const width = options.width ?? 1920;
   const height = options.height ?? 1080;
@@ -1181,8 +1514,8 @@ async function renderDocCoverToPng(doc, container, options = {}) {
   let writtenPath;
   if (options.outputPath) {
     const absolute = resolvePath(options.outputPath);
-    await mkdir(dirname2(absolute), { recursive: true });
-    await writeFile(absolute, bytes);
+    await mkdir2(dirname2(absolute), { recursive: true });
+    await writeFile2(absolute, bytes);
     writtenPath = absolute;
   }
   options.onProgress?.("done", 100);
@@ -1230,8 +1563,8 @@ async function renderDocToDashboardPng(doc, container, options = {}) {
   let writtenPath;
   if (outputPath) {
     const absolute = resolvePath(outputPath);
-    await mkdir(dirname2(absolute), { recursive: true });
-    await writeFile(absolute, bytes);
+    await mkdir2(dirname2(absolute), { recursive: true });
+    await writeFile2(absolute, bytes);
     writtenPath = absolute;
   }
   onProgress?.("done", 100);
@@ -1254,6 +1587,20 @@ async function renderDocToMp4(doc, container, options) {
     fps,
     quality
   });
+  const frameTransport = options.frameTransport ?? "pipe";
+  const captureFormat = options.captureFormat ?? (quality === "high" ? "png" : "jpeg");
+  if (frameTransport === "pipe") {
+    return renderDocToMp4Piped(doc, container, options, {
+      fps,
+      quality,
+      width: dimensions.width,
+      height: dimensions.height,
+      captureFormat
+    });
+  }
+  if (options.framesDir || options.resume || options.onFrame) {
+    throw new Error("framesDir, resume, and onFrame require the pipe frame transport");
+  }
   const capture = await captureDocFrames(doc, container, {
     fps,
     width: dimensions.width,
@@ -1276,7 +1623,7 @@ async function renderDocToMp4(doc, container, options) {
       options.signal
     );
     options.signal?.throwIfAborted();
-    const { framesToMp4Native: framesToMp4Native2 } = await import("./nativeEncoder-RZ3T4Z6S.js");
+    const { framesToMp4Native: framesToMp4Native2 } = await import("./nativeEncoder-T43J5UMP.js");
     await framesToMp4Native2(capture.ffmpegPath, capture.frames, encodingAudio, options.outputPath, {
       fps,
       quality,
@@ -1331,7 +1678,7 @@ async function renderDocToGif(doc, container, options) {
   try {
     options.onProgress?.("encoding GIF", 80);
     options.signal?.throwIfAborted();
-    const { framesToGifNative: framesToGifNative2 } = await import("./nativeEncoder-RZ3T4Z6S.js");
+    const { framesToGifNative: framesToGifNative2 } = await import("./nativeEncoder-T43J5UMP.js");
     await framesToGifNative2(capture.ffmpegPath, capture.frames, options.outputPath, {
       fps,
       orientation,
@@ -1361,7 +1708,7 @@ async function renderDocToGif(doc, container, options) {
 async function extractThumbnails(options) {
   const { videoPath, outputDir, slug, sizes, force, signal } = options;
   const { existsSync } = await import("fs");
-  const { rm: rm2 } = await import("fs/promises");
+  const { rm: rm3 } = await import("fs/promises");
   const { isAbsolute: isAbsolute2, relative: relative2, resolve: resolve2, sep: sep2 } = await import("path");
   signal?.throwIfAborted();
   if (typeof slug !== "string" || !/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$/.test(slug)) {
@@ -1411,13 +1758,13 @@ async function extractThumbnails(options) {
         signal?.throwIfAborted();
         generatedPaths.push(outputPath);
       } catch (error) {
-        await rm2(outputPath, { force: true });
+        await rm3(outputPath, { force: true });
         throw error;
       }
     }
     signal?.throwIfAborted();
   } catch (error) {
-    await Promise.allSettled(generatedPaths.map((path) => rm2(path, { force: true })));
+    await Promise.allSettled(generatedPaths.map((path) => rm3(path, { force: true })));
     throw error;
   }
 }
@@ -1432,6 +1779,7 @@ export {
   convert,
   createCliRegistry,
   extractThumbnails,
+  ffmpegPipeArgs,
   framesToGifNative,
   framesToGifNativeBytes,
   framesToMp4Native,