frameyard 0.8.0 → 0.10.0

package/dist/renderer/timeline.js

@@ -8,9 +8,16 @@ import { validateHtmlComposition } from "../html/validate.js";
 import { startPreviewServer } from "../server/server.js";
 import { inspectTimelineAudio } from "./audio.js";
 import { openCompositionSession } from "./browser.js";
-import { assertContainerCodec, assertFfmpegCapabilities, compositeTimelineFrame, compositeTimelineSegment, concatTimelineSegments, CONTAINER_EXTENSION, defaultCodecForContainer, ENCODER_SESSION_LIMIT, encodePngSequenceToFfv1, mixAudioTimeline, muxVideoWithAudio, resolveVideoEncoder, } from "./ffmpeg.js";
+import { assertContainerCodec, assertFfmpegCapabilities, compositeTimelineFrame, compositeTimelineSegment, concatTimelineSegments, CONTAINER_EXTENSION, defaultCodecForContainer, encodeVideoSegmentDirect, ENCODER_SESSION_LIMIT, mixAudioTimeline, muxVideoWithAudio, resolveVideoEncoder, sceneLayerToCompositeLayer, startDirectSegmentEncoder, startDualPipeSegmentEncoder, startFfv1Encoder, } from "./ffmpeg.js";
+import { createSemaphore } from "./concurrency.js";
+import { CompositionSessionPool } from "./session-pool.js";
 import { inspectTranscriptClips } from "./transcripts.js";
+import { startTiming } from "./timings.js";
+import { evaluatePresentation } from "../timeline/keyframes.js";
+import { transitionProgress } from "../timeline/transitions.js";
+import { KEYFRAME_CHANNELS } from "../timeline/schema.js";
 import { planTimelineRender } from "../timeline/plan.js";
+import { projectScene, transitionSpans } from "../timeline/scene.js";
 import { resolveProjectTimeline, } from "../timeline/resolve.js";
 export const MAX_TIMELINE_WORKERS = 16;
 function validateWorkers(value) {
@@ -30,11 +37,42 @@ function validateWorkers(value) {
 export function clampTimelineWorkers(workers, encoder) {
     return Math.min(workers, ENCODER_SESSION_LIMIT[encoder]);
 }
+const MAX_CAPTURE_CONCURRENCY = 12;
+/**
+ * Capture sessions are bounded independently from segment workers. A segment
+ * with two or three layers can overlap its captures without letting an
+ * eight-worker render open sixteen browsers.
+ */
+function captureConcurrency(workers) {
+    const raw = process.env.FRAMEYARD_CAPTURE_CONCURRENCY;
+    if (raw !== undefined) {
+        const value = Number(raw);
+        if (Number.isInteger(value) && value > 0) {
+            return Math.min(value, 32);
+        }
+    }
+    return Math.min(workers * 2, MAX_CAPTURE_CONCURRENCY);
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw new FrameyardError("RENDER_FAILED", "Operation cancelled.");
     }
 }
+async function withCaptureSlot(limiter, signal, task) {
+    if (!limiter) {
+        throwIfAborted(signal);
+        return task();
+    }
+    throwIfAborted(signal);
+    const release = await limiter.acquire();
+    try {
+        throwIfAborted(signal);
+        return await task();
+    }
+    finally {
+        release();
+    }
+}
 async function pathExists(filePath) {
     try {
         await stat(filePath);
@@ -136,19 +174,6 @@ function compositionDiagnostic(diagnostic, timelineId, clip, compositionId) {
 function clampVolume(value) {
     return Math.min(1, Math.max(0, value));
 }
-function visualSourceSize(clip, timeline) {
-    const source = clip.source;
-    if (source.kind === "composition") {
-        return { width: source.metadata.width, height: source.metadata.height };
-    }
-    if (source.kind === "video" || source.kind === "image") {
-        if (source.width === undefined || source.height === undefined) {
-            throw new FrameyardError("TIMELINE_MEDIA_INVALID", `Media ${source.src} is missing width/height metadata for clip "${clip.id}".`);
-        }
-        return { width: source.width, height: source.height };
-    }
-    return { width: timeline.format.width, height: timeline.format.height };
-}
 function mapCompositionAudio(clip, audio, fps, window) {
     if (window.muted) {
         return null;
@@ -178,11 +203,16 @@ function mapCompositionAudio(clip, audio, fps, window) {
         trimStart: audio.trimStart + (effectiveStart - audio.startFrame) / fps,
         trimDuration: duration,
         volume: clampVolume(audio.volume * window.gain),
+        ...(window.envelopes.length > 0 ? { envelopes: window.envelopes } : {}),
+        // Without an explicit duration the source ends naturally; any remaining
+        // mapped window is silence, not an overrun.
+        ...(audio.trimDuration === undefined ? { allowShortSource: true } : {}),
     };
 }
 function collectTimelineAudio(timeline, window, clips, transcripts) {
     const fps = timeline.format.fps;
     const trackById = new Map(timeline.tracks.map((track) => [track.id, track]));
+    const spansByClip = transitionSpans(timeline);
     for (const clip of timeline.clips) {
         const source = clip.source;
         const mappedStart = clip.start + window.frameOffset;
@@ -194,6 +224,13 @@ function collectTimelineAudio(timeline, window, clips, transcripts) {
         }
         const clipGain = window.gain * (clip.audio?.gain ?? 1);
         const clipMuted = window.muted || (clip.audio?.muted ?? false);
+        const ownEnvelopes = (spansByClip.get(clip.id) ?? []).map((span) => ({
+            startFrame: span.start + window.frameOffset,
+            endFrame: span.end + window.frameOffset,
+            ...(span.easing !== undefined ? { easing: span.easing } : {}),
+            role: span.role,
+        }));
+        const envelopes = ownEnvelopes.length > 0 ? [...window.envelopes, ...ownEnvelopes] : window.envelopes;
         if (source.kind === "composition") {
             for (const transcript of source.transcriptClips) {
                 transcripts.set(`${transcript.src}\u0000${transcript.words}`, transcript);
@@ -202,13 +239,13 @@ function collectTimelineAudio(timeline, window, clips, transcripts) {
                 continue;
             }
             for (const audio of source.audioClips) {
-                const mapped = mapCompositionAudio(clip, audio, fps, { ...window, gain: clipGain });
+                const mapped = mapCompositionAudio(clip, audio, fps, { ...window, gain: clipGain, envelopes });
                 if (mapped) {
                     clips.push(mapped);
                 }
             }
             for (const audio of source.embeddedAudioClips) {
-                const mapped = mapCompositionAudio(clip, audio, fps, { ...window, gain: clipGain });
+                const mapped = mapCompositionAudio(clip, audio, fps, { ...window, gain: clipGain, envelopes });
                 if (mapped) {
                     clips.push({ ...mapped, allowSilent: true });
                 }
@@ -222,6 +259,7 @@ function collectTimelineAudio(timeline, window, clips, transcripts) {
                 endFrame,
                 gain: clipGain,
                 muted: clipMuted,
+                envelopes,
             }, clips, transcripts);
             continue;
         }
@@ -233,6 +271,7 @@ function collectTimelineAudio(timeline, window, clips, transcripts) {
                     trimStart: clip.sourceIn / fps + (startFrame - mappedStart) / fps,
                     trimDuration: (endFrame - startFrame) / fps,
                     volume: clampVolume(clipGain),
+                    ...(envelopes.length > 0 ? { envelopes } : {}),
                 });
             }
             continue;
@@ -248,6 +287,7 @@ function collectTimelineAudio(timeline, window, clips, transcripts) {
                 trimStart: clip.sourceIn / fps + (startFrame - mappedStart) / fps,
                 trimDuration: (endFrame - startFrame) / fps,
                 volume: clampVolume(clipGain * (track.gain ?? 1)),
+                ...(envelopes.length > 0 ? { envelopes } : {}),
             });
         }
     }
@@ -255,7 +295,7 @@ function collectTimelineAudio(timeline, window, clips, transcripts) {
 function buildAudioClips(timeline) {
     const clips = [];
     const transcripts = new Map();
-    collectTimelineAudio(timeline, { frameOffset: 0, startFrame: 0, endFrame: timeline.durationInFrames, gain: 1, muted: false }, clips, transcripts);
+    collectTimelineAudio(timeline, { frameOffset: 0, startFrame: 0, endFrame: timeline.durationInFrames, gain: 1, muted: false, envelopes: [] }, clips, transcripts);
     return { clips, transcripts: [...transcripts.values()] };
 }
 /** Resolved timeline audio for preview surfaces. */
@@ -263,7 +303,7 @@ export function resolveTimelineAudio(timeline) {
     const { clips, transcripts } = buildAudioClips(timeline);
     return {
         clips: clips.map((clip) => {
-            const { allowSilent: _allowSilent, ...resolved } = clip;
+            const { allowSilent: _allowSilent, allowShortSource: _allowShortSource, ...resolved } = clip;
             return resolved;
         }),
         transcripts,
@@ -321,8 +361,13 @@ async function captureStaticCompositionLayer(options) {
         throw error;
     }
 }
-async function captureCompositionLayer(options) {
-    const { project, timeline, clip, source, segment, layerIndex, serverUrl, segmentDir, infoCache } = options;
+/**
+ * Opens a composition session, captures every frame of the segment, and hands
+ * each PNG to `writeFrame`. The caller owns the encoder lifecycle so the same
+ * loop can feed an FFV1 intermediate or a direct delivery segment.
+ */
+async function captureCompositionFrames(options, writeFrame) {
+    const { project, timeline, clip, source, segment, layerIndex, serverUrl, infoCache } = options;
     const propsKey = JSON.stringify(clip.props ?? null);
     const cacheKey = `${source.entry}\u0000${propsKey}`;
     let validation = infoCache.get(cacheKey);
@@ -342,38 +387,293 @@ async function captureCompositionLayer(options) {
     if (!layer) {
         throw new FrameyardError("INTERNAL", `Missing layer ${layerIndex} for segment ${segment.index}.`);
     }
-    const prefix = `comp-${layerIndex}`;
-    const session = await openCompositionSession({
+    const sessionTiming = startTiming("timeline.layer.session", {
+        entry: source.entry,
+        layer: layerIndex,
+        segment: segment.index,
+    });
+    const sessionKey = JSON.stringify([source.entry, clip.props ?? null, true]);
+    const openOptions = {
         serverUrl,
         entry: source.entry,
         props: clip.props,
         info: validation.info,
         staticDiagnostics: validation.diagnostics,
         transparentBackground: true,
-    });
+    };
+    const lease = options.sessionPool
+        ? await options.sessionPool.acquire(sessionKey, () => openCompositionSession(openOptions))
+        : await (async () => {
+            const session = await openCompositionSession(openOptions);
+            return {
+                session,
+                reused: false,
+                release: () => session.close(),
+                discard: () => session.close(),
+            };
+        })();
+    sessionTiming.finish({ reused: lease.reused });
+    const session = lease.session;
+    let healthy = false;
     const diagnostics = [];
+    const captureTiming = startTiming("timeline.layer.capture_frames", {
+        entry: source.entry,
+        layer: layerIndex,
+        segment: segment.index,
+        frames: segment.frames,
+    });
+    let seekMs = 0;
+    let captureMs = 0;
+    let writeMs = 0;
+    let pngBytes = 0;
     try {
         for (let offset = 0; offset < segment.frames; offset += 1) {
             throwIfAborted(options.signal);
+            const seekStarted = performance.now();
             await session.seek(layer.sourceStart + offset);
+            seekMs += performance.now() - seekStarted;
+            const captureStarted = performance.now();
             const png = await session.capture();
-            await writeFile(path.join(segmentDir, `${prefix}-${String(offset).padStart(4, "0")}.png`), png);
+            captureMs += performance.now() - captureStarted;
+            pngBytes += png.length;
+            const writeStarted = performance.now();
+            await writeFrame(png);
+            writeMs += performance.now() - writeStarted;
         }
         for (const diagnostic of await session.readDiagnostics()) {
             diagnostics.push(compositionDiagnostic(diagnostic, timeline.id, clip, source.id));
         }
+        healthy = true;
     }
     finally {
-        await session.close();
+        captureTiming.finish({
+            seekMs: Number(seekMs.toFixed(1)),
+            captureMs: Number(captureMs.toFixed(1)),
+            writeMs: Number(writeMs.toFixed(1)),
+            pngBytes,
+        });
+        if (healthy) {
+            await lease.release();
+        }
+        else {
+            await lease.discard();
+        }
     }
-    const outputPath = path.join(segmentDir, `${prefix}.mkv`);
-    await encodePngSequenceToFfv1({
-        pattern: path.join(segmentDir, `${prefix}-%04d.png`),
-        outputPath,
-        fps: timeline.format.fps,
-        signal: options.signal,
+    return diagnostics;
+}
+async function captureCompositionLayer(options) {
+    const prefix = `comp-${options.layerIndex}`;
+    const outputPath = path.join(options.segmentDir, `${prefix}.mkv`);
+    const ffv1Timing = startTiming("timeline.layer.ffv1", {
+        entry: options.source.entry,
+        layer: options.layerIndex,
+        segment: options.segment.index,
     });
-    return { path: outputPath, diagnostics };
+    let encoder;
+    try {
+        encoder = await startFfv1Encoder({
+            outputPath,
+            frames: options.segment.frames,
+            fps: options.timeline.format.fps,
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    catch (error) {
+        ffv1Timing.finish();
+        throw error;
+    }
+    try {
+        const diagnostics = await captureCompositionFrames(options, (png) => encoder.writeFrame(png));
+        await encoder.finish();
+        return { path: outputPath, diagnostics };
+    }
+    catch (error) {
+        await encoder.abort();
+        throw error;
+    }
+    finally {
+        ffv1Timing.finish();
+    }
+}
+function isFullFrameComposition(layer, timeline) {
+    if (layer.clip.source.kind !== "composition" || layer.capture !== "frames") {
+        return false;
+    }
+    if (layer.transform.width !== undefined || layer.transform.height !== undefined) {
+        return false;
+    }
+    if (layer.sourceWidth !== timeline.format.width || layer.sourceHeight !== timeline.format.height) {
+        return false;
+    }
+    const { x, y, scale, rotation, opacity } = layer.transform;
+    if (x !== 0 || y !== 0 || scale !== 1 || rotation !== 0 || opacity !== 1) {
+        return false;
+    }
+    return layer.blend === "normal" && layer.transition === undefined && layer.keyframes === undefined;
+}
+function canEncodeDirectly(options) {
+    if (options.background === "transparent" || options.segment.layers.length !== 1) {
+        return false;
+    }
+    const layer = options.segment.layers[0];
+    return layer !== undefined && isFullFrameComposition(layer, options.timeline);
+}
+function isStaticCompositionOverlay(layer) {
+    if (layer.clip.source.kind !== "composition" || layer.capture !== "frames") {
+        return false;
+    }
+    const { scale, rotation, opacity } = layer.transform;
+    if (scale !== 1 || rotation !== 0 || opacity !== 1) {
+        return false;
+    }
+    return layer.blend === "normal" && layer.transition === undefined && layer.keyframes === undefined;
+}
+function canEncodeVideoDirectly(options) {
+    if (process.env.FRAMEYARD_DISABLE_VIDEO_DIRECT === "1") {
+        return false;
+    }
+    if (options.background === "transparent" || options.segment.layers.length !== 1) {
+        return false;
+    }
+    const layer = options.segment.layers[0];
+    if (!layer || layer.clip.source.kind !== "video" || layer.capture !== "video") {
+        return false;
+    }
+    if (layer.sourceWidth !== options.timeline.format.width || layer.sourceHeight !== options.timeline.format.height) {
+        return false;
+    }
+    const { x, y, scale, rotation, opacity, width, height } = layer.transform;
+    if (width !== undefined ||
+        height !== undefined ||
+        x !== 0 ||
+        y !== 0 ||
+        scale !== 1 ||
+        rotation !== 0 ||
+        opacity !== 1) {
+        return false;
+    }
+    return layer.blend === "normal" && layer.transition === undefined && layer.keyframes === undefined;
+}
+function canEncodeDualPipe(options) {
+    // FFmpeg reads the second image pipe through fd 3; keep the conservative
+    // fallback on hosts where extra stdio pipes are not portable.
+    if (process.platform === "win32" ||
+        process.env.FRAMEYARD_DISABLE_DUAL_PIPE === "1" ||
+        options.background === "transparent" ||
+        options.segment.layers.length !== 2) {
+        return false;
+    }
+    const base = options.segment.layers[0];
+    const overlay = options.segment.layers[1];
+    return (base !== undefined &&
+        overlay !== undefined &&
+        isFullFrameComposition(base, options.timeline) &&
+        isStaticCompositionOverlay(overlay));
+}
+async function captureDirectCompositionLayer(options) {
+    const timing = startTiming("timeline.layer.composition", {
+        entry: options.source.entry,
+        layer: options.layerIndex,
+        segment: options.segment.index,
+    });
+    let encoder;
+    try {
+        encoder = await startDirectSegmentEncoder({
+            outputPath: options.outputPath,
+            width: options.timeline.format.width,
+            height: options.timeline.format.height,
+            fps: options.timeline.format.fps,
+            frames: options.segment.frames,
+            background: options.background,
+            codec: options.codec,
+            container: options.container,
+            ...(options.encoderName !== undefined ? { encoder: options.encoderName } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    catch (error) {
+        timing.finish();
+        throw error;
+    }
+    try {
+        const diagnostics = await captureCompositionFrames(options, (png) => encoder.writeFrame(png));
+        await encoder.finish();
+        return { path: options.outputPath, diagnostics };
+    }
+    catch (error) {
+        await encoder.abort();
+        throw error;
+    }
+    finally {
+        timing.finish();
+    }
+}
+async function captureTwoLayerDirectComposition(options) {
+    const overlayLayer = options.segment.layers[1];
+    if (!overlayLayer) {
+        throw new FrameyardError("INTERNAL", "Dual-pipe capture requires an overlay layer.");
+    }
+    const overlay = sceneLayerToCompositeLayer(overlayLayer, { path: "pipe:3", input: "sequence" });
+    const encoder = await startDualPipeSegmentEncoder({
+        outputPath: options.outputPath,
+        width: options.timeline.format.width,
+        height: options.timeline.format.height,
+        fps: options.timeline.format.fps,
+        frames: options.segment.frames,
+        background: options.background,
+        codec: options.codec,
+        container: options.container,
+        overlay,
+        ...(options.encoderName !== undefined ? { encoder: options.encoderName } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    const tasks = options.segment.layers.map(async (layer, layerIndex) => {
+        if (layer.clip.source.kind !== "composition") {
+            throw new FrameyardError("INTERNAL", "Dual-pipe capture requires composition layers.");
+        }
+        const source = layer.clip.source;
+        return withCaptureSlot(options.captureLimiter, options.signal, async () => {
+            const timing = startTiming("timeline.layer.composition", {
+                entry: source.entry,
+                layer: layerIndex,
+                segment: options.segment.index,
+            });
+            try {
+                return await captureCompositionFrames({
+                    project: options.project,
+                    timeline: options.timeline,
+                    clip: layer.clip,
+                    source,
+                    segment: options.segment,
+                    layerIndex,
+                    serverUrl: options.serverUrl,
+                    infoCache: options.infoCache,
+                    ...(options.sessionPool !== undefined ? { sessionPool: options.sessionPool } : {}),
+                    ...(options.signal ? { signal: options.signal } : {}),
+                }, (png) => encoder.writeFrame(layerIndex, png));
+            }
+            finally {
+                timing.finish();
+            }
+        });
+    });
+    const settled = await Promise.allSettled(tasks);
+    const diagnostics = [];
+    for (const result of settled) {
+        if (result.status === "rejected") {
+            await encoder.abort();
+            throw result.reason;
+        }
+        diagnostics.push(...result.value);
+    }
+    try {
+        await encoder.finish();
+    }
+    catch (error) {
+        await encoder.abort();
+        throw error;
+    }
+    return { path: options.outputPath, diagnostics };
 }
 async function renderNestedTimelineRange(options) {
     if (options.depth > 32) {
@@ -395,6 +695,8 @@ async function renderNestedTimelineRange(options) {
             scratchRoot: options.scratchRoot,
             infoCache: options.infoCache,
             staticCache: options.staticCache,
+            ...(options.captureLimiter !== undefined ? { captureLimiter: options.captureLimiter } : {}),
+            ...(options.sessionPool !== undefined ? { sessionPool: options.sessionPool } : {}),
             codec: "ffv1",
             background: options.timeline.background ?? "transparent",
             prefix,
@@ -424,36 +726,118 @@ async function processTimelineSegment(options) {
     const prefix = options.prefix ?? "timeline";
     const depth = options.depth ?? 0;
     const segmentDir = path.join(scratchRoot, `${prefix}-seg-${String(segment.index).padStart(4, "0")}`);
+    const segmentTiming = startTiming("timeline.segment", {
+        segment: segment.index,
+        start: segment.start,
+        frames: segment.frames,
+        layers: segment.layers.length,
+    });
+    const extension = codec === "ffv1" ? "mkv" : CONTAINER_EXTENSION[options.container ?? "mp4"];
+    const segmentPath = path.join(scratchRoot, `${prefix}-segment-${String(segment.index).padStart(4, "0")}.${extension}`);
+    if (codec !== "ffv1" && canEncodeDirectly({ segment, timeline, background })) {
+        const layer = segment.layers[0];
+        if (!layer) {
+            throw new FrameyardError("INTERNAL", "Direct segment capture requires one composition layer.");
+        }
+        const clip = layer.clip;
+        if (clip.source.kind !== "composition") {
+            throw new FrameyardError("INTERNAL", "Direct segment capture requires one composition layer.");
+        }
+        const source = clip.source;
+        const directTiming = startTiming("timeline.segment.direct", {
+            segment: segment.index,
+            frames: segment.frames,
+            codec,
+            container: options.container ?? "mp4",
+        });
+        const captured = await withCaptureSlot(options.captureLimiter, options.signal, () => captureDirectCompositionLayer({
+            project,
+            timeline,
+            clip,
+            source,
+            segment,
+            layerIndex: 0,
+            serverUrl,
+            infoCache,
+            outputPath: segmentPath,
+            background,
+            codec,
+            container: options.container ?? "mp4",
+            ...(options.sessionPool !== undefined ? { sessionPool: options.sessionPool } : {}),
+            ...(options.encoder !== undefined ? { encoderName: options.encoder } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        }));
+        directTiming.finish();
+        segmentTiming.finish();
+        return { path: segmentPath, diagnostics: captured.diagnostics };
+    }
+    if (codec !== "ffv1" && canEncodeDualPipe({ segment, timeline, background })) {
+        const directTiming = startTiming("timeline.segment.direct", {
+            segment: segment.index,
+            frames: segment.frames,
+            codec,
+            container: options.container ?? "mp4",
+            layers: 2,
+        });
+        const captured = await captureTwoLayerDirectComposition({
+            project,
+            timeline,
+            segment,
+            serverUrl,
+            infoCache,
+            outputPath: segmentPath,
+            background,
+            codec,
+            container: options.container ?? "mp4",
+            ...(options.captureLimiter !== undefined ? { captureLimiter: options.captureLimiter } : {}),
+            ...(options.sessionPool !== undefined ? { sessionPool: options.sessionPool } : {}),
+            ...(options.encoder !== undefined ? { encoderName: options.encoder } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        directTiming.finish();
+        segmentTiming.finish();
+        return { path: segmentPath, diagnostics: captured.diagnostics };
+    }
+    if (codec !== "ffv1" && canEncodeVideoDirectly({ segment, timeline, background })) {
+        const layer = segment.layers[0];
+        if (!layer || layer.clip.source.kind !== "video") {
+            throw new FrameyardError("INTERNAL", "Direct video capture requires one video layer.");
+        }
+        const source = layer.clip.source;
+        const directTiming = startTiming("timeline.segment.direct", {
+            segment: segment.index,
+            frames: segment.frames,
+            codec,
+            container: options.container ?? "mp4",
+            layers: 1,
+            kind: "video",
+        });
+        await encodeVideoSegmentDirect({
+            inputPath: source.absolutePath,
+            outputPath: segmentPath,
+            sourceStartFrame: layer.sourceStart,
+            frames: segment.frames,
+            fps: timeline.format.fps,
+            codec,
+            container: options.container ?? "mp4",
+            ...(options.encoder !== undefined ? { encoder: options.encoder } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        directTiming.finish();
+        segmentTiming.finish();
+        return { path: segmentPath, diagnostics: [] };
+    }
     await mkdir(segmentDir, { recursive: true });
     const diagnostics = [];
     const layers = [];
-    for (const [layerIndex, layer] of segment.layers.entries()) {
+    const layerTasks = segment.layers.map(async (layer, layerIndex) => {
         throwIfAborted(options.signal);
         const clip = layer.clip;
         const source = clip.source;
-        const transform = clip.transform ?? {
-            fit: "contain",
-            x: 0,
-            y: 0,
-            scale: 1,
-            rotation: 0,
-            opacity: 1,
-        };
-        const base = {
-            fit: transform.fit,
-            x: transform.x,
-            y: transform.y,
-            ...(transform.width !== undefined && transform.height !== undefined
-                ? { width: transform.width, height: transform.height }
-                : {}),
-            scale: transform.scale,
-            rotation: transform.rotation,
-            opacity: transform.opacity,
-            blend: clip.blend ?? "normal",
-        };
         if (source.kind === "composition") {
-            if (source.metadata.static === true) {
-                const captured = await captureStaticCompositionLayer({
+            if (layer.capture === "still") {
+                const timing = startTiming("timeline.layer.static", { layer: layerIndex, segment: segment.index });
+                const captured = await withCaptureSlot(options.captureLimiter, options.signal, () => captureStaticCompositionLayer({
                     project,
                     timeline,
                     clip,
@@ -463,18 +847,20 @@ async function processTimelineSegment(options) {
                     infoCache,
                     staticCache: options.staticCache,
                     ...(options.signal ? { signal: options.signal } : {}),
-                });
-                diagnostics.push(...captured.diagnostics);
-                layers.push({
-                    kind: "image",
-                    path: captured.path,
-                    sourceWidth: source.metadata.width,
-                    sourceHeight: source.metadata.height,
-                    ...base,
-                });
-                continue;
+                }));
+                timing.finish();
+                return {
+                    layerIndex,
+                    compositeLayer: sceneLayerToCompositeLayer(layer, { path: captured.path, input: "image" }),
+                    diagnostics: captured.diagnostics,
+                };
             }
-            const captured = await captureCompositionLayer({
+            const timing = startTiming("timeline.layer.composition", {
+                entry: source.entry,
+                layer: layerIndex,
+                segment: segment.index,
+            });
+            const captured = await withCaptureSlot(options.captureLimiter, options.signal, () => captureCompositionLayer({
                 project,
                 timeline,
                 clip,
@@ -484,31 +870,29 @@ async function processTimelineSegment(options) {
                 serverUrl,
                 segmentDir,
                 infoCache,
+                ...(options.sessionPool !== undefined ? { sessionPool: options.sessionPool } : {}),
                 ...(options.signal ? { signal: options.signal } : {}),
-            });
-            diagnostics.push(...captured.diagnostics);
-            layers.push({
-                kind: "composition",
-                path: captured.path,
-                sourceWidth: source.metadata.width,
-                sourceHeight: source.metadata.height,
-                ...base,
-            });
-            continue;
+            }));
+            timing.finish();
+            return {
+                layerIndex,
+                compositeLayer: sceneLayerToCompositeLayer(layer, { path: captured.path, input: "sequence" }),
+                diagnostics: captured.diagnostics,
+            };
         }
         if (source.kind === "video" || source.kind === "image") {
-            const size = visualSourceSize(clip, timeline);
-            layers.push({
-                kind: source.kind,
-                path: source.absolutePath,
-                sourceWidth: size.width,
-                sourceHeight: size.height,
-                ...base,
-                ...(source.kind === "video" ? { sourceStartFrame: layer.sourceStart } : {}),
-            });
-            continue;
+            return {
+                layerIndex,
+                compositeLayer: sceneLayerToCompositeLayer(layer, {
+                    path: source.absolutePath,
+                    input: source.kind,
+                    ...(source.kind === "video" ? { sourceStartFrame: layer.sourceStart } : {}),
+                }),
+                diagnostics: [],
+            };
         }
         if (source.kind === "timeline") {
+            const timing = startTiming("timeline.layer.nested", { layer: layerIndex, segment: segment.index });
             const nested = await renderNestedTimelineRange({
                 project,
                 timeline: source.timeline,
@@ -518,23 +902,39 @@ async function processTimelineSegment(options) {
                 scratchRoot,
                 infoCache,
                 staticCache: options.staticCache,
+                ...(options.captureLimiter !== undefined ? { captureLimiter: options.captureLimiter } : {}),
+                ...(options.sessionPool !== undefined ? { sessionPool: options.sessionPool } : {}),
                 depth: depth + 1,
                 ...(options.signal ? { signal: options.signal } : {}),
             });
-            diagnostics.push(...nested.diagnostics);
-            layers.push({
-                kind: "timeline",
-                path: nested.path,
-                sourceWidth: source.timeline.format.width,
-                sourceHeight: source.timeline.format.height,
-                ...base,
-            });
-            continue;
+            timing.finish();
+            return {
+                layerIndex,
+                compositeLayer: sceneLayerToCompositeLayer(layer, { path: nested.path, input: "sequence" }),
+                diagnostics: nested.diagnostics,
+            };
         }
         throw new FrameyardError("TIMELINE_INVALID", `Unsupported visual source for clip "${clip.id}".`);
+    });
+    const settled = await Promise.allSettled(layerTasks);
+    const capturedLayers = [];
+    for (const result of settled) {
+        if (result.status === "rejected") {
+            throw result.reason;
+        }
+        capturedLayers.push(result.value);
     }
-    const extension = codec === "ffv1" ? "mkv" : CONTAINER_EXTENSION[options.container ?? "mp4"];
-    const segmentPath = path.join(scratchRoot, `${prefix}-segment-${String(segment.index).padStart(4, "0")}.${extension}`);
+    capturedLayers.sort((left, right) => left.layerIndex - right.layerIndex);
+    for (const captured of capturedLayers) {
+        diagnostics.push(...captured.diagnostics);
+        layers.push(captured.compositeLayer);
+    }
+    const compositeTiming = startTiming("timeline.segment.composite", {
+        segment: segment.index,
+        frames: segment.frames,
+        layers: layers.length,
+        codec,
+    });
     await compositeTimelineSegment({
         outputPath: segmentPath,
         width: timeline.format.width,
@@ -544,13 +944,63 @@ async function processTimelineSegment(options) {
         background,
         layers,
         codec,
+        frameOffset: segment.start,
         ...(options.container !== undefined ? { container: options.container } : {}),
         ...(options.encoder !== undefined ? { encoder: options.encoder } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
     });
+    compositeTiming.finish();
+    const cleanupTiming = startTiming("timeline.segment.cleanup", { segment: segment.index });
     await rm(segmentDir, { recursive: true, force: true });
+    cleanupTiming.finish();
+    segmentTiming.finish();
     return { path: segmentPath, diagnostics };
 }
+function checkKeyframeEvaluation(timeline, segments) {
+    for (const segment of segments) {
+        for (const layer of segment.layers) {
+            const keyframes = layer.keyframes;
+            if (!keyframes) {
+                continue;
+            }
+            for (let frame = segment.start; frame < segment.end; frame += 1) {
+                const values = evaluatePresentation(layer.transform, keyframes, frame - layer.clip.start);
+                for (const channel of KEYFRAME_CHANNELS) {
+                    if (!Number.isFinite(values[channel])) {
+                        throw new FrameyardError("TIMELINE_CLIP_INVALID", `Clip "${layer.clip.id}" keyframes.${channel} produced a non-finite value at timeline frame ${frame}.`, {
+                            details: {
+                                timeline: timeline.id,
+                                clip: layer.clip.id,
+                                track: layer.clip.track,
+                                channel,
+                                frame: frame - layer.clip.start,
+                                timelineFrame: frame,
+                            },
+                        });
+                    }
+                }
+            }
+        }
+    }
+}
+function checkTransitionEvaluation(timeline) {
+    for (const transition of timeline.transitions) {
+        for (let frame = transition.start; frame < transition.end; frame += 1) {
+            const progress = transitionProgress(transition, frame);
+            if (!Number.isFinite(progress)) {
+                throw new FrameyardError("TIMELINE_TRANSITION_INVALID", `Transition "${transition.from}" → "${transition.to}" produced a non-finite progress at timeline frame ${frame}.`, {
+                    details: {
+                        timeline: timeline.id,
+                        track: transition.track,
+                        from: transition.from,
+                        to: transition.to,
+                        timelineFrame: frame,
+                    },
+                });
+            }
+        }
+    }
+}
 async function checkResolvedTimelineRange(options) {
     if (options.context.depth > 32) {
         throw new FrameyardError("TIMELINE_INVALID", "Nested timeline depth exceeds 32.");
@@ -558,6 +1008,8 @@ async function checkResolvedTimelineRange(options) {
     const { timeline, startFrame, endFrame, context } = options;
     const plan = planTimelineRender(timeline, { startFrame, endFrame });
     const diagnostics = [];
+    checkKeyframeEvaluation(timeline, plan.segments);
+    checkTransitionEvaluation(timeline);
     const targets = new Map();
     for (const segment of plan.segments) {
         for (const layer of segment.layers) {
@@ -664,7 +1116,7 @@ export async function checkTimeline(options) {
     const startedAt = performance.now();
     const projectTimeline = options.project.timelines.get(options.timelineId);
     if (!projectTimeline) {
-        throw new FrameyardError("TIMELINE_NOT_FOUND", `Timeline "${options.timelineId}" is not listed in video.config.js.`);
+        throw new FrameyardError("TIMELINE_NOT_FOUND", `Timeline "${options.timelineId}" is not listed in fy.config.js.`);
     }
     const resolved = await resolveProjectTimeline({
         project: options.project,
@@ -740,6 +1192,7 @@ export async function checkTimeline(options) {
         framesChecked: timeline.durationInFrames,
         tracks: timeline.tracks.length,
         clips: timeline.clips.length,
+        transitions: timeline.transitions.length,
         audio: { clips: audioInspection.clips.length, details: audioInspection.clips },
         transcripts: {
             clips: transcripts.clips.length,
@@ -754,36 +1207,12 @@ async function renderResolvedTimelineFrame(options) {
         throw new FrameyardError("TIMELINE_INVALID", "Nested timeline depth exceeds 32.");
     }
     const { timeline, frame, context } = options;
-    const plan = planTimelineRender(timeline, { startFrame: frame, endFrame: frame + 1 });
-    const segment = plan.segments[0];
-    if (!segment) {
-        throw new FrameyardError("FRAME_OUT_OF_RANGE", `Frame ${frame} does not belong to a timeline segment.`);
-    }
+    const scene = projectScene(timeline, frame, frame + 1);
     const diagnostics = [];
     const layers = [];
-    for (const [layerIndex, layer] of segment.layers.entries()) {
+    for (const [layerIndex, layer] of scene.layers.entries()) {
         const clip = layer.clip;
         const source = clip.source;
-        const transform = clip.transform ?? {
-            fit: "contain",
-            x: 0,
-            y: 0,
-            scale: 1,
-            rotation: 0,
-            opacity: 1,
-        };
-        const base = {
-            fit: transform.fit,
-            x: transform.x,
-            y: transform.y,
-            ...(transform.width !== undefined && transform.height !== undefined
-                ? { width: transform.width, height: transform.height }
-                : {}),
-            scale: transform.scale,
-            rotation: transform.rotation,
-            opacity: transform.opacity,
-            blend: clip.blend ?? "normal",
-        };
         if (source.kind === "composition") {
             const validation = await validateHtmlComposition({
                 projectRoot: context.project.root,
@@ -814,25 +1243,15 @@ async function renderResolvedTimelineFrame(options) {
             finally {
                 await session.close();
             }
-            layers.push({
-                kind: "image",
-                path: framePath,
-                sourceWidth: source.metadata.width,
-                sourceHeight: source.metadata.height,
-                ...base,
-            });
+            layers.push(sceneLayerToCompositeLayer(layer, { path: framePath, input: "image" }));
             continue;
         }
         if (source.kind === "video" || source.kind === "image") {
-            const size = visualSourceSize(clip, timeline);
-            layers.push({
-                kind: source.kind,
+            layers.push(sceneLayerToCompositeLayer(layer, {
                 path: source.absolutePath,
-                sourceWidth: size.width,
-                sourceHeight: size.height,
-                ...base,
+                input: source.kind,
                 ...(source.kind === "video" ? { sourceStartFrame: layer.sourceStart } : {}),
-            });
+            }));
             continue;
         }
         if (source.kind === "timeline") {
@@ -845,13 +1264,7 @@ async function renderResolvedTimelineFrame(options) {
                 context: { ...context, depth: context.depth + 1 },
             });
             diagnostics.push(...nestedDiagnostics);
-            layers.push({
-                kind: "image",
-                path: nestedPath,
-                sourceWidth: source.timeline.format.width,
-                sourceHeight: source.timeline.format.height,
-                ...base,
-            });
+            layers.push(sceneLayerToCompositeLayer(layer, { path: nestedPath, input: "image" }));
             continue;
         }
         throw new FrameyardError("TIMELINE_INVALID", `Unsupported visual source for clip "${clip.id}".`);
@@ -863,6 +1276,7 @@ async function renderResolvedTimelineFrame(options) {
         fps: timeline.format.fps,
         background: options.background,
         layers,
+        frameOffset: frame,
         ...(context.signal ? { signal: context.signal } : {}),
     });
     return diagnostics;
@@ -895,7 +1309,7 @@ export async function captureTimelineStills(options) {
     const startedAt = performance.now();
     const projectTimeline = options.project.timelines.get(options.timelineId);
     if (!projectTimeline) {
-        throw new FrameyardError("TIMELINE_NOT_FOUND", `Timeline "${options.timelineId}" is not listed in video.config.js.`);
+        throw new FrameyardError("TIMELINE_NOT_FOUND", `Timeline "${options.timelineId}" is not listed in fy.config.js.`);
     }
     const resolved = await resolveProjectTimeline({
         project: options.project,
@@ -1000,20 +1414,25 @@ export async function renderTimeline(options) {
     const requestedWorkers = validateWorkers(options.workers);
     const overwrite = options.overwrite ?? false;
     const startedAt = performance.now();
+    const renderTiming = startTiming("timeline.render", { timeline: options.timelineId });
     await ensureOutputAvailable(options.outPath, overwrite);
     await assertFfmpegCapabilities(options.signal, codec);
     const encoder = await resolveVideoEncoder(codec, options.encoder, options.signal);
     const workers = clampTimelineWorkers(requestedWorkers, encoder);
+    const captureLimiter = createSemaphore(captureConcurrency(workers));
+    const sessionPool = new CompositionSessionPool({ maxIdle: Math.max(2, workers) });
     const projectTimeline = options.project.timelines.get(options.timelineId);
     if (!projectTimeline) {
-        throw new FrameyardError("TIMELINE_NOT_FOUND", `Timeline "${options.timelineId}" is not listed in video.config.js.`);
+        throw new FrameyardError("TIMELINE_NOT_FOUND", `Timeline "${options.timelineId}" is not listed in fy.config.js.`);
     }
+    const resolveTiming = startTiming("timeline.resolve", { timeline: options.timelineId });
     const resolved = await resolveProjectTimeline({
         project: options.project,
         timeline: projectTimeline,
         ...(options.signal ? { signal: options.signal } : {}),
         ...(options.propsOverrides ? { propsOverrides: options.propsOverrides } : {}),
     });
+    resolveTiming.finish({ clips: resolved.timeline?.clips.length ?? 0, diagnostics: resolved.diagnostics.length });
     if (!resolved.timeline) {
         const first = resolved.diagnostics.find((diagnostic) => diagnostic.severity === "error");
         throw new FrameyardError(first?.code ?? "TIMELINE_INVALID", first?.message ?? "Timeline resolution failed.", {
@@ -1025,7 +1444,9 @@ export async function renderTimeline(options) {
     const scratchBase = options.scratchDir ?? tmpdir();
     await mkdir(scratchBase, { recursive: true });
     const scratchRoot = await mkdtemp(path.join(scratchBase, "frameyard-timeline-"));
+    const serverTiming = startTiming("timeline.server", { project: options.project.root });
     const server = await startPreviewServer({ projectRoot: options.project.root, port: 0 });
+    serverTiming.finish({ url: server.url });
     const infoCache = new Map();
     const staticCache = new Map();
     const diagnostics = [...resolved.diagnostics];
@@ -1042,6 +1463,7 @@ export async function renderTimeline(options) {
     });
     let nextSegment = 0;
     const audio = buildAudioClips(timeline);
+    const audioTiming = startTiming("timeline.audio_inspect", { clips: audio.clips.length });
     const audioInspection = audio.clips.length
         ? await inspectTimelineAudio({
             projectRoot: options.project.root,
@@ -1051,11 +1473,13 @@ export async function renderTimeline(options) {
             ...(options.signal ? { signal: options.signal } : {}),
         })
         : { clips: [], assets: [], warnings: [] };
+    audioTiming.finish({ assets: audioInspection.assets.length });
     diagnostics.push(...audioInspection.warnings.map((message) => ({
         severity: "warning",
         code: "AUDIO_WARNING",
         message,
     })));
+    const transcriptTiming = startTiming("timeline.transcript_inspect", { clips: audio.transcripts.length });
     const transcripts = audio.transcripts.length
         ? await inspectTranscriptClips({
             projectRoot: options.project.root,
@@ -1063,6 +1487,7 @@ export async function renderTimeline(options) {
             ...(options.signal ? { signal: options.signal } : {}),
         })
         : { clips: [], assets: [], warnings: [] };
+    transcriptTiming.finish({ assets: transcripts.assets.length });
     diagnostics.push(...transcripts.warnings.map((message) => ({
         severity: "warning",
         code: "TRANSCRIPT_WARNING",
@@ -1088,6 +1513,8 @@ export async function renderTimeline(options) {
                     scratchRoot,
                     infoCache,
                     staticCache,
+                    captureLimiter,
+                    sessionPool,
                     codec,
                     container,
                     encoder,
@@ -1103,7 +1530,14 @@ export async function renderTimeline(options) {
                 });
             }
         };
+        const segmentsTiming = startTiming("timeline.segments", {
+            segments: plan.segments.length,
+            workers,
+            codec,
+            encoder,
+        });
         await Promise.all(Array.from({ length: workers }, () => worker()));
+        segmentsTiming.finish();
         const segmentPaths = segmentResults.map((result) => {
             if (!result) {
                 throw new FrameyardError("INTERNAL", "A timeline segment was not rendered.");
@@ -1111,6 +1545,7 @@ export async function renderTimeline(options) {
             diagnostics.push(...result.diagnostics);
             return result.path;
         });
+        const concatTiming = startTiming("timeline.concat", { segments: segmentPaths.length });
         await concatTimelineSegments({
             segmentPaths,
             listPath: path.join(scratchRoot, "segments.txt"),
@@ -1119,9 +1554,11 @@ export async function renderTimeline(options) {
             container,
             ...(options.signal ? { signal: options.signal } : {}),
         });
+        concatTiming.finish();
         let finalPath = tempVideo;
         if (audioInspection.assets.length > 0) {
             const audioPath = path.join(scratchRoot, "audio.wav");
+            const mixTiming = startTiming("timeline.audio_mix", { assets: audioInspection.assets.length });
             await mixAudioTimeline({
                 clips: audioInspection.assets.map((asset) => ({
                     path: asset.path,
@@ -1129,12 +1566,15 @@ export async function renderTimeline(options) {
                     trimStart: asset.clip.trimStart,
                     ...(asset.clip.trimDuration !== undefined ? { trimDuration: asset.clip.trimDuration } : {}),
                     volume: asset.clip.volume,
+                    ...(asset.clip.envelopes !== undefined ? { volumeEnvelopes: asset.clip.envelopes } : {}),
                 })),
                 fps: timeline.format.fps,
                 durationSeconds: total / timeline.format.fps,
                 outputPath: audioPath,
                 ...(options.signal ? { signal: options.signal } : {}),
             });
+            mixTiming.finish();
+            const muxTiming = startTiming("timeline.mux", { codec, container });
             await muxVideoWithAudio({
                 videoPath: tempVideo,
                 audioPath,
@@ -1143,13 +1583,24 @@ export async function renderTimeline(options) {
                 container,
                 ...(options.signal ? { signal: options.signal } : {}),
             });
+            muxTiming.finish();
             finalPath = tempFinal;
         }
         if (!overwrite && (await pathExists(options.outPath))) {
             throw new FrameyardError("OUTPUT_EXISTS", `Output already exists: ${options.outPath}. Pass --overwrite to replace it.`);
         }
+        const publishTiming = startTiming("timeline.publish", { out: options.outPath });
         await publishFile(finalPath, options.outPath, overwrite);
+        publishTiming.finish();
         const uniqueDiagnostics = mergeDiagnostics(diagnostics);
+        renderTiming.finish({
+            segments: plan.segments.length,
+            workers,
+            codec,
+            encoder,
+            frames: total,
+            outputBytes: (await stat(options.outPath)).size,
+        });
         return {
             timeline: options.timelineId,
             entry: timeline.entry,
@@ -1162,6 +1613,7 @@ export async function renderTimeline(options) {
             framesRendered: total,
             segments: plan.segments.length,
             workers,
+            transitions: timeline.transitions.length,
             codec,
             container,
             encoder,
@@ -1175,6 +1627,7 @@ export async function renderTimeline(options) {
     finally {
         await rm(tempVideo, { force: true });
         await rm(tempFinal, { force: true });
+        await sessionPool.close();
         try {
             await server.close();
         }