frameyard 0.6.0 → 0.8.0

package/dist/renderer/timeline.js

@@ -2,12 +2,13 @@ import { link, mkdir, mkdtemp, rename, rm, stat, writeFile } from "node:fs/promi
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { FrameyardError } from "../errors.js";
+import { isPlainObject, } from "../contracts.js";
+import { FrameyardError, isFrameyardError } from "../errors.js";
 import { validateHtmlComposition } from "../html/validate.js";
 import { startPreviewServer } from "../server/server.js";
 import { inspectTimelineAudio } from "./audio.js";
 import { openCompositionSession } from "./browser.js";
-import { assertFfmpegCapabilities, compositeTimelineFrame, compositeTimelineSegment, concatTimelineSegments, encodePngSequenceToFfv1, mixAudioTimeline, muxVideoWithAudio, } from "./ffmpeg.js";
+import { assertContainerCodec, assertFfmpegCapabilities, compositeTimelineFrame, compositeTimelineSegment, concatTimelineSegments, CONTAINER_EXTENSION, defaultCodecForContainer, ENCODER_SESSION_LIMIT, encodePngSequenceToFfv1, mixAudioTimeline, muxVideoWithAudio, resolveVideoEncoder, } from "./ffmpeg.js";
 import { inspectTranscriptClips } from "./transcripts.js";
 import { planTimelineRender } from "../timeline/plan.js";
 import { resolveProjectTimeline, } from "../timeline/resolve.js";
@@ -22,6 +23,13 @@ function validateWorkers(value) {
     }
     return workers;
 }
+/**
+ * Caps workers at the encoder's concurrent-session limit. Consumer NVIDIA
+ * drivers allow eight NVENC sessions, and each worker opens one encoder.
+ */
+export function clampTimelineWorkers(workers, encoder) {
+    return Math.min(workers, ENCODER_SESSION_LIMIT[encoder]);
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw new FrameyardError("RENDER_FAILED", "Operation cancelled.");
@@ -42,6 +50,25 @@ async function ensureOutputAvailable(outPath, overwrite) {
     }
     await mkdir(path.dirname(outPath), { recursive: true });
 }
+async function assertOutputsAvailable(outPaths, overwrite) {
+    if (overwrite) {
+        return;
+    }
+    const conflicts = [];
+    for (const outPath of outPaths) {
+        if (await pathExists(outPath)) {
+            conflicts.push(outPath);
+        }
+    }
+    if (conflicts.length === 0) {
+        return;
+    }
+    const first = conflicts[0];
+    const message = conflicts.length === 1
+        ? `Output already exists: ${first}. Pass --overwrite to replace it.`
+        : `Output already exists: ${first} (and ${conflicts.length - 1} more). Pass --overwrite to replace them.`;
+    throw new FrameyardError("OUTPUT_EXISTS", message, { details: { conflicts } });
+}
 async function publishFile(tempPath, outPath, overwrite) {
     if (overwrite) {
         await rename(tempPath, outPath);
@@ -79,6 +106,21 @@ function mergeDiagnostics(...groups) {
     }
     return result;
 }
+function withBatchContext(error, frames, failedFrame) {
+    if (!isFrameyardError(error)) {
+        return error;
+    }
+    const details = error.details === undefined
+        ? {}
+        : isPlainObject(error.details)
+            ? { ...error.details }
+            : { originalDetails: error.details };
+    return new FrameyardError(error.code, error.message, {
+        cause: error,
+        details: { ...details, frames: [...frames], failedFrame },
+        diagnostics: error.diagnostics,
+    });
+}
 function compositionDiagnostic(diagnostic, timelineId, clip, compositionId) {
     return {
         ...diagnostic,
@@ -227,6 +269,58 @@ export function resolveTimelineAudio(timeline) {
         transcripts,
     };
 }
+async function captureStaticCompositionLayer(options) {
+    const { project, timeline, clip, source, serverUrl, scratchRoot, infoCache, staticCache } = options;
+    const propsKey = JSON.stringify(clip.props ?? null);
+    const cacheKey = `${source.entry}\u0000${propsKey}`;
+    const cached = staticCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const pending = (async () => {
+        let validation = infoCache.get(cacheKey);
+        if (!validation) {
+            validation = await validateHtmlComposition({
+                projectRoot: project.root,
+                entry: source.entry,
+                ...(clip.props !== undefined ? { props: clip.props } : {}),
+                ...(project.format ? { format: project.format } : {}),
+            });
+            infoCache.set(cacheKey, validation);
+        }
+        if (!validation.info) {
+            throw new FrameyardError("TIMELINE_CLIP_INVALID", `Composition "${source.id}" could not be loaded for clip "${clip.id}".`, { diagnostics: validation.diagnostics });
+        }
+        const session = await openCompositionSession({
+            serverUrl,
+            entry: source.entry,
+            props: clip.props,
+            info: validation.info,
+            staticDiagnostics: validation.diagnostics,
+            transparentBackground: true,
+        });
+        try {
+            throwIfAborted(options.signal);
+            await session.seek(0);
+            const png = await session.capture();
+            const filePath = path.join(scratchRoot, `static-${randomUUID()}.png`);
+            await writeFile(filePath, png);
+            const diagnostics = (await session.readDiagnostics()).map((diagnostic) => compositionDiagnostic(diagnostic, timeline.id, clip, source.id));
+            return { path: filePath, diagnostics };
+        }
+        finally {
+            await session.close();
+        }
+    })();
+    staticCache.set(cacheKey, pending);
+    try {
+        return await pending;
+    }
+    catch (error) {
+        staticCache.delete(cacheKey);
+        throw error;
+    }
+}
 async function captureCompositionLayer(options) {
     const { project, timeline, clip, source, segment, layerIndex, serverUrl, segmentDir, infoCache } = options;
     const propsKey = JSON.stringify(clip.props ?? null);
@@ -237,6 +331,7 @@ async function captureCompositionLayer(options) {
             projectRoot: project.root,
             entry: source.entry,
             ...(clip.props !== undefined ? { props: clip.props } : {}),
+            ...(project.format ? { format: project.format } : {}),
         });
         infoCache.set(cacheKey, validation);
     }
@@ -299,6 +394,7 @@ async function renderNestedTimelineRange(options) {
             serverUrl: options.serverUrl,
             scratchRoot: options.scratchRoot,
             infoCache: options.infoCache,
+            staticCache: options.staticCache,
             codec: "ffv1",
             background: options.timeline.background ?? "transparent",
             prefix,
@@ -315,6 +411,8 @@ async function renderNestedTimelineRange(options) {
         segmentPaths: results.map((result) => result.path),
         listPath: path.join(options.scratchRoot, `${prefix}-segments.txt`),
         outputPath,
+        // Nested timeline segments are always lossless FFV1 in Matroska.
+        container: "mkv",
         ...(options.signal ? { signal: options.signal } : {}),
     });
     return { path: outputPath, diagnostics };
@@ -351,8 +449,31 @@ async function processTimelineSegment(options) {
             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({
+                    project,
+                    timeline,
+                    clip,
+                    source,
+                    serverUrl,
+                    scratchRoot,
+                    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;
+            }
             const captured = await captureCompositionLayer({
                 project,
                 timeline,
@@ -396,6 +517,7 @@ async function processTimelineSegment(options) {
                 serverUrl,
                 scratchRoot,
                 infoCache,
+                staticCache: options.staticCache,
                 depth: depth + 1,
                 ...(options.signal ? { signal: options.signal } : {}),
             });
@@ -411,7 +533,7 @@ async function processTimelineSegment(options) {
         }
         throw new FrameyardError("TIMELINE_INVALID", `Unsupported visual source for clip "${clip.id}".`);
     }
-    const extension = codec === "ffv1" ? "mkv" : "mp4";
+    const extension = codec === "ffv1" ? "mkv" : CONTAINER_EXTENSION[options.container ?? "mp4"];
     const segmentPath = path.join(scratchRoot, `${prefix}-segment-${String(segment.index).padStart(4, "0")}.${extension}`);
     await compositeTimelineSegment({
         outputPath: segmentPath,
@@ -422,6 +544,8 @@ async function processTimelineSegment(options) {
         background,
         layers,
         codec,
+        ...(options.container !== undefined ? { container: options.container } : {}),
+        ...(options.encoder !== undefined ? { encoder: options.encoder } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
     });
     await rm(segmentDir, { recursive: true, force: true });
@@ -447,6 +571,7 @@ async function checkResolvedTimelineRange(options) {
                     projectRoot: context.project.root,
                     entry: source.entry,
                     ...(layer.clip.props !== undefined ? { props: layer.clip.props } : {}),
+                    ...(context.project.format ? { format: context.project.format } : {}),
                 });
                 if (!validation.info) {
                     throw new FrameyardError("TIMELINE_CLIP_INVALID", `Composition "${source.id}" could not be loaded for clip "${layer.clip.id}".`, { diagnostics: validation.diagnostics });
@@ -466,6 +591,9 @@ async function checkResolvedTimelineRange(options) {
                 staticDiagnostics: target.validation.diagnostics,
             });
             sessions.set(key, session);
+            if (target.source.metadata.static === true) {
+                await session.seek(0);
+            }
         }
         for (const segment of plan.segments) {
             for (let frame = segment.start; frame < segment.end; frame += 1) {
@@ -475,6 +603,9 @@ async function checkResolvedTimelineRange(options) {
                         continue;
                     }
                     const source = layer.clip.source;
+                    if (source.metadata.static === true) {
+                        continue;
+                    }
                     const key = `${source.entry}\u0000${JSON.stringify(layer.clip.props ?? null)}`;
                     const session = sessions.get(key);
                     if (!session) {
@@ -651,12 +782,14 @@ async function renderResolvedTimelineFrame(options) {
             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,
                 entry: source.entry,
                 ...(clip.props !== undefined ? { props: clip.props } : {}),
+                ...(context.project.format ? { format: context.project.format } : {}),
             });
             if (!validation.info) {
                 throw new FrameyardError("TIMELINE_CLIP_INVALID", `Composition "${source.id}" could not be loaded for clip "${clip.id}".`, { diagnostics: validation.diagnostics });
@@ -734,16 +867,31 @@ async function renderResolvedTimelineFrame(options) {
     });
     return diagnostics;
 }
-/** Captures one timeline frame as PNG through the clip capture and composite path. */
-export async function captureTimelineStill(options) {
-    if (!Number.isInteger(options.frame) || options.frame < 0) {
-        throw new FrameyardError("FRAME_OUT_OF_RANGE", `--frame must be a non-negative integer; received ${options.frame}.`);
+/** Captures timeline frames as PNGs through the clip capture and composite path. */
+export async function captureTimelineStills(options) {
+    if (options.frames.length === 0) {
+        throw new FrameyardError("USAGE", "Still capture requires at least one frame.");
+    }
+    if (options.frames.length !== options.outPaths.length) {
+        throw new FrameyardError("USAGE", "Still frames and output paths must have the same length.");
+    }
+    for (const frame of options.frames) {
+        if (!Number.isInteger(frame) || frame < 0) {
+            throw new FrameyardError("FRAME_OUT_OF_RANGE", `--frame must be a non-negative integer; received ${frame}.`);
+        }
+    }
+    if (new Set(options.frames).size !== options.frames.length) {
+        throw new FrameyardError("USAGE", "Still frames must be unique.");
     }
-    if (path.extname(options.outPath).toLowerCase() !== ".png") {
-        throw new FrameyardError("USAGE", `Still output must use a .png extension: ${options.outPath}`);
+    if (new Set(options.outPaths).size !== options.outPaths.length) {
+        throw new FrameyardError("USAGE", "Still output paths must be unique.");
+    }
+    for (const outPath of options.outPaths) {
+        if (path.extname(outPath).toLowerCase() !== ".png") {
+            throw new FrameyardError("USAGE", `Still output must use a .png extension: ${outPath}`);
+        }
     }
     const overwrite = options.overwrite ?? false;
-    await ensureOutputAvailable(options.outPath, overwrite);
     const startedAt = performance.now();
     const projectTimeline = options.project.timelines.get(options.timelineId);
     if (!projectTimeline) {
@@ -762,37 +910,58 @@ export async function captureTimelineStill(options) {
         });
     }
     const timeline = resolved.timeline;
-    if (options.frame >= timeline.durationInFrames) {
-        throw new FrameyardError("FRAME_OUT_OF_RANGE", `Frame ${options.frame} is outside the valid range 0..${timeline.durationInFrames - 1}.`);
+    const invalidFrames = options.frames.filter((frame) => frame >= timeline.durationInFrames);
+    if (invalidFrames.length > 0) {
+        const first = invalidFrames[0];
+        throw new FrameyardError("FRAME_OUT_OF_RANGE", `Frame ${first} is outside the valid range 0..${timeline.durationInFrames - 1}.`, { details: { invalidFrames, validRange: { min: 0, max: timeline.durationInFrames - 1 } } });
+    }
+    await assertOutputsAvailable(options.outPaths, overwrite);
+    for (const outPath of options.outPaths) {
+        await mkdir(path.dirname(outPath), { recursive: true });
     }
     const scratchBase = options.scratchDir ?? tmpdir();
     await mkdir(scratchBase, { recursive: true });
     const scratchRoot = await mkdtemp(path.join(scratchBase, "frameyard-timeline-still-"));
-    const server = await startPreviewServer({ projectRoot: options.project.root, port: 0 });
-    const tempPath = path.join(path.dirname(options.outPath), `.${path.basename(options.outPath)}.frameyard-${process.pid}-${randomUUID()}.png`);
+    const tempPaths = options.outPaths.map((outPath) => path.join(path.dirname(outPath), `.${path.basename(outPath)}.frameyard-${process.pid}-${randomUUID()}.png`));
+    let server;
     try {
-        const diagnostics = await renderResolvedTimelineFrame({
-            timeline,
-            frame: options.frame,
-            outputPath: tempPath,
-            background: timeline.background ?? "black",
-            context: {
-                project: options.project,
-                serverUrl: server.url,
-                scratchRoot,
-                depth: 0,
-                ...(options.signal ? { signal: options.signal } : {}),
-            },
-        });
-        if (!overwrite && (await pathExists(options.outPath))) {
-            throw new FrameyardError("OUTPUT_EXISTS", `Output already exists: ${options.outPath}. Pass --overwrite to replace it.`);
+        server = await startPreviewServer({ projectRoot: options.project.root, port: 0 });
+        const diagnostics = [];
+        for (const [index, frame] of options.frames.entries()) {
+            throwIfAborted(options.signal);
+            try {
+                diagnostics.push(...(await renderResolvedTimelineFrame({
+                    timeline,
+                    frame,
+                    outputPath: tempPaths[index],
+                    background: timeline.background ?? "black",
+                    context: {
+                        project: options.project,
+                        serverUrl: server.url,
+                        scratchRoot,
+                        depth: 0,
+                        ...(options.signal ? { signal: options.signal } : {}),
+                    },
+                })));
+            }
+            catch (error) {
+                throw withBatchContext(error, options.frames, frame);
+            }
         }
-        await publishFile(tempPath, options.outPath, overwrite);
+        await assertOutputsAvailable(options.outPaths, overwrite);
+        for (const [index, outPath] of options.outPaths.entries()) {
+            await publishFile(tempPaths[index], outPath, overwrite);
+        }
+        const frames = options.frames.map((frame, index) => ({
+            frame,
+            path: options.outPaths[index],
+        }));
+        const first = frames[0];
         return {
             timeline: options.timelineId,
             entry: timeline.entry,
-            frame: options.frame,
-            path: options.outPath,
+            ...(frames.length === 1 && first !== undefined ? { frame: first.frame, path: first.path } : {}),
+            frames,
             width: timeline.format.width,
             height: timeline.format.height,
             diagnostics: mergeDiagnostics(resolved.diagnostics, diagnostics),
@@ -800,9 +969,9 @@ export async function captureTimelineStill(options) {
         };
     }
     finally {
-        await rm(tempPath, { force: true });
+        await Promise.all(tempPaths.map((tempPath) => rm(tempPath, { force: true })));
         try {
-            await server.close();
+            await server?.close();
         }
         catch {
             // Preserve the still's original error.
@@ -810,16 +979,31 @@ export async function captureTimelineStill(options) {
         await rm(scratchRoot, { recursive: true, force: true });
     }
 }
+/** Captures one timeline frame as a PNG through the clip capture and composite path. */
+export async function captureTimelineStill(options) {
+    const { frame, outPath, ...rest } = options;
+    return captureTimelineStills({
+        ...rest,
+        frames: [frame],
+        outPaths: [outPath],
+    });
+}
 /** Renders one timeline to MP4 through the segmented lossless clip pipeline. */
 export async function renderTimeline(options) {
-    if (path.extname(options.outPath).toLowerCase() !== ".mp4") {
-        throw new FrameyardError("USAGE", `Timeline output must use an .mp4 extension: ${options.outPath}`);
+    const container = options.container ?? "mp4";
+    const codec = options.codec ?? defaultCodecForContainer(container);
+    assertContainerCodec(container, codec);
+    const extension = `.${CONTAINER_EXTENSION[container]}`;
+    if (path.extname(options.outPath).toLowerCase() !== extension) {
+        throw new FrameyardError("USAGE", `Timeline output for --container ${container} must use a ${extension} extension: ${options.outPath}`);
     }
-    const workers = validateWorkers(options.workers);
+    const requestedWorkers = validateWorkers(options.workers);
     const overwrite = options.overwrite ?? false;
-    await ensureOutputAvailable(options.outPath, overwrite);
-    await assertFfmpegCapabilities(options.signal);
     const startedAt = performance.now();
+    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 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.`);
@@ -843,7 +1027,15 @@ export async function renderTimeline(options) {
     const scratchRoot = await mkdtemp(path.join(scratchBase, "frameyard-timeline-"));
     const server = await startPreviewServer({ projectRoot: options.project.root, port: 0 });
     const infoCache = new Map();
+    const staticCache = new Map();
     const diagnostics = [...resolved.diagnostics];
+    if (workers < requestedWorkers) {
+        diagnostics.push({
+            severity: "warning",
+            code: "ENCODER_WARNING",
+            message: `Encoder ${encoder} allows ${workers} concurrent encode sessions; using ${workers} workers instead of ${requestedWorkers}.`,
+        });
+    }
     const total = timeline.durationInFrames;
     const segmentResults = Array.from({
         length: plan.segments.length,
@@ -895,6 +1087,10 @@ export async function renderTimeline(options) {
                     serverUrl: server.url,
                     scratchRoot,
                     infoCache,
+                    staticCache,
+                    codec,
+                    container,
+                    encoder,
                     ...(options.signal ? { signal: options.signal } : {}),
                 });
                 segmentResults[index] = result;
@@ -919,6 +1115,8 @@ export async function renderTimeline(options) {
             segmentPaths,
             listPath: path.join(scratchRoot, "segments.txt"),
             outputPath: tempVideo,
+            codec,
+            container,
             ...(options.signal ? { signal: options.signal } : {}),
         });
         let finalPath = tempVideo;
@@ -941,6 +1139,8 @@ export async function renderTimeline(options) {
                 videoPath: tempVideo,
                 audioPath,
                 outputPath: tempFinal,
+                codec,
+                container,
                 ...(options.signal ? { signal: options.signal } : {}),
             });
             finalPath = tempFinal;
@@ -962,6 +1162,9 @@ export async function renderTimeline(options) {
             framesRendered: total,
             segments: plan.segments.length,
             workers,
+            codec,
+            container,
+            encoder,
             bytes: (await stat(options.outPath)).size,
             audio: { clips: audioInspection.clips.length },
             transcripts: { clips: transcripts.clips.length },