frameyard 0.8.0 → 0.10.0

package/dist/renderer/ffmpeg.js

@@ -1,6 +1,9 @@
 import { spawn } from "node:child_process";
 import { writeFile } from "node:fs/promises";
 import { FrameyardError } from "../errors.js";
+import { evaluatePresentation } from "../timeline/keyframes.js";
+import { transitionProgress } from "../timeline/transitions.js";
+import { keyframeChannelExpression, transitionGainExpression, transitionProgressExpression, } from "./keyframe-expressions.js";
 const STDERR_LIMIT = 16 * 1024;
 function captureTail(child) {
     let tail = "";
@@ -302,8 +305,7 @@ export async function probeMedia(filePath, options = {}) {
         throw new FrameyardError("FFPROBE_FAILED", `Could not parse ffprobe output for ${filePath}.`, { cause: error });
     }
 }
-/** Normalizes any decodable source to the 16 kHz mono PCM WAV that whisper.cpp expects. */
-export async function normalizeAudioForTranscription(options) {
+async function normalizeAudio(options) {
     await runCaptured("ffmpeg", [
         "-hide_banner",
         "-loglevel",
@@ -318,12 +320,20 @@ export async function normalizeAudioForTranscription(options) {
         "-ac",
         "1",
         "-ar",
-        "16000",
+        String(options.sampleRate),
         "-c:a",
         "pcm_s16le",
         options.outputPath,
     ], { signal: options.signal });
 }
+/** Normalizes any decodable source to the 16 kHz mono PCM WAV that whisper.cpp expects. */
+export async function normalizeAudioForTranscription(options) {
+    await normalizeAudio({ ...options, sampleRate: 16_000 });
+}
+/** Normalizes generated speech to the 24 kHz mono PCM WAV that Frameyard publishes. */
+export async function normalizeSpeechAudio(options) {
+    await normalizeAudio({ ...options, sampleRate: 24_000 });
+}
 export async function mixAudioTimeline(options) {
     if (options.clips.length === 0) {
         throw new FrameyardError("AUDIO_INVALID", "Cannot mix an empty audio timeline.");
@@ -340,10 +350,22 @@ export async function mixAudioTimeline(options) {
             trim.push(`duration=${formatNumber(clip.trimDuration)}`);
         }
         const delayMs = Math.round((clip.startFrame * 1000) / options.fps);
+        const gain = clip.volumeEnvelopes?.length
+            ? clip.volumeEnvelopes
+                .map((envelope) => transitionGainExpression({
+                progressExpression: `((${formatNumber(clip.startFrame)}+t*${formatNumber(options.fps)}-${formatNumber(envelope.startFrame)})/${formatNumber(envelope.endFrame - envelope.startFrame)})`,
+                ...(envelope.easing !== undefined ? { easing: envelope.easing } : {}),
+                role: envelope.role,
+            }))
+                .join("*")
+            : undefined;
+        const volume = gain === undefined
+            ? `volume=${formatNumber(clip.volume)}`
+            : `volume='${formatNumber(clip.volume)}*(${gain})':eval=frame`;
         const chain = [
             `atrim=${trim.join(":")}`,
             "asetpts=PTS-STARTPTS",
-            `volume=${formatNumber(clip.volume)}`,
+            volume,
             "aresample=48000",
             "aformat=sample_fmts=fltp:channel_layouts=stereo",
             "apad",
@@ -363,40 +385,14 @@ export async function mixAudioTimeline(options) {
     args.push("-filter_complex", filters.join(";"), "-map", "[audio]", "-t", formatNumber(options.durationSeconds), "-ar", "48000", "-ac", "2", "-c:a", "pcm_s16le", options.outputPath);
     await runCaptured("ffmpeg", args, { signal: options.signal });
 }
-export async function startVideoEncoder(options) {
+/** Drives an FFmpeg `image2pipe` encoder from PNG buffers. */
+async function startPipeEncoder(options) {
     if (options.signal?.aborted) {
         throw abortError();
     }
-    const args = [
-        "-hide_banner",
-        "-loglevel",
-        "error",
-        "-nostdin",
-        "-y",
-        "-f",
-        "image2pipe",
-        "-framerate",
-        formatNumber(options.fps),
-        "-i",
-        "pipe:0",
-    ];
-    if (options.audioPath) {
-        args.push("-i", options.audioPath);
-    }
-    args.push("-map", "0:v:0");
-    if (options.audioPath) {
-        args.push("-map", "1:a:0");
-    }
-    const codec = options.codec ?? "h264";
-    const container = options.container ?? "mp4";
-    args.push(...videoEncoderArgs(options.encoder ?? "libx264"), ...videoCodecTagArgs(codec, container), "-r", formatNumber(options.fps), "-frames:v", String(options.frames), "-t", formatNumber(options.durationSeconds));
-    if (options.audioPath) {
-        args.push(...audioEncoderArgs(codec));
-    }
-    args.push(...containerMuxFlags(container), ...containerMuxerArgs(container), options.outputPath);
     let child;
     try {
-        child = spawn("ffmpeg", args, { stdio: ["pipe", "pipe", "pipe"] });
+        child = spawn("ffmpeg", options.args, { stdio: ["pipe", "pipe", "pipe"] });
     }
     catch (error) {
         throw new FrameyardError("FFMPEG_FAILED", "Could not start FFmpeg.", { cause: error });
@@ -492,6 +488,332 @@ export async function startVideoEncoder(options) {
         abort,
     };
 }
+export async function startVideoEncoder(options) {
+    if (options.signal?.aborted) {
+        throw abortError();
+    }
+    const args = [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-nostdin",
+        "-y",
+        "-f",
+        "image2pipe",
+        "-framerate",
+        formatNumber(options.fps),
+        "-i",
+        "pipe:0",
+    ];
+    if (options.audioPath) {
+        args.push("-i", options.audioPath);
+    }
+    args.push("-map", "0:v:0");
+    if (options.audioPath) {
+        args.push("-map", "1:a:0");
+    }
+    const codec = options.codec ?? "h264";
+    const container = options.container ?? "mp4";
+    args.push(...videoEncoderArgs(options.encoder ?? "libx264"), ...videoCodecTagArgs(codec, container), "-r", formatNumber(options.fps), "-frames:v", String(options.frames), "-t", formatNumber(options.durationSeconds));
+    if (options.audioPath) {
+        args.push(...audioEncoderArgs(codec));
+    }
+    args.push(...containerMuxFlags(container), ...containerMuxerArgs(container), options.outputPath);
+    return startPipeEncoder({ args, frames: options.frames, ...(options.signal ? { signal: options.signal } : {}) });
+}
+function ffv1Threads(options) {
+    if (options.threads !== undefined) {
+        return options.threads;
+    }
+    const raw = process.env.FRAMEYARD_FFV1_THREADS;
+    if (raw === undefined) {
+        return 2;
+    }
+    const value = Number(raw);
+    return Number.isInteger(value) && value >= 0 ? value : 2;
+}
+/**
+ * Encodes PNG frames streamed over stdin into a lossless alpha-preserving FFV1
+ * file. The encoder starts before capture so encoding overlaps the next frame.
+ */
+export async function startFfv1Encoder(options) {
+    const threads = ffv1Threads(options);
+    const args = [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-nostdin",
+        "-y",
+        "-f",
+        "image2pipe",
+        "-framerate",
+        formatNumber(options.fps),
+        "-i",
+        "pipe:0",
+        "-c:v",
+        "ffv1",
+        "-level",
+        "3",
+        "-pix_fmt",
+        "bgra",
+        ...(threads > 0 ? ["-threads", String(threads)] : []),
+        options.outputPath,
+    ];
+    return startPipeEncoder({ args, frames: options.frames, ...(options.signal ? { signal: options.signal } : {}) });
+}
+/**
+ * Encodes a full-frame composition capture directly into a delivery segment.
+ * The captured PNGs keep their alpha; a solid background is composited first so
+ * the H.264/HEVC/VP9 segment has no transparency.
+ */
+export async function startDirectSegmentEncoder(options) {
+    if (options.background === "transparent") {
+        throw new FrameyardError("INTERNAL", "A direct delivery segment requires an opaque background.");
+    }
+    const encoder = options.encoder ?? encoderNameFor(options.codec, "software");
+    const durationSeconds = options.frames / options.fps;
+    const args = [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-nostdin",
+        "-y",
+        "-f",
+        "image2pipe",
+        "-framerate",
+        formatNumber(options.fps),
+        "-i",
+        "pipe:0",
+        "-f",
+        "lavfi",
+        "-i",
+        `color=c=${ffmpegBackgroundColor(options.background)}:s=${options.width}x${options.height}:r=${formatNumber(options.fps)}:d=${formatNumber(durationSeconds)}`,
+        "-filter_complex",
+        "[1:v][0:v]overlay=0:0:format=auto,format=yuv420p[out]",
+        "-map",
+        "[out]",
+        ...videoEncoderArgs(encoder),
+        ...videoCodecTagArgs(options.codec, options.container),
+        "-r",
+        formatNumber(options.fps),
+        "-frames:v",
+        String(options.frames),
+        "-t",
+        formatNumber(durationSeconds),
+        "-an",
+        ...containerMuxFlags(options.container),
+        ...containerMuxerArgs(options.container),
+        options.outputPath,
+    ];
+    return startPipeEncoder({ args, frames: options.frames, ...(options.signal ? { signal: options.signal } : {}) });
+}
+/**
+ * Encodes two full-frame composition captures directly into one delivery
+ * segment. Layer 0 is the base, layer 1 is the overlay, and both keep alpha.
+ */
+export async function startDualPipeSegmentEncoder(options) {
+    if (options.background === "transparent") {
+        throw new FrameyardError("INTERNAL", "A dual-pipe delivery segment requires an opaque background.");
+    }
+    const encoder = options.encoder ?? encoderNameFor(options.codec, "software");
+    const durationSeconds = options.frames / options.fps;
+    const overlay = options.overlay;
+    const overlayFilters = [];
+    if (overlay) {
+        const fullFrame = overlay.width === undefined &&
+            overlay.height === undefined &&
+            overlay.sourceWidth === options.width &&
+            overlay.sourceHeight === options.height;
+        if (!fullFrame) {
+            overlayFilters.push(fitFilter(overlay, options.width, options.height));
+        }
+        overlayFilters.push("format=rgba");
+    }
+    const overlayGraph = overlay
+        ? `[1:v]${overlayFilters.join(",")}[ov];[base][ov]overlay=${placementFilter(overlay, 0)}:format=auto,format=yuv420p[out]`
+        : "[base][1:v]overlay=0:0:format=auto,format=yuv420p[out]";
+    const args = [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-nostdin",
+        "-y",
+        "-f",
+        "image2pipe",
+        "-framerate",
+        formatNumber(options.fps),
+        "-i",
+        "pipe:0",
+        "-f",
+        "image2pipe",
+        "-framerate",
+        formatNumber(options.fps),
+        "-i",
+        "pipe:3",
+        "-f",
+        "lavfi",
+        "-i",
+        `color=c=${ffmpegBackgroundColor(options.background)}:s=${options.width}x${options.height}:r=${formatNumber(options.fps)}:d=${formatNumber(durationSeconds)}`,
+        "-filter_complex",
+        `[2:v][0:v]overlay=0:0:format=auto[base];${overlayGraph}`,
+        "-map",
+        "[out]",
+        ...videoEncoderArgs(encoder),
+        ...videoCodecTagArgs(options.codec, options.container),
+        "-r",
+        formatNumber(options.fps),
+        "-frames:v",
+        String(options.frames),
+        "-t",
+        formatNumber(durationSeconds),
+        "-an",
+        ...containerMuxFlags(options.container),
+        ...containerMuxerArgs(options.container),
+        options.outputPath,
+    ];
+    let child;
+    try {
+        child = spawn("ffmpeg", args, { stdio: ["pipe", "ignore", "pipe", "pipe"] });
+    }
+    catch (error) {
+        throw new FrameyardError("FFMPEG_FAILED", "Could not start FFmpeg.", { cause: error });
+    }
+    const stderrTail = captureTail(child);
+    await new Promise((resolve, reject) => {
+        child.once("spawn", resolve);
+        child.once("error", (error) => {
+            if (error.code === "ENOENT") {
+                reject(new FrameyardError("FFMPEG_FAILED", "FFmpeg was not found on PATH. Install FFmpeg and ensure it is available.", { cause: error }));
+            }
+            else {
+                reject(new FrameyardError("FFMPEG_FAILED", `FFmpeg could not start: ${error.message}`, { cause: error }));
+            }
+        });
+    });
+    const input0 = child.stdio[0];
+    const input1 = child.stdio[3];
+    const closed = new Promise((resolve) => {
+        child.once("close", (code, signal) => resolve({ code, signal }));
+    });
+    let finished = false;
+    const framesWritten = [0, 0];
+    const onAbort = () => {
+        input0.destroy();
+        input1.destroy();
+        child.kill("SIGKILL");
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    async function abort() {
+        if (finished) {
+            return;
+        }
+        finished = true;
+        options.signal?.removeEventListener("abort", onAbort);
+        input0.destroy();
+        input1.destroy();
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill("SIGKILL");
+        }
+        await closed.catch(() => undefined);
+    }
+    async function write(layer, png) {
+        if (finished) {
+            throw new FrameyardError("FFMPEG_FAILED", "Cannot write a frame after the encoder finished.");
+        }
+        if (options.signal?.aborted) {
+            throw abortError();
+        }
+        const stream = layer === 0 ? input0 : input1;
+        await new Promise((resolve, reject) => {
+            const onError = (error) => {
+                stream.off("error", onError);
+                if (options.signal?.aborted) {
+                    reject(abortError());
+                }
+                else {
+                    reject(new FrameyardError("FFMPEG_FAILED", `FFmpeg stopped while accepting layer ${layer} frames: ${error.message}`, {
+                        cause: error,
+                    }));
+                }
+            };
+            stream.once("error", onError);
+            stream.write(png, (error) => {
+                stream.off("error", onError);
+                if (error) {
+                    reject(new FrameyardError("FFMPEG_FAILED", `Could not write a layer ${layer} frame to FFmpeg: ${error.message}`, {
+                        cause: error,
+                    }));
+                }
+                else {
+                    framesWritten[layer] += 1;
+                    resolve();
+                }
+            });
+        });
+    }
+    return {
+        writeFrame: write,
+        async finish() {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            options.signal?.removeEventListener("abort", onAbort);
+            input0.end();
+            input1.end();
+            const { code, signal } = await closed;
+            if (options.signal?.aborted) {
+                throw abortError();
+            }
+            if (code !== 0) {
+                const detail = stderrTail();
+                throw new FrameyardError("FFMPEG_FAILED", `FFmpeg encoding failed${signal ? ` (${signal})` : code === null ? "" : ` (exit ${code})`}${detail ? `:\n${detail}` : "."}`);
+            }
+            if (framesWritten[0] !== options.frames || framesWritten[1] !== options.frames) {
+                throw new FrameyardError("FFMPEG_FAILED", `FFmpeg encoded ${framesWritten[0]}/${framesWritten[1]} frames but ${options.frames} were required per layer.`);
+            }
+        },
+        abort,
+    };
+}
+/**
+ * Builds FFmpeg's narrow layer input from a projected scene layer. The mapper
+ * owns the scene-to-filter boundary; capture chooses the artifact and its input
+ * mode, while the scene owns presentation, keyframes, and transition roles.
+ */
+export function sceneLayerToCompositeLayer(layer, artifact) {
+    const transform = layer.transform;
+    const transition = layer.transition;
+    return {
+        input: artifact.input,
+        path: artifact.path,
+        sourceWidth: layer.sourceWidth,
+        sourceHeight: layer.sourceHeight,
+        ...(transform.width !== undefined && transform.height !== undefined
+            ? { width: transform.width, height: transform.height }
+            : {}),
+        fit: transform.fit,
+        x: transform.x,
+        y: transform.y,
+        scale: transform.scale,
+        rotation: transform.rotation,
+        opacity: transform.opacity,
+        blend: layer.blend,
+        ...(artifact.sourceStartFrame !== undefined ? { sourceStartFrame: artifact.sourceStartFrame } : {}),
+        ...(layer.keyframes !== undefined ? { keyframes: layer.keyframes } : {}),
+        clipStart: layer.clip.start,
+        ...(transition !== undefined
+            ? {
+                transition: {
+                    role: transition.role,
+                    start: transition.window.start,
+                    end: transition.window.end,
+                    ...(transition.window.easing !== undefined ? { easing: transition.window.easing } : {}),
+                },
+            }
+            : {}),
+    };
+}
 function ffmpegBackgroundColor(value) {
     if (value === "transparent") {
         return "black@0.0";
@@ -533,25 +855,165 @@ function fitFilter(layer, stageWidth, stageHeight) {
     const fittedHeight = Math.max(1, Math.round(sourceHeight * scale));
     return `scale=${fittedWidth}:${fittedHeight},pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=black@0`;
 }
-function layerFilter(layer, stageWidth, stageHeight, fps) {
-    const filters = [
+function layerTransform(layer) {
+    return {
+        fit: layer.fit,
+        x: layer.x,
+        y: layer.y,
+        ...(layer.width !== undefined && layer.height !== undefined ? { width: layer.width, height: layer.height } : {}),
+        scale: layer.scale,
+        rotation: layer.rotation,
+        opacity: layer.opacity,
+    };
+}
+function hasKeyframe(layer, channel) {
+    return layer.keyframes?.[channel] !== undefined;
+}
+/** The incoming layer's animated alpha at an absolute timeline frame. */
+function transitionAlphaAt(layer, frame) {
+    if (layer.transition?.role !== "in") {
+        return 1;
+    }
+    return transitionProgress(layer.transition, frame);
+}
+/** False when a keyed or transitioning layer is invisible for every frame of the range. */
+function isLayerVisibleInRange(layer, frameOffset, frames) {
+    const animated = hasKeyframe(layer, "opacity") || hasKeyframe(layer, "scale");
+    if (!animated && layer.transition?.role !== "in") {
+        return layer.opacity > 0 && layer.scale > 0;
+    }
+    const transform = layerTransform(layer);
+    const clipStart = layer.clipStart ?? 0;
+    for (let index = 0; index < frames; index += 1) {
+        const frame = frameOffset + index;
+        const values = evaluatePresentation(transform, layer.keyframes, frame - clipStart);
+        if (values.opacity * transitionAlphaAt(layer, frame) > 0 && values.scale > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+function baseLayerFilters(layer, stageWidth, stageHeight, fps) {
+    const fullFrame = layer.width === undefined &&
+        layer.height === undefined &&
+        layer.sourceWidth === stageWidth &&
+        layer.sourceHeight === stageHeight;
+    return [
         // Matroska and WebM timestamps can be quantized to milliseconds. Normalize
         // every timed layer to the project frame rate before overlay framesync so
         // it does not duplicate or drop frames. Still images are already static.
-        ...(layer.kind === "image" ? [] : [`fps=${formatNumber(fps)}`]),
-        fitFilter(layer, stageWidth, stageHeight),
+        ...(layer.input === "image" ? [] : [`fps=${formatNumber(fps)}`]),
+        // A source that already matches the stage has no fit work to do.
+        ...(fullFrame ? [] : [fitFilter(layer, stageWidth, stageHeight)]),
         "format=rgba",
     ];
-    if (layer.scale !== 1) {
-        filters.push(`scale=iw*${formatNumber(layer.scale)}:ih*${formatNumber(layer.scale)}`);
+}
+/** Dimensions entering the rotate filter for this layer. */
+function rotationInputSize(layer, stageWidth, stageHeight) {
+    const width = layer.width ?? stageWidth;
+    const height = layer.height ?? stageHeight;
+    if (layer.keyframes?.scale !== undefined) {
+        // Animated scale is applied after rotation, keeping the rotate input fixed.
+        return { width, height };
+    }
+    return {
+        width: Math.max(1, Math.ceil(width * layer.scale)),
+        height: Math.max(1, Math.ceil(height * layer.scale)),
+    };
+}
+function rotatedBounds(width, height, degrees) {
+    const radians = (degrees * Math.PI) / 180;
+    const cosine = Math.abs(Math.cos(radians));
+    const sine = Math.abs(Math.sin(radians));
+    // Two extra pixels absorb filter rounding and anti-aliased edge pixels.
+    return {
+        width: Math.max(1, Math.ceil(width * cosine + height * sine) + 2),
+        height: Math.max(1, Math.ceil(width * sine + height * cosine) + 2),
+    };
+}
+/**
+ * FFmpeg's rotate filter clips to a fixed output size. A keyed rotation uses a
+ * square diagonal bound so every segment uses the same size and corners stay
+ * visible at any angle. Static rotation uses its exact bounding box.
+ */
+function rotationOutputSize(layer, stageWidth, stageHeight) {
+    const input = rotationInputSize(layer, stageWidth, stageHeight);
+    if (layer.keyframes?.rotation) {
+        const diagonal = Math.max(1, Math.ceil(Math.hypot(input.width, input.height)) + 2);
+        return { width: diagonal, height: diagonal };
     }
-    if (layer.rotation !== 0) {
-        filters.push(`rotate=angle=${formatNumber(layer.rotation)}*PI/180:fillcolor=black@0`);
+    return rotatedBounds(input.width, input.height, layer.rotation);
+}
+function needsOpacityMask(layer) {
+    return hasKeyframe(layer, "opacity") || hasKeyframe(layer, "scale") || layer.transition?.role === "in";
+}
+/**
+ * Presentation filters after the optional opacity mask. Animated scale is
+ * applied after rotation because uniform scale and rotation commute; rotation
+ * then keeps a fixed input size for the rotate filter.
+ */
+function presentationLayerFilters(layer, stageWidth, stageHeight, frameOffset) {
+    const filters = [];
+    const clipStart = layer.clipStart ?? 0;
+    const frameOptions = { frameVariable: "n", frameOffset, clipStart };
+    const scaleKeys = layer.keyframes?.scale;
+    const rotationKeys = layer.keyframes?.rotation;
+    const opacityKeys = layer.keyframes?.opacity;
+    const addRotation = () => {
+        if (rotationKeys || layer.rotation !== 0) {
+            const output = rotationOutputSize(layer, stageWidth, stageHeight);
+            const outputSize = `ow=${output.width}:oh=${output.height}`;
+            if (rotationKeys) {
+                const angle = keyframeChannelExpression("rotation", rotationKeys, frameOptions);
+                filters.push(`rotate=angle='(${angle})*PI/180':fillcolor=black@0:${outputSize}`);
+            }
+            else {
+                filters.push(`rotate=angle=${formatNumber(layer.rotation)}*PI/180:fillcolor=black@0:${outputSize}`);
+            }
+        }
+    };
+    if (scaleKeys) {
+        addRotation();
+        const scale = keyframeChannelExpression("scale", scaleKeys, frameOptions);
+        filters.push(`scale=w='max(1,iw*(${scale}))':h='max(1,ih*(${scale}))':eval=frame`);
     }
-    if (layer.opacity < 1) {
+    else {
+        if (layer.scale !== 1) {
+            filters.push(`scale=iw*${formatNumber(layer.scale)}:ih*${formatNumber(layer.scale)}`);
+        }
+        addRotation();
+    }
+    // A transitioning layer carries its opacity in the animated mask instead.
+    if (!opacityKeys && !scaleKeys && layer.transition?.role !== "in" && layer.opacity < 1) {
         filters.push(`colorchannelmixer=aa=${formatNumber(layer.opacity)}`);
     }
-    return filters.join(",");
+    return filters;
+}
+/** Builds the animated alpha mask at the fitted box size. */
+function opacityMaskFilter(options) {
+    const { layer, stageWidth, stageHeight, frameOffset, inputIndex, outputLabel } = options;
+    const clipStart = layer.clipStart ?? 0;
+    const frameOptions = { frameVariable: "N", frameOffset, clipStart };
+    const opacityKeys = layer.keyframes?.opacity;
+    const scaleKeys = layer.keyframes?.scale;
+    const opacity = opacityKeys
+        ? keyframeChannelExpression("opacity", opacityKeys, frameOptions)
+        : formatNumber(layer.opacity);
+    const scale = scaleKeys ? keyframeChannelExpression("scale", scaleKeys, frameOptions) : undefined;
+    const visible = scale !== undefined ? `if(gt(${scale},0),1,0)` : "1";
+    const transition = layer.transition?.role === "in"
+        ? transitionProgressExpression({
+            frameVariable: "N",
+            frameOffset,
+            start: layer.transition.start,
+            end: layer.transition.end,
+            ...(layer.transition.easing !== undefined ? { easing: layer.transition.easing } : {}),
+        })
+        : undefined;
+    const alpha = `min(1,max(0,(${opacity})*(${visible})${transition !== undefined ? `*(${transition})` : ""}))`;
+    const width = layer.width ?? stageWidth;
+    const height = layer.height ?? stageHeight;
+    return `[${inputIndex}:v]format=rgba,geq=r=0:g=0:b=0:a='255*${alpha}',scale=${width}:${height}:flags=neighbor,format=rgba[${outputLabel}]`;
 }
 /** W3C soft-light in 0-255 space; FFmpeg's native mode uses a different formula. */
 const SOFT_LIGHT_EXPRESSION = "if(lt(B,128), A-(1-2*B/255)*A*(1-A/255), A+(2*B/255-1)*(if(lt(A,64),((16*A/255-12)*A/255+4)*A/255,sqrt(A/255))*255-A))";
@@ -580,8 +1042,17 @@ function blendSpec(mode) {
         sourceFirst: mode === "color-dodge" || mode === "color-burn",
     };
 }
-function placementFilter(layer) {
-    return `x=(main_w-overlay_w)/2+${formatNumber(layer.x)}:y=(main_h-overlay_h)/2+${formatNumber(layer.y)}`;
+function placementFilter(layer, frameOffset) {
+    const clipStart = layer.clipStart ?? 0;
+    const frameOptions = { frameVariable: "n", frameOffset, clipStart };
+    const xKeys = layer.keyframes?.x;
+    const yKeys = layer.keyframes?.y;
+    const x = xKeys ? keyframeChannelExpression("x", xKeys, frameOptions) : formatNumber(layer.x);
+    const y = yKeys ? keyframeChannelExpression("y", yKeys, frameOptions) : formatNumber(layer.y);
+    if (!xKeys && !yKeys) {
+        return `x=(main_w-overlay_w)/2+${x}:y=(main_h-overlay_h)/2+${y}`;
+    }
+    return `x='(main_w-overlay_w)/2+(${x})':y='(main_h-overlay_h)/2+(${y})':eval=frame`;
 }
 /**
  * Builds the FFmpeg filter graph for one timeline composite. Blend layers are
@@ -605,7 +1076,7 @@ function buildCompositeGraph(options) {
     let current = "base0";
     let inputIndex = 0;
     let includedIndex = 0;
-    const blendedLayers = options.layers.filter((layer) => layer.blend !== "normal" && layer.opacity > 0 && layer.scale > 0);
+    const blendedLayers = options.layers.filter((layer) => layer.blend !== "normal" && isLayerVisibleInRange(layer, options.frameOffset, options.frames));
     const canvasLabels = [];
     if (blendedLayers.length > 0) {
         args.push("-f", "lavfi", "-i", `color=c=black@0.0:s=${options.width}x${options.height}:r=${formatNumber(options.fps)}:d=${formatNumber(durationSeconds)}`);
@@ -620,10 +1091,19 @@ function buildCompositeGraph(options) {
     }
     let canvasIndex = 0;
     for (const layer of options.layers) {
-        if (layer.opacity <= 0 || layer.scale <= 0) {
+        if (!isLayerVisibleInRange(layer, options.frameOffset, options.frames)) {
             continue;
         }
-        if (layer.kind === "video") {
+        const masked = needsOpacityMask(layer);
+        let maskInput = 0;
+        if (masked) {
+            args.push("-f", "lavfi", "-i", 
+            // FFmpeg 6 rejects a 1x1 yuv420p source (chroma planes round to zero).
+            `color=c=black@0.0:s=2x2:r=${formatNumber(options.fps)}:d=${formatNumber(durationSeconds)}`);
+            inputIndex += 1;
+            maskInput = inputIndex;
+        }
+        if (layer.input === "video") {
             const startSeconds = (layer.sourceStartFrame ?? 0) / options.fps;
             if (options.segment) {
                 args.push("-ss", formatNumber(startSeconds), "-t", formatNumber(durationSeconds), "-i", layer.path, "-an");
@@ -632,7 +1112,7 @@ function buildCompositeGraph(options) {
                 args.push("-ss", formatNumber(startSeconds), "-i", layer.path, "-an");
             }
         }
-        else if (layer.kind === "image") {
+        else if (layer.input === "image") {
             if (options.segment) {
                 args.push("-loop", "1", "-framerate", formatNumber(options.fps), "-t", formatNumber(durationSeconds), "-i", layer.path, "-an");
             }
@@ -645,15 +1125,32 @@ function buildCompositeGraph(options) {
         }
         inputIndex += 1;
         includedIndex += 1;
-        filters.push(`[${inputIndex}:v]${layerFilter(layer, options.width, options.height, options.fps)}[l${includedIndex}]`);
+        const layerInput = inputIndex;
+        const base = baseLayerFilters(layer, options.width, options.height, options.fps);
+        const presentation = presentationLayerFilters(layer, options.width, options.height, options.frameOffset);
+        if (masked) {
+            filters.push(`[${layerInput}:v]${base.join(",")}[v${includedIndex}]`);
+            filters.push(opacityMaskFilter({
+                layer,
+                stageWidth: options.width,
+                stageHeight: options.height,
+                frameOffset: options.frameOffset,
+                inputIndex: maskInput,
+                outputLabel: `km${includedIndex}`,
+            }));
+            filters.push(`[v${includedIndex}][km${includedIndex}]blend=c0_mode=normal:c1_mode=normal:c2_mode=normal:c3_mode=multiply${presentation.length > 0 ? `,${presentation.join(",")}` : ""}[l${includedIndex}]`);
+        }
+        else {
+            filters.push(`[${layerInput}:v]${[...base, ...presentation].join(",")}[l${includedIndex}]`);
+        }
         if (layer.blend === "normal") {
-            filters.push(`[${current}][l${includedIndex}]overlay=${placementFilter(layer)}:format=auto[b${includedIndex}]`);
+            filters.push(`[${current}][l${includedIndex}]overlay=${placementFilter(layer, options.frameOffset)}:format=auto[b${includedIndex}]`);
             current = `b${includedIndex}`;
             continue;
         }
         const canvas = canvasLabels[canvasIndex];
         canvasIndex += 1;
-        filters.push(`[${canvas}][l${includedIndex}]overlay=${placementFilter(layer)}:format=auto,format=rgba,split=2[pb${includedIndex}][pm${includedIndex}]`);
+        filters.push(`[${canvas}][l${includedIndex}]overlay=${placementFilter(layer, options.frameOffset)}:format=auto,format=rgba,split=2[pb${includedIndex}][pm${includedIndex}]`);
         filters.push(`[${current}]format=rgba,split=3[bc${includedIndex}][bm${includedIndex}][bo${includedIndex}]`);
         filters.push(`[bm${includedIndex}]alphaextract,format=rgba[mask${includedIndex}]`);
         const spec = blendSpec(layer.blend);
@@ -666,24 +1163,38 @@ function buildCompositeGraph(options) {
     }
     return { args, filters, output: current };
 }
-/** Encode a numbered PNG sequence into a lossless alpha-preserving FFV1 file. */
-export async function encodePngSequenceToFfv1(options) {
-    await runCaptured("ffmpeg", [
-        "-y",
-        "-v",
+/** Re-encodes one full-frame video range directly into a delivery segment. */
+export async function encodeVideoSegmentDirect(options) {
+    const encoder = options.encoder ?? encoderNameFor(options.codec, "software");
+    const startSeconds = options.sourceStartFrame / options.fps;
+    const durationSeconds = options.frames / options.fps;
+    const args = [
+        "-hide_banner",
+        "-loglevel",
         "error",
-        "-framerate",
-        formatNumber(options.fps),
+        "-nostdin",
+        "-y",
+        ...(startSeconds > 0 ? ["-ss", formatNumber(startSeconds)] : []),
         "-i",
-        options.pattern,
-        "-c:v",
-        "ffv1",
-        "-level",
-        "3",
-        "-pix_fmt",
-        "bgra",
+        options.inputPath,
+        "-map",
+        "0:v:0",
+        "-an",
+        "-vf",
+        `fps=${formatNumber(options.fps)},format=rgba,format=yuv420p`,
+        ...videoEncoderArgs(encoder),
+        ...videoCodecTagArgs(options.codec, options.container),
+        "-r",
+        formatNumber(options.fps),
+        "-frames:v",
+        String(options.frames),
+        "-t",
+        formatNumber(durationSeconds),
+        ...containerMuxFlags(options.container),
+        ...containerMuxerArgs(options.container),
         options.outputPath,
-    ], { signal: options.signal });
+    ];
+    await runCaptured("ffmpeg", args, { signal: options.signal });
 }
 /** Composites one timeline segment into H.264 or an alpha-preserving FFV1 file. */
 export async function compositeTimelineSegment(options) {
@@ -692,6 +1203,7 @@ export async function compositeTimelineSegment(options) {
         height: options.height,
         fps: options.fps,
         frames: options.frames,
+        frameOffset: options.frameOffset ?? 0,
         background: options.background,
         layers: options.layers,
         segment: true,
@@ -766,6 +1278,7 @@ export async function compositeTimelineFrame(options) {
         height: options.height,
         fps: options.fps,
         frames: 1,
+        frameOffset: options.frameOffset ?? 0,
         background: options.background,
         layers: options.layers,
         segment: false,