@kitsra/kavio-render 0.1.2 → 0.2.0

package/dist/assemble-command.d.ts

@@ -3,11 +3,29 @@ export interface AssembleRenderCommandOptions {
     /** Composition with props resolved and the export preset already applied. */
     view: KavioDocument;
     preset: KavioExportPreset;
-    /** printf-style path to the captured transparent overlay frames, e.g. work/overlay-%05d.png */
-    framePattern: string;
+    /**
+     * printf-style path to the captured transparent overlay frames, e.g.
+     * work/overlay-%05d.png. When omitted, the command reads overlay frames from
+     * stdin as an image2pipe PNG stream so capture and encode can overlap.
+     */
+    framePattern?: string;
     /** Output file path. Defaults to `<preset.name>.<ext>`. */
     outputPath?: string;
 }
+export interface AssembleDirectRenderCommandOptions {
+    /** Composition with props resolved and the export preset already applied. */
+    view: KavioDocument;
+    preset: KavioExportPreset;
+    /** Output file path. Defaults to `<preset.name>.<ext>`. */
+    outputPath?: string;
+}
+export type DirectRenderSupport = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    layerId?: string;
+};
 /**
  * Fuse the FFmpeg planner's base-video, overlay, and audio-mix pieces into a single
  * runnable `ffmpeg` argument list. Pure: no IO, no process spawning.
@@ -16,4 +34,11 @@ export interface AssembleRenderCommandOptions {
  * in how the base stream is produced; everything downstream is identical.
  */
 export declare function assembleRenderCommand(options: AssembleRenderCommandOptions): string[];
+/**
+ * Experimental FFmpeg-direct renderer for filtergraph-safe templates. This path
+ * deliberately avoids the browser/PNG overlay loop and compiles supported shape
+ * layers into drawbox filters over the normal base video/audio plan.
+ */
+export declare function assembleDirectRenderCommand(options: AssembleDirectRenderCommandOptions): string[];
+export declare function getDirectRenderSupport(view: KavioDocument): DirectRenderSupport;
 //# sourceMappingURL=assemble-command.d.ts.map

package/dist/assemble-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assemble-command.d.ts","sourceRoot":"","sources":["../src/assemble-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,aAAa,EACb,iBAAiB,EAGlB,MAAM,sBAAsB,CAAC;AAY9B,MAAM,WAAW,4BAA4B;IAC3C,6EAA6E;IAC7E,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,+FAA+F;IAC/F,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,EAAE,CA2ErF"}
+{"version":3,"file":"assemble-command.d.ts","sourceRoot":"","sources":["../src/assemble-command.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,aAAa,EACb,iBAAiB,EAKlB,MAAM,sBAAsB,CAAC;AAY9B,MAAM,WAAW,4BAA4B;IAC3C,6EAA6E;IAC7E,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kCAAkC;IACjD,6EAA6E;IAC7E,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAMpD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,EAAE,CA+ErF;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kCAAkC,GAAG,MAAM,EAAE,CA0EjG;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,GAAG,mBAAmB,CAiB/E"}

package/dist/assemble-command.js

@@ -1,3 +1,4 @@
+import { evaluateLayer, getCanvasDimensions, isLayerActive } from "@kitsra/kavio-core";
 import { extensionForFormat } from "@kitsra/kavio-schema";
 import { buildFilterComplexArgs, planAudioMix, planBaseVideoSequence, planOverlayCompositing } from "@kitsra/kavio-ffmpeg";
 import { renderError } from "./errors.js";
@@ -39,14 +40,19 @@ export function assembleRenderCommand(options) {
         baseLabel = `${inputIndex}:v`;
         inputIndex += 1;
     }
-    // --- Transparent overlay frame sequence ---------------------------------
+    // --- Transparent overlay frame sequence (files or stdin pipe) -----------
     const overlayPlan = planOverlayCompositing({
         baseLabel,
-        frames: { framePattern, fps, inputIndex, startNumber: 0, outputLabel: "overlay_frames" },
+        frames: { framePattern: framePattern ?? "-", fps, inputIndex, startNumber: 0, outputLabel: "overlay_frames" },
         outputLabel: VIDEO_OUT_LABEL,
         shortest: true
     });
-    inputArgs.push(...planInputArgs(overlayPlan));
+    if (framePattern === undefined) {
+        inputArgs.push("-f", "image2pipe", "-framerate", String(fps), "-i", "-");
+    }
+    else {
+        inputArgs.push(...planInputArgs(overlayPlan));
+    }
     chains.push(...planFilterChains(overlayPlan));
     inputIndex += 1;
     // --- Audio: mix declared tracks, or synthesize silence ------------------
@@ -77,6 +83,89 @@ export function assembleRenderCommand(options) {
         outputPath
     ];
 }
+/**
+ * Experimental FFmpeg-direct renderer for filtergraph-safe templates. This path
+ * deliberately avoids the browser/PNG overlay loop and compiles supported shape
+ * layers into drawbox filters over the normal base video/audio plan.
+ */
+export function assembleDirectRenderCommand(options) {
+    const support = getDirectRenderSupport(options.view);
+    if (!support.ok) {
+        throw renderError({
+            code: "RENDER_FAILED",
+            stage: "render",
+            path: support.layerId === undefined ? "layers" : `layers.${support.layerId}`,
+            message: `FFmpeg-direct render does not support this composition yet: ${support.reason}`
+        });
+    }
+    const { view, preset } = options;
+    const fps = preset.fps ?? view.composition.fps;
+    const width = preset.width;
+    const height = preset.height;
+    const background = preset.background ?? view.composition.background ?? "black";
+    const outputPath = options.outputPath ?? `${preset.name}.${extensionForFormat(preset.format)}`;
+    const durationSeconds = view.composition.durationFrames / fps;
+    const inputArgs = [];
+    const chains = [];
+    let inputIndex = 0;
+    const videoLayers = view.layers.filter((layer) => layer.type === "video");
+    let baseLabel;
+    if (videoLayers.length > 0) {
+        const segments = videoLayers.map((layer, index) => baseSegment(view, layer, { width, height }, fps, inputIndex + index, background));
+        const basePlan = planBaseVideoSequence({ segments, outputLabel: BASE_LABEL });
+        inputArgs.push(...planInputArgs(basePlan));
+        chains.push(...planFilterChains(basePlan));
+        inputIndex += segments.length;
+        baseLabel = BASE_LABEL;
+    }
+    else {
+        inputArgs.push("-f", "lavfi", "-i", `color=c=${escapeLavfi(background)}:s=${width}x${height}:r=${fps}:d=${formatSeconds(durationSeconds)}`);
+        baseLabel = `${inputIndex}:v`;
+        inputIndex += 1;
+    }
+    chains.push(buildDirectShapeFilterChain(view, baseLabel, VIDEO_OUT_LABEL));
+    const audioTracks = view.audio ?? [];
+    if (audioTracks.length > 0) {
+        const trackOptions = audioTracks.map((track, index) => audioOption(view, track, inputIndex + index));
+        const audioPlan = planAudioMix({ tracks: trackOptions, fps, outputLabel: AUDIO_OUT_LABEL, normalizeLoudness: true });
+        inputArgs.push(...planInputArgs(audioPlan));
+        chains.push(...planFilterChains(audioPlan));
+        inputIndex += trackOptions.length;
+    }
+    else {
+        inputArgs.push("-f", "lavfi", "-i", "anullsrc=channel_layout=stereo:sample_rate=48000");
+        chains.push(silentAudioChain(inputIndex));
+        inputIndex += 1;
+    }
+    return [
+        "-y",
+        ...inputArgs,
+        ...buildFilterComplexArgs(chains),
+        "-map",
+        `[${VIDEO_OUT_LABEL}]`,
+        "-map",
+        `[${AUDIO_OUT_LABEL}]`,
+        ...encodeArgs(preset, fps),
+        "-t",
+        formatSeconds(durationSeconds),
+        outputPath
+    ];
+}
+export function getDirectRenderSupport(view) {
+    for (const layer of view.layers) {
+        if (layer.type === "video") {
+            continue;
+        }
+        if (layer.type !== "shape") {
+            return unsupported(layer, `layer type "${layer.type}" requires browser rendering`);
+        }
+        const unsupportedShape = getUnsupportedDirectShapeReason(layer);
+        if (unsupportedShape !== null) {
+            return unsupported(layer, unsupportedShape);
+        }
+    }
+    return { ok: true };
+}
 function baseSegment(view, layer, output, fps, inputIndex, background) {
     const asset = videoAsset(view, layer.asset, layer.id);
     const segment = {
@@ -114,6 +203,80 @@ function audioOption(view, track, inputIndex) {
         inputIndex
     };
 }
+function buildDirectShapeFilterChain(view, inputLabel, outputLabel) {
+    const dimensions = getCanvasDimensions(view.composition);
+    const filters = view.layers
+        .map((layer, index) => ({ layer, order: layer.z ?? index }))
+        .sort((a, b) => a.order - b.order)
+        .flatMap(({ layer }) => (layer.type === "shape" ? directShapeFilters(layer, dimensions) : []));
+    const effectiveFilters = filters.length === 0 ? ["null"] : filters;
+    return {
+        inputLabels: [inputLabel],
+        filters: effectiveFilters,
+        outputLabel,
+        expression: `[${inputLabel}]${effectiveFilters.join(",")}[${outputLabel}]`
+    };
+}
+function directShapeFilters(layer, dimensions) {
+    const evaluation = evaluateLayer(layer, layer.startFrame, dimensions);
+    const width = evaluation.size.width ?? 0;
+    const height = evaluation.size.height ?? 0;
+    if (!isLayerActive(layer, layer.startFrame) || width <= 0 || height <= 0 || evaluation.opacity <= 0) {
+        return [];
+    }
+    const x = evaluation.topLeft.x ?? evaluation.position.x;
+    const y = evaluation.topLeft.y ?? evaluation.position.y;
+    const start = layer.startFrame;
+    const end = layer.startFrame + layer.durationFrames - 1;
+    const enable = `enable='between(n,${start},${end})'`;
+    const filters = [];
+    if (layer.fill !== undefined && layer.fill !== "transparent") {
+        filters.push(`drawbox=x=${formatFfmpegNumber(x)}:y=${formatFfmpegNumber(y)}:w=${formatFfmpegNumber(width)}:h=${formatFfmpegNumber(height)}:color=${formatDrawboxColor(layer.fill, evaluation.opacity)}:t=fill:${enable}`);
+    }
+    if (layer.stroke !== undefined && layer.stroke !== null && layer.stroke.width > 0) {
+        filters.push(`drawbox=x=${formatFfmpegNumber(x)}:y=${formatFfmpegNumber(y)}:w=${formatFfmpegNumber(width)}:h=${formatFfmpegNumber(height)}:color=${formatDrawboxColor(layer.stroke.color, evaluation.opacity)}:t=${formatFfmpegNumber(layer.stroke.width)}:${enable}`);
+    }
+    return filters;
+}
+function getUnsupportedDirectShapeReason(layer) {
+    if (layer.shape !== "rect") {
+        return `shape "${layer.shape}" is not supported`;
+    }
+    if (layer.radius !== undefined && layer.radius > 0) {
+        return "rounded shape corners are not supported";
+    }
+    if (layer.keyframes !== undefined && Object.keys(layer.keyframes).length > 0) {
+        return "animated shape keyframes are not supported";
+    }
+    if (layer.rotation !== undefined && layer.rotation !== 0) {
+        return "rotated shapes are not supported";
+    }
+    if (layer.scale !== undefined && layer.scale !== 1) {
+        return "scaled shapes are not supported";
+    }
+    if (layer.effects !== undefined && layer.effects.length > 0) {
+        return "shape effects are not supported";
+    }
+    if (layer.mask !== undefined && layer.mask !== null) {
+        return "shape masks are not supported";
+    }
+    if (layer.transitionIn !== undefined && layer.transitionIn !== null) {
+        return "shape transitions are not supported";
+    }
+    if (layer.transitionOut !== undefined && layer.transitionOut !== null) {
+        return "shape transitions are not supported";
+    }
+    if (layer.fill !== undefined && layer.fill !== "transparent" && !isDirectColorSupported(layer.fill)) {
+        return `fill color "${layer.fill}" is not supported`;
+    }
+    if (layer.stroke !== undefined && layer.stroke !== null && !isDirectColorSupported(layer.stroke.color)) {
+        return `stroke color "${layer.stroke.color}" is not supported`;
+    }
+    return null;
+}
+function unsupported(layer, reason) {
+    return { ok: false, reason, layerId: layer.id };
+}
 function silentAudioChain(inputIndex) {
     return {
         inputLabels: [`${inputIndex}:a`],
@@ -189,6 +352,35 @@ function escapeLavfi(value) {
         .replace(/,/g, "\\,")
         .replace(/;/g, "\\;");
 }
+function isDirectColorSupported(value) {
+    return value === "transparent" || /^#[0-9a-f]{6}([0-9a-f]{2})?$/i.test(value);
+}
+function formatDrawboxColor(value, opacity) {
+    const match = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i.exec(value);
+    if (match === null) {
+        throw renderError({
+            code: "RENDER_FAILED",
+            stage: "render",
+            message: `FFmpeg-direct render only supports hex colors; received "${value}".`
+        });
+    }
+    const base = match[1];
+    const alpha = match[2] === undefined ? 1 : Number.parseInt(match[2], 16) / 255;
+    return `${escapeLavfi(`0x${base}`)}@${formatFfmpegNumber(alpha * opacity)}`;
+}
+function formatFfmpegNumber(value) {
+    if (!Number.isFinite(value)) {
+        throw renderError({
+            code: "RENDER_FAILED",
+            stage: "render",
+            message: "FFmpeg-direct render encountered a non-finite numeric value."
+        });
+    }
+    if (Number.isInteger(value)) {
+        return String(value);
+    }
+    return value.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
 function formatSeconds(seconds) {
     if (Number.isInteger(seconds)) {
         return String(seconds);

package/dist/ffmpeg-runner.d.ts

@@ -1,7 +1,14 @@
 export interface FfmpegChildStream {
     on(event: "data", listener: (chunk: unknown) => void): void;
 }
+export interface FfmpegChildWritable {
+    write(chunk: Uint8Array): boolean;
+    end(): void;
+    on(event: "drain" | "error", listener: (...args: unknown[]) => void): void;
+    once(event: "close", listener: () => void): void;
+}
 export interface FfmpegChildProcess {
+    stdin?: FfmpegChildWritable | null;
     stdout: FfmpegChildStream | null;
     stderr: FfmpegChildStream | null;
     on(event: "error", listener: (error: Error) => void): void;
@@ -12,6 +19,12 @@ export type FfmpegSpawn = (command: string, args: readonly string[]) => FfmpegCh
 export interface FfmpegRunOptions {
     onProgress?: (chunk: string) => void;
     signal?: AbortSignal;
+    /**
+     * Byte chunks piped to ffmpeg's stdin (e.g. an image2pipe PNG frame stream).
+     * The runner applies write backpressure and ends stdin when the source
+     * completes; a source failure kills ffmpeg and rejects with that error.
+     */
+    stdin?: AsyncIterable<Uint8Array>;
 }
 export interface FfmpegRunResult {
     code: number;

package/dist/ffmpeg-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ffmpeg-runner.d.ts","sourceRoot":"","sources":["../src/ffmpeg-runner.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3D,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,kBAAkB,CAAC;AAE3F,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD;AAID,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG,YAAY,CA2ExF"}
+{"version":3,"file":"ffmpeg-runner.d.ts","sourceRoot":"","sources":["../src/ffmpeg-runner.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;IAClC,GAAG,IAAI,IAAI,CAAC;IACZ,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3E,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3D,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,kBAAkB,CAAC;AAE3F,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD;AAID,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG,YAAY,CAkGxF"}

package/dist/ffmpeg-runner.js

@@ -15,6 +15,7 @@ export function createFfmpegRunner(options = {}) {
                 const child = spawn(binary, args);
                 let stderr = "";
                 let settled = false;
+                let closed = false;
                 const settle = (action) => {
                     if (settled) {
                         return;
@@ -32,6 +33,22 @@ export function createFfmpegRunner(options = {}) {
                 if (signal !== undefined) {
                     signal.addEventListener("abort", onAbort);
                 }
+                if (runOptions.stdin !== undefined) {
+                    const stdin = child.stdin;
+                    if (stdin === undefined || stdin === null) {
+                        child.kill("SIGKILL");
+                        settle(() => reject(renderError({
+                            code: "FFMPEG_FAILED",
+                            stage: "ffmpeg",
+                            message: "ffmpeg child process exposes no stdin to pipe frames into."
+                        })));
+                        return;
+                    }
+                    pumpStdin(stdin, runOptions.stdin, () => closed).catch((error) => {
+                        child.kill("SIGKILL");
+                        settle(() => reject(error));
+                    });
+                }
                 child.stderr?.on("data", (chunk) => {
                     stderr = `${stderr}${String(chunk)}`.slice(-STDERR_TAIL_LENGTH);
                 });
@@ -47,6 +64,7 @@ export function createFfmpegRunner(options = {}) {
                     })));
                 });
                 child.on("close", (code) => {
+                    closed = true;
                     settle(() => {
                         if (code === 0) {
                             resolve({ code: 0, stderr });
@@ -62,6 +80,34 @@ export function createFfmpegRunner(options = {}) {
         }
     };
 }
+async function pumpStdin(stdin, source, isClosed) {
+    // One permanent listener per event; each backpressure pause parks a single
+    // waiter that any of drain/error/close wakes. EPIPE from an early ffmpeg
+    // exit is swallowed here — the child close handler reports the real failure
+    // with stderr context.
+    let waiter = null;
+    const wake = () => {
+        const parked = waiter;
+        waiter = null;
+        parked?.();
+    };
+    stdin.on("drain", wake);
+    stdin.on("error", wake);
+    stdin.once("close", wake);
+    for await (const chunk of source) {
+        if (isClosed()) {
+            return;
+        }
+        if (!stdin.write(chunk)) {
+            await new Promise((resolve) => {
+                waiter = resolve;
+            });
+        }
+    }
+    if (!isClosed()) {
+        stdin.end();
+    }
+}
 function cancelledError() {
     return renderError({
         code: "RENDER_CANCELLED",

package/dist/frame-stream.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bounded async byte queue bridging frame capture (producer) and an ffmpeg
+ * stdin pump (consumer). push() resolves immediately while the buffered bytes
+ * stay under the cap, otherwise it waits for the consumer — so a slow encoder
+ * applies backpressure to capture instead of buffering the whole render.
+ */
+export interface FrameByteQueue extends AsyncIterable<Uint8Array> {
+    /** Enqueue one chunk; resolves once the queue is willing to accept more. */
+    push(chunk: Uint8Array): Promise<void>;
+    /** Signal that no more chunks will arrive; iteration completes after drain. */
+    end(): void;
+    /** Poison the queue: pending and future pushes and iteration reject with the error. */
+    fail(error: unknown): void;
+}
+export interface CreateFrameByteQueueOptions {
+    /** Buffered-byte threshold above which push() waits for the consumer. Default 64 MiB. */
+    maxBufferedBytes?: number;
+}
+export declare function createFrameByteQueue(options?: CreateFrameByteQueueOptions): FrameByteQueue;
+//# sourceMappingURL=frame-stream.d.ts.map

package/dist/frame-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-stream.d.ts","sourceRoot":"","sources":["../src/frame-stream.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,aAAa,CAAC,UAAU,CAAC;IAC/D,4EAA4E;IAC5E,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,+EAA+E;IAC/E,GAAG,IAAI,IAAI,CAAC;IACZ,uFAAuF;IACvF,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,2BAA2B;IAC1C,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,GAAG,cAAc,CAsF9F"}

package/dist/frame-stream.js

@@ -0,0 +1,82 @@
+const DEFAULT_MAX_BUFFERED_BYTES = 64 * 1024 * 1024;
+export function createFrameByteQueue(options = {}) {
+    const maxBufferedBytes = options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+    const chunks = [];
+    let bufferedBytes = 0;
+    let ended = false;
+    let failure = null;
+    let notifyConsumer = null;
+    const producerWaiters = [];
+    const wakeConsumer = () => {
+        notifyConsumer?.();
+        notifyConsumer = null;
+    };
+    const releaseProducers = () => {
+        while (producerWaiters.length > 0 && (failure !== null || bufferedBytes <= maxBufferedBytes)) {
+            const waiter = producerWaiters.shift();
+            if (waiter === undefined) {
+                return;
+            }
+            if (failure !== null) {
+                waiter.reject(failure.error);
+            }
+            else {
+                waiter.resolve();
+            }
+        }
+    };
+    return {
+        async push(chunk) {
+            if (failure !== null) {
+                throw failure.error;
+            }
+            if (ended) {
+                throw new Error("Cannot push to an ended frame byte queue.");
+            }
+            const hadCapacity = bufferedBytes < maxBufferedBytes;
+            chunks.push(chunk);
+            bufferedBytes += chunk.byteLength;
+            wakeConsumer();
+            if (hadCapacity) {
+                return;
+            }
+            await new Promise((resolve, reject) => {
+                producerWaiters.push({ resolve, reject });
+            });
+        },
+        end() {
+            ended = true;
+            wakeConsumer();
+        },
+        fail(error) {
+            if (failure !== null) {
+                return;
+            }
+            failure = { error };
+            chunks.length = 0;
+            bufferedBytes = 0;
+            wakeConsumer();
+            releaseProducers();
+        },
+        async *[Symbol.asyncIterator]() {
+            while (true) {
+                if (failure !== null) {
+                    throw failure.error;
+                }
+                const chunk = chunks.shift();
+                if (chunk !== undefined) {
+                    bufferedBytes -= chunk.byteLength;
+                    releaseProducers();
+                    yield chunk;
+                    continue;
+                }
+                if (ended) {
+                    return;
+                }
+                await new Promise((resolve) => {
+                    notifyConsumer = resolve;
+                });
+            }
+        }
+    };
+}

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 export declare const KAVIO_RENDER_PACKAGE = "@kitsra/kavio-render";
 export { renderError, isRenderError, RENDER_ERROR_CODES, type RenderErrorCode, type RenderErrorOptions } from "./errors.js";
-export { assembleRenderCommand, type AssembleRenderCommandOptions } from "./assemble-command.js";
+export { assembleDirectRenderCommand, assembleRenderCommand, getDirectRenderSupport, type AssembleDirectRenderCommandOptions, type AssembleRenderCommandOptions, type DirectRenderSupport } from "./assemble-command.js";
 export { resolveFfmpegPath } from "./binaries.js";
-export { createFfmpegRunner, type FfmpegRunner, type FfmpegRunOptions, type FfmpegRunResult, type FfmpegSpawn, type FfmpegChildProcess, type CreateFfmpegRunnerOptions } from "./ffmpeg-runner.js";
+export { createFfmpegRunner, type FfmpegRunner, type FfmpegRunOptions, type FfmpegRunResult, type FfmpegSpawn, type FfmpegChildProcess, type FfmpegChildWritable, type CreateFfmpegRunnerOptions } from "./ffmpeg-runner.js";
+export { createFrameByteQueue, type FrameByteQueue, type CreateFrameByteQueueOptions } from "./frame-stream.js";
 export { createRenderHarnessServer, type RenderHarnessServer, type CreateRenderHarnessServerOptions } from "./harness-server.js";
 export { PlaywrightDriver, type PlaywrightDriverOptions } from "./playwright-driver.js";
-export { renderComposition, type RenderCompositionOptions, type RenderCompositionResult } from "./render-composition.js";
+export { renderComposition, type RenderCompositionMode, type RenderCompositionOptions, type RenderCompositionResult, type RenderStageTimings } from "./render-composition.js";
 export { renderBatch, type RenderBatchOptions, type RenderBatchItemResult } from "./render-batch.js";
 export type { RenderBatchInput, RenderBatchRow } from "@kitsra/kavio-render-worker";
 export { FakeBrowserDriver, createFakeFfmpegRunner, type FakeFfmpegRunner, type CreateFakeFfmpegRunnerOptions } from "./testing.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC5H,OAAO,EAAE,qBAAqB,EAAE,KAAK,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EACtC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACrG,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,6BAA6B,EACnC,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC5H,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,kCAAkC,EACvC,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAChH,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EACtC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACrG,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,6BAA6B,EACnC,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,8 +1,9 @@
 export const KAVIO_RENDER_PACKAGE = "@kitsra/kavio-render";
 export { renderError, isRenderError, RENDER_ERROR_CODES } from "./errors.js";
-export { assembleRenderCommand } from "./assemble-command.js";
+export { assembleDirectRenderCommand, assembleRenderCommand, getDirectRenderSupport } from "./assemble-command.js";
 export { resolveFfmpegPath } from "./binaries.js";
 export { createFfmpegRunner } from "./ffmpeg-runner.js";
+export { createFrameByteQueue } from "./frame-stream.js";
 export { createRenderHarnessServer } from "./harness-server.js";
 export { PlaywrightDriver } from "./playwright-driver.js";
 export { renderComposition } from "./render-composition.js";

package/dist/playwright-driver.d.ts

@@ -13,6 +13,7 @@ export declare class PlaywrightDriver implements BrowserDriver {
     private browser;
     private context;
     private page;
+    private cdp;
     private server;
     private viewport;
     private readonly deviceScaleFactor;
@@ -22,6 +23,14 @@ export declare class PlaywrightDriver implements BrowserDriver {
     constructor(options?: PlaywrightDriverOptions);
     open(composition: KavioDocument, options?: BrowserOpenOptions): Promise<void>;
     renderFrame(frame: number, options?: BrowserFrameCaptureOptions): Promise<BrowserFrameCapture>;
+    /**
+     * Launch a sibling Chromium process against this driver's harness server,
+     * ready to render frames for the same composition. Chromium serializes
+     * screenshot capture inside one browser process, so true capture
+     * parallelism needs one process per worker; the harness server and its
+     * composition stay owned by this driver.
+     */
+    fork(): Promise<BrowserDriver>;
     close(): Promise<void>;
 }
 //# sourceMappingURL=playwright-driver.d.ts.map

package/dist/playwright-driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-driver.d.ts","sourceRoot":"","sources":["../src/playwright-driver.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA+C1D,MAAM,WAAW,uBAAuB;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,2EAA2E;IAC3E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAE1B,OAAO,GAAE,uBAA4B;IAK3C,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgBlG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAY7B"}
+{"version":3,"file":"playwright-driver.d.ts","sourceRoot":"","sources":["../src/playwright-driver.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAqD1D,MAAM,WAAW,uBAAuB;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,GAAG,CAAqC;IAChD,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,2EAA2E;IAC3E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAE1B,OAAO,GAAE,uBAA4B;IAK3C,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCjF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAYxG;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;IA6B9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAY7B"}

package/dist/playwright-driver.js

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 import { createBrowserViewport, createPngFrameCapture, DEFAULT_CHROMIUM_LAUNCH_OPTIONS } from "@kitsra/kavio-render-worker";
 import { renderError } from "./errors.js";
 import { createRenderHarnessServer } from "./harness-server.js";
@@ -25,6 +26,7 @@ export class PlaywrightDriver {
     browser = null;
     context = null;
     page = null;
+    cdp = null;
     server = null;
     viewport = null;
     deviceScaleFactor;
@@ -70,6 +72,7 @@ export class PlaywrightDriver {
         this.server = await createRenderHarnessServer({ composition });
         await this.page.goto(this.server.url);
         await this.page.waitForFunction("window.__kavioReady === true", undefined, { timeout: this.readyTimeoutMs });
+        this.cdp = await createFastScreenshotSession(this.context, this.page);
     }
     async renderFrame(frame, options = {}) {
         if (this.page === null || this.viewport === null) {
@@ -79,10 +82,43 @@ export class PlaywrightDriver {
                 message: "PlaywrightDriver.renderFrame called before open()."
             });
         }
-        const omitBackground = options.omitBackground ?? true;
-        await this.page.evaluate(`window.__kavio.renderFrame(${frame})`);
-        const bytes = await this.page.screenshot({ type: "png", omitBackground });
-        return createPngFrameCapture({ frame, bytes, viewport: this.viewport, omitBackground });
+        return renderFrameOnPage(this.page, this.cdp, this.viewport, frame, options);
+    }
+    /**
+     * Launch a sibling Chromium process against this driver's harness server,
+     * ready to render frames for the same composition. Chromium serializes
+     * screenshot capture inside one browser process, so true capture
+     * parallelism needs one process per worker; the harness server and its
+     * composition stay owned by this driver.
+     */
+    async fork() {
+        if (this.server === null || this.viewport === null) {
+            throw renderError({
+                code: "RENDER_FAILED",
+                stage: "render",
+                message: "PlaywrightDriver.fork called before open()."
+            });
+        }
+        const chromium = await loadChromium();
+        const browser = await chromium.launch({
+            headless: DEFAULT_CHROMIUM_LAUNCH_OPTIONS.headless,
+            args: DEFAULT_CHROMIUM_LAUNCH_OPTIONS.args
+        });
+        try {
+            const context = await browser.newContext({
+                viewport: { width: this.viewport.width, height: this.viewport.height },
+                deviceScaleFactor: this.viewport.deviceScaleFactor
+            });
+            const page = await context.newPage();
+            await page.goto(this.server.url);
+            await page.waitForFunction("window.__kavioReady === true", undefined, { timeout: this.readyTimeoutMs });
+            const cdp = await createFastScreenshotSession(context, page);
+            return new PlaywrightForkDriver(browser, page, cdp, this.viewport);
+        }
+        catch (error) {
+            await browser.close();
+            throw error;
+        }
     }
     async close() {
         try {
@@ -98,6 +134,76 @@ export class PlaywrightDriver {
         this.viewport = null;
     }
 }
+/** Fork of a PlaywrightDriver: its own Chromium process on the shared harness server. */
+class PlaywrightForkDriver {
+    browser;
+    page;
+    cdp;
+    viewport;
+    constructor(browser, page, cdp, viewport) {
+        this.browser = browser;
+        this.page = page;
+        this.cdp = cdp;
+        this.viewport = viewport;
+    }
+    async open() {
+        throw renderError({
+            code: "RENDER_FAILED",
+            stage: "render",
+            message: "Forked Playwright drivers are already open."
+        });
+    }
+    async renderFrame(frame, options = {}) {
+        return renderFrameOnPage(this.page, this.cdp, this.viewport, frame, options);
+    }
+    async close() {
+        await this.browser.close();
+    }
+}
+/**
+ * Prepare a raw CDP screenshot session: the transparent-background override is
+ * applied once here instead of per page.screenshot() call, and captures use
+ * Page.captureScreenshot with optimizeForSpeed (fastest PNG compression level;
+ * identical decoded pixels, so encoded outputs stay deterministic). Returns
+ * null when CDP is unavailable so capture falls back to page.screenshot().
+ */
+async function createFastScreenshotSession(context, page) {
+    try {
+        const session = await context.newCDPSession(page);
+        await session.send("Emulation.setDefaultBackgroundColorOverride", {
+            color: { r: 0, g: 0, b: 0, a: 0 }
+        });
+        return session;
+    }
+    catch {
+        return null;
+    }
+}
+async function renderFrameOnPage(page, cdp, viewport, frame, options) {
+    const omitBackground = options.omitBackground ?? true;
+    const evaluateStart = performance.now();
+    await page.evaluate(`window.__kavio.renderFrame(${frame})`);
+    const screenshotStart = performance.now();
+    let bytes;
+    if (cdp !== null && omitBackground) {
+        const result = (await cdp.send("Page.captureScreenshot", {
+            format: "png",
+            optimizeForSpeed: true
+        }));
+        bytes = Buffer.from(result.data, "base64");
+    }
+    else {
+        bytes = await page.screenshot({ type: "png", omitBackground });
+    }
+    const screenshotEnd = performance.now();
+    return createPngFrameCapture({
+        frame,
+        bytes,
+        viewport,
+        omitBackground,
+        timing: { evaluateMs: screenshotStart - evaluateStart, screenshotMs: screenshotEnd - screenshotStart }
+    });
+}
 function missingBrowserExecutable(message) {
     return message.includes("Executable doesn't exist") || message.includes("playwright install");
 }

package/dist/render-composition.d.ts

@@ -1,11 +1,22 @@
 import { type KavioDocument, type KavioError } from "@kitsra/kavio-schema";
 import { type BrowserDriver, type RenderOutputMetadata } from "@kitsra/kavio-render-worker";
 import { type FfmpegRunner } from "./ffmpeg-runner.js";
+export type RenderCompositionMode = "browser-overlay" | "ffmpeg-direct";
 export interface RenderCompositionOptions {
     preset: string | import("@kitsra/kavio-schema").KavioExportPreset;
     propValues?: Record<string, unknown>;
     outDir?: string;
     outputName?: string;
+    /**
+     * Experimental: "ffmpeg-direct" skips browser PNG capture for compositions
+     * that can be compiled directly into FFmpeg filters.
+     */
+    renderMode?: RenderCompositionMode;
+    /**
+     * Concurrent capture pages for browser-overlay renders. Defaults to
+     * min(4, cores - 1). Deterministic: output bytes match serial capture.
+     */
+    captureParallelism?: number;
     driver?: BrowserDriver;
     ffmpegRunner?: FfmpegRunner;
     signal?: AbortSignal;
@@ -13,10 +24,27 @@ export interface RenderCompositionOptions {
     ffmpegVersion?: string;
     chromiumRevision?: string;
 }
+export interface RenderStageTimings {
+    /** Browser launch + frame capture wall time; absent for ffmpeg-direct renders. */
+    captureMs?: number;
+    /** Driver open wall time (browser launch + harness ready) within captureMs. */
+    browserOpenMs?: number;
+    /** Summed per-frame seek/evaluate time, when the driver reports it. */
+    captureEvaluateMs?: number;
+    /** Summed per-frame screenshot time, when the driver reports it. */
+    captureScreenshotMs?: number;
+    /** FFmpeg encode wall time. */
+    encodeMs: number;
+    /** Output checksum wall time. */
+    checksumMs: number;
+    /** Full renderComposition wall time, including validation and cleanup. */
+    totalMs: number;
+}
 export type RenderCompositionResult = {
     ok: true;
     outputPath: string;
     metadata: RenderOutputMetadata;
+    timings: RenderStageTimings;
 } | {
     ok: false;
     errors: KavioError[];

package/dist/render-composition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-composition.d.ts","sourceRoot":"","sources":["../src/render-composition.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,UAAU,EAEhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAKL,KAAK,aAAa,EAElB,KAAK,oBAAoB,EAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK3E,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,GAAG,OAAO,sBAAsB,EAAE,iBAAiB,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,GAChE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAExC,oGAAoG;AACpG,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAqFlC"}
+{"version":3,"file":"render-composition.d.ts","sourceRoot":"","sources":["../src/render-composition.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,UAAU,EAEhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,aAAa,EAElB,KAAK,oBAAoB,EAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAM3E,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,GAAG,OAAO,sBAAsB,EAAE,iBAAiB,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAC7F;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAExC,oGAAoG;AACpG,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CA+IlC"}

package/dist/render-composition.js

@@ -1,17 +1,19 @@
 import { createHash } from "node:crypto";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { mkdir, readFile } from "node:fs/promises";
+import { availableParallelism } from "node:os";
 import { dirname, join } from "node:path";
 import { applyExportPreset, collectCompositionResourceLimitInputs, collectResourceLimitViolations, resolveTemplateProps } from "@kitsra/kavio-core";
 import { extensionForFormat, validateComposition } from "@kitsra/kavio-schema";
-import { captureFrames, createRenderMetadata, createTemporaryFramesCleanupTask, withRenderCleanup } from "@kitsra/kavio-render-worker";
-import { assembleRenderCommand } from "./assemble-command.js";
+import { captureFrames, createRenderMetadata } from "@kitsra/kavio-render-worker";
+import { assembleDirectRenderCommand, assembleRenderCommand } from "./assemble-command.js";
 import { createFfmpegRunner } from "./ffmpeg-runner.js";
+import { createFrameByteQueue } from "./frame-stream.js";
 import { isRenderError, renderError } from "./errors.js";
 import { PlaywrightDriver } from "./playwright-driver.js";
 import { withEffectiveCodecs } from "./encoding.js";
 /** End-to-end render for one (composition × export): props → view → validate → capture → encode. */
 export async function renderComposition(doc, options) {
+    const totalStart = performance.now();
     const resolution = resolveTemplateProps(doc, options.propValues ?? {});
     if (!resolution.ok) {
         return { ok: false, errors: resolution.errors };
@@ -45,45 +47,100 @@ export async function renderComposition(doc, options) {
     const outputName = options.outputName ?? `${preset.name}.${extensionForFormat(preset.format)}`;
     const outputPath = options.outDir === undefined ? outputName : join(options.outDir, outputName);
     const metadataPreset = withEffectiveCodecs(preset);
+    const renderMode = options.renderMode ?? "browser-overlay";
     try {
-        const metadata = await withRenderCleanup(async (cleanup) => {
-            const workDir = await mkdtemp(join(tmpdir(), "kavio-render-"));
-            cleanup.defer(createTemporaryFramesCleanupTask(async () => {
-                await rm(workDir, { recursive: true, force: true });
-            }, "workdir"));
-            const driver = options.driver ?? new PlaywrightDriver();
-            const framePattern = join(workDir, "overlay-%05d.png");
+        let captureMs;
+        let browserOpenMs;
+        let captureEvaluateMs;
+        let captureScreenshotMs;
+        let encodeMs = 0;
+        await mkdir(dirname(outputPath), { recursive: true });
+        const ffmpegRunner = options.ffmpegRunner ?? createFfmpegRunner();
+        let browserDriver;
+        if (renderMode === "ffmpeg-direct") {
+            const args = assembleDirectRenderCommand({ view, preset, outputPath });
+            const encodeStart = performance.now();
+            await ffmpegRunner.run(args, options.signal === undefined ? {} : { signal: options.signal });
+            encodeMs = performance.now() - encodeStart;
+        }
+        else {
+            // Overlay frames stream straight into ffmpeg stdin so capture and encode
+            // overlap; the bounded queue applies backpressure instead of buffering
+            // the render or round-tripping PNG files through a temp directory.
+            const args = assembleRenderCommand({ view, preset, outputPath });
+            browserDriver = options.driver ?? new PlaywrightDriver();
+            const frames = createFrameByteQueue();
+            const captureStart = performance.now();
             // captureFrames manages browser-context cleanup (open → capture → close).
-            await captureFrames({
-                driver,
+            const capturePromise = captureFrames({
+                driver: browserDriver,
                 composition: view,
+                parallelism: options.captureParallelism ?? defaultCaptureParallelism(),
                 continueOnFrameError: options.continueOnFrameError === true,
                 onFrame: async (capture) => {
-                    const name = `overlay-${String(capture.frame).padStart(5, "0")}.png`;
-                    await writeFile(join(workDir, name), capture.bytes);
+                    await frames.push(capture.bytes);
                 }
+            }).then((captureResult) => {
+                captureMs = performance.now() - captureStart;
+                browserOpenMs = captureResult.openMs;
+                captureEvaluateMs = captureResult.evaluateMs;
+                captureScreenshotMs = captureResult.screenshotMs;
+                frames.end();
+            }, (error) => {
+                frames.fail(error);
+                throw error;
             });
-            await mkdir(dirname(outputPath), { recursive: true });
-            const args = assembleRenderCommand({ view, preset, framePattern, outputPath });
-            const ffmpegRunner = options.ffmpegRunner ?? createFfmpegRunner();
-            await ffmpegRunner.run(args, options.signal === undefined ? {} : { signal: options.signal });
-            const checksum = await sha256File(outputPath);
-            return createRenderMetadata({
-                composition: view.composition,
-                preset: metadataPreset,
-                outputName,
-                outputPath,
-                checksums: checksum,
-                ffmpegVersion: options.ffmpegVersion ?? "ffmpeg-static",
-                chromiumRevision: options.chromiumRevision ?? chromiumRevisionOf(driver)
+            const encodeStart = performance.now();
+            const ffmpegPromise = ffmpegRunner
+                .run(args, options.signal === undefined ? { stdin: frames } : { stdin: frames, signal: options.signal })
+                .then((result) => {
+                encodeMs = performance.now() - encodeStart;
+                return result;
+            }, (error) => {
+                // Stop capture instead of letting it fill the queue for a dead consumer.
+                frames.fail(error);
+                throw error;
             });
+            const [captureSettled, ffmpegSettled] = await Promise.allSettled([capturePromise, ffmpegPromise]);
+            // A genuine capture failure poisons the queue and surfaces through the
+            // ffmpeg rejection too, so prefer the ffmpeg outcome, then capture.
+            if (ffmpegSettled.status === "rejected") {
+                throw ffmpegSettled.reason;
+            }
+            if (captureSettled.status === "rejected") {
+                throw captureSettled.reason;
+            }
+        }
+        const checksumStart = performance.now();
+        const checksum = await sha256File(outputPath);
+        const checksumMs = performance.now() - checksumStart;
+        const metadata = createRenderMetadata({
+            composition: view.composition,
+            preset: metadataPreset,
+            outputName,
+            outputPath,
+            checksums: checksum,
+            ffmpegVersion: options.ffmpegVersion ?? "ffmpeg-static",
+            chromiumRevision: options.chromiumRevision ?? (renderMode === "ffmpeg-direct" ? "not-used" : chromiumRevisionOf(browserDriver))
         });
-        return { ok: true, outputPath, metadata };
+        const timings = {
+            ...(captureMs !== undefined && { captureMs }),
+            ...(browserOpenMs !== undefined && { browserOpenMs }),
+            ...(captureEvaluateMs !== undefined && { captureEvaluateMs }),
+            ...(captureScreenshotMs !== undefined && { captureScreenshotMs }),
+            encodeMs,
+            checksumMs,
+            totalMs: performance.now() - totalStart
+        };
+        return { ok: true, outputPath, metadata, timings };
     }
     catch (error) {
         return { ok: false, errors: [toKavioError(error)] };
     }
 }
+function defaultCaptureParallelism() {
+    return Math.max(1, Math.min(4, availableParallelism() - 1));
+}
 function chromiumRevisionOf(driver) {
     if (driver instanceof PlaywrightDriver && driver.chromiumVersion !== null) {
         return driver.chromiumVersion;

package/dist/testing.d.ts

@@ -5,15 +5,24 @@ import type { FfmpegRunner } from "./ffmpeg-runner.js";
 export declare class FakeBrowserDriver implements BrowserDriver {
     opens: number;
     closes: number;
+    /** Forks created across this driver and its descendants. */
+    forks: number;
+    /** Fork close() calls, aggregated on the root driver. */
+    forkCloses: number;
+    /** Frames rendered across this driver and all forks, in completion order. */
     renderedFrames: number[];
     private viewport;
+    private root;
     open(composition: KavioDocument, options?: BrowserOpenOptions): Promise<void>;
+    fork(): Promise<BrowserDriver>;
     renderFrame(frame: number, options?: BrowserFrameCaptureOptions): Promise<BrowserFrameCapture>;
     close(): Promise<void>;
 }
 export interface FakeFfmpegRunner extends FfmpegRunner {
     /** Argument lists captured from each run() call. */
     readonly calls: string[][];
+    /** Chunks consumed from the stdin stream across all run() calls. */
+    readonly stdinChunks: Uint8Array[];
 }
 export interface CreateFakeFfmpegRunnerOptions {
     /** When true, run() rejects with FFMPEG_FAILED (for cleanup-on-failure tests). */

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,oBAAoB,CAAC;AAI1F,qFAAqF;AACrF,qBAAa,iBAAkB,YAAW,aAAa;IACrD,KAAK,SAAK;IACV,MAAM,SAAK;IACX,cAAc,EAAE,MAAM,EAAE,CAAM;IAC9B,OAAO,CAAC,QAAQ,CAAgC;IAE1C,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAiBlG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,6BAA6B;IAC5C,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,6BAAkC,GAAG,gBAAgB,CAoBpG"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,oBAAoB,CAAC;AAI1F,qFAAqF;AACrF,qBAAa,iBAAkB,YAAW,aAAa;IACrD,KAAK,SAAK;IACV,MAAM,SAAK;IACX,4DAA4D;IAC5D,KAAK,SAAK;IACV,yDAAyD;IACzD,UAAU,SAAK;IACf,6EAA6E;IAC7E,cAAc,EAAE,MAAM,EAAE,CAAM;IAC9B,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,IAAI,CAAkC;IAExC,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjF,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;IAgB9B,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAkBlG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,6BAA6B;IAC5C,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,6BAAkC,GAAG,gBAAgB,CA4BpG"}

package/dist/testing.js

@@ -7,12 +7,33 @@ const FAKE_PNG = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
 export class FakeBrowserDriver {
     opens = 0;
     closes = 0;
+    /** Forks created across this driver and its descendants. */
+    forks = 0;
+    /** Fork close() calls, aggregated on the root driver. */
+    forkCloses = 0;
+    /** Frames rendered across this driver and all forks, in completion order. */
     renderedFrames = [];
     viewport = null;
+    root = null;
     async open(composition, options = {}) {
         this.opens += 1;
         this.viewport = options.viewport ?? createBrowserViewport(composition);
     }
+    async fork() {
+        if (this.viewport === null) {
+            throw renderError({
+                code: "RENDER_FRAME_FAILED",
+                stage: "render",
+                message: "FakeBrowserDriver.fork called before open()."
+            });
+        }
+        const root = this.root ?? this;
+        root.forks += 1;
+        const child = new FakeBrowserDriver();
+        child.root = root;
+        child.viewport = this.viewport;
+        return child;
+    }
     async renderFrame(frame, options = {}) {
         if (this.viewport === null) {
             throw renderError({
@@ -21,29 +42,42 @@ export class FakeBrowserDriver {
                 message: "FakeBrowserDriver.renderFrame called before open()."
             });
         }
-        this.renderedFrames.push(frame);
+        (this.root ?? this).renderedFrames.push(frame);
         return createPngFrameCapture({
             frame,
             bytes: FAKE_PNG,
             viewport: this.viewport,
-            omitBackground: options.omitBackground ?? true
+            omitBackground: options.omitBackground ?? true,
+            timing: { evaluateMs: 0, screenshotMs: 0 }
         });
     }
     async close() {
-        this.closes += 1;
+        if (this.root !== null) {
+            this.root.forkCloses += 1;
+        }
+        else {
+            this.closes += 1;
+        }
         this.viewport = null;
     }
 }
 /** FfmpegRunner that records args and writes a placeholder output file. */
 export function createFakeFfmpegRunner(options = {}) {
     const calls = [];
+    const stdinChunks = [];
     return {
         calls,
-        async run(args, _runOptions) {
+        stdinChunks,
+        async run(args, runOptions) {
             calls.push([...args]);
             if (options.fail === true) {
                 throw renderError({ code: "FFMPEG_FAILED", stage: "ffmpeg", message: "Fake ffmpeg failure." });
             }
+            if (runOptions?.stdin !== undefined) {
+                for await (const chunk of runOptions.stdin) {
+                    stdinChunks.push(chunk);
+                }
+            }
             const outputPath = args[args.length - 1];
             if (outputPath !== undefined && outputPath.length > 0) {
                 await mkdir(dirname(outputPath), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsra/kavio-render",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Render execution layer for Kavio: browser frame capture and FFmpeg encoding.",
   "license": "Elastic-2.0",
   "repository": {
@@ -13,11 +13,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@kitsra/kavio-browser-renderer": "0.1.2",
-    "@kitsra/kavio-core": "0.1.2",
-    "@kitsra/kavio-ffmpeg": "0.1.2",
-    "@kitsra/kavio-render-worker": "0.1.2",
-    "@kitsra/kavio-schema": "0.1.2"
+    "@kitsra/kavio-browser-renderer": "0.2.0",
+    "@kitsra/kavio-core": "0.2.0",
+    "@kitsra/kavio-ffmpeg": "0.2.0",
+    "@kitsra/kavio-render-worker": "0.2.0",
+    "@kitsra/kavio-schema": "0.2.0"
   },
   "optionalDependencies": {
     "ffmpeg-static": "5.3.0",