frameyard 0.6.0 → 0.8.0

package/dist/renderer/index.d.ts

@@ -1,6 +1,7 @@
-import type { CompositionDiagnostic, CompositionMetadata } from "../contracts.js";
+import { type CompositionDiagnostic, type CompositionMetadata, type StaticCompositionMetadata } from "../contracts.js";
 import type { Project } from "../project.js";
 import { type AudioInspection } from "./audio.js";
+import { type VideoCodec, type VideoContainer, type VideoEncoderChoice, type VideoEncoderName } from "./ffmpeg.js";
 import { type TranscriptInspection } from "./transcripts.js";
 export interface ProgressEvent {
     frame: number;
@@ -14,7 +15,8 @@ interface SessionOptions {
     signal?: AbortSignal;
     onProgress?: (event: ProgressEvent) => void;
 }
-export interface CheckResult {
+export interface AnimatedCheckResult {
+    kind: "animated";
     composition: string;
     entry: string;
     controller: {
@@ -36,7 +38,8 @@ export interface CheckResult {
     diagnostics: CompositionDiagnostic[];
     elapsedMs: number;
 }
-export interface StillResult {
+export interface StaticCheckResult {
+    kind: "static";
     composition: string;
     entry: string;
     controller: {
@@ -45,14 +48,37 @@ export interface StillResult {
         kind: "external";
         src: string;
     } | null;
+    metadata: StaticCompositionMetadata;
+    framesChecked: 1;
+    diagnostics: CompositionDiagnostic[];
+    elapsedMs: number;
+}
+export type CheckResult = AnimatedCheckResult | StaticCheckResult;
+export interface StillFrameResult {
     frame: number;
     path: string;
+}
+export interface StillResult {
+    composition: string;
+    entry: string;
+    controller: {
+        kind: "inline";
+    } | {
+        kind: "external";
+        src: string;
+    } | null;
+    /** Present only when exactly one frame was captured. */
+    frame?: number;
+    /** Present only when exactly one frame was captured. */
+    path?: string;
+    frames: StillFrameResult[];
     width: number;
     height: number;
     diagnostics: CompositionDiagnostic[];
     elapsedMs: number;
 }
-export interface RenderResult {
+export interface VideoRenderResult {
+    kind: "video";
     composition: string;
     entry: string;
     controller: {
@@ -69,6 +95,12 @@ export interface RenderResult {
     durationSeconds: number;
     framesRendered: number;
     concurrency: number;
+    /** Resolved delivery codec. */
+    codec: VideoCodec;
+    /** Resolved delivery container. */
+    container: VideoContainer;
+    /** Resolved encoder used for the output. */
+    encoder: VideoEncoderName;
     bytes: number;
     audio: {
         clips: number;
@@ -79,19 +111,48 @@ export interface RenderResult {
     diagnostics: CompositionDiagnostic[];
     elapsedMs: number;
 }
+export interface ImageRenderResult {
+    kind: "image";
+    composition: string;
+    entry: string;
+    controller: {
+        kind: "inline";
+    } | {
+        kind: "external";
+        src: string;
+    } | null;
+    path: string;
+    width: number;
+    height: number;
+    bytes: number;
+    diagnostics: CompositionDiagnostic[];
+    elapsedMs: number;
+}
+export type RenderResult = VideoRenderResult | ImageRenderResult;
 export declare const MAX_RENDER_CONCURRENCY = 16;
 /** Validates the render concurrency flag and returns its normalized value. */
 export declare function validateRenderConcurrency(value: number | undefined): number;
 export declare function checkComposition(options: SessionOptions): Promise<CheckResult>;
+export declare function captureStills(options: SessionOptions & {
+    frames: number[];
+    outPaths: string[];
+    overwrite?: boolean;
+}): Promise<StillResult>;
 export declare function captureStill(options: SessionOptions & {
     frame: number;
     outPath: string;
     overwrite?: boolean;
 }): Promise<StillResult>;
 export declare function renderComposition(options: SessionOptions & {
-    outPath: string;
+    outPath?: string;
     overwrite?: boolean;
     concurrency?: number;
+    /** Encoder choice; defaults to the codec's software encoder. */
+    encoder?: VideoEncoderChoice;
+    /** Delivery codec; defaults to `h264`. */
+    codec?: VideoCodec;
+    /** Delivery container; defaults to `mp4`. */
+    container?: VideoContainer;
 }): Promise<RenderResult>;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/renderer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/renderer/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/renderer/index.ts"],"names":[],"mappings":"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"}

package/dist/renderer/index.js

@@ -2,12 +2,14 @@ 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 { COMPOSITION_FORMAT_UNRESOLVED_MESSAGE } from "../composition/index.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, mixAudioTimeline, startVideoEncoder } from "./ffmpeg.js";
+import { assertContainerCodec, assertFfmpegCapabilities, CONTAINER_EXTENSION, defaultCodecForContainer, mixAudioTimeline, resolveVideoEncoder, startVideoEncoder, } from "./ffmpeg.js";
 import { inspectTranscriptClips } from "./transcripts.js";
 export const MAX_RENDER_CONCURRENCY = 16;
 /** Validates the render concurrency flag and returns its normalized value. */
@@ -55,6 +57,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,
+    });
+}
 async function readSessionDiagnostics(sessions) {
     const groups = await Promise.all(sessions.map((session) => session.readDiagnostics()));
     return mergeDiagnostics(...groups);
@@ -79,6 +96,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);
@@ -100,21 +136,28 @@ async function publishFile(tempPath, outPath, overwrite) {
         await rm(tempPath, { force: true });
     }
 }
-async function withSessions(options, resolveSessionCount, callback) {
+async function prepareComposition(options) {
     throwIfAborted(options.signal);
     const composition = compositionFor(options.project, options.compositionId);
     const validation = await validateHtmlComposition({
         projectRoot: options.project.root,
         entry: composition.entry,
         props: options.props,
+        ...(options.project.format ? { format: options.project.format } : {}),
     });
     const staticDiagnostics = validation.diagnostics;
     const staticErrors = staticDiagnostics.filter((diagnostic) => diagnostic.severity === "error");
     if (!validation.info || staticErrors.length > 0) {
         const first = staticErrors[0];
+        if (!first && validation.formatUnresolved) {
+            throw new FrameyardError("COMPOSITION_FORMAT_UNRESOLVED", `Composition "${options.compositionId}": ${COMPOSITION_FORMAT_UNRESOLVED_MESSAGE}`, { diagnostics: validation.diagnostics });
+        }
         throw new FrameyardError(first?.code ?? "COMPOSITION_INVALID", `Composition "${options.compositionId}": ${first?.message ?? "static validation failed."}`, { diagnostics: validation.diagnostics });
     }
-    const staticInfo = validation.info;
+    return { composition, staticInfo: validation.info, staticDiagnostics };
+}
+async function withPreparedSessions(options, prepared, resolveSessionCount, callback) {
+    const { composition, staticInfo, staticDiagnostics } = prepared;
     const server = await startPreviewServer({ projectRoot: options.project.root, port: 0 });
     const sessions = [];
     try {
@@ -176,9 +219,6 @@ async function withSessions(options, resolveSessionCount, callback) {
         }
     }
 }
-async function withSession(options, callback) {
-    return withSessions(options, () => 1, async (sessions) => callback(sessions[0]));
-}
 function reportProgress(options, frame, total, startedAt) {
     options.onProgress?.({ frame, total, elapsedMs: performance.now() - startedAt });
 }
@@ -264,12 +304,31 @@ async function captureFramesInOrder(options) {
 }
 export async function checkComposition(options) {
     const startedAt = performance.now();
-    return withSession(options, async (session) => {
-        const total = session.metadata.durationInFrames;
+    const prepared = await prepareComposition(options);
+    return withPreparedSessions(options, prepared, () => 1, async (sessions) => {
+        const session = sessions[0];
+        const metadata = session.metadata;
+        if (metadata.static === true) {
+            throwIfAborted(options.signal);
+            await session.seek(0);
+            reportProgress(options, 1, 1, startedAt);
+            const diagnostics = mergeDiagnostics(prepared.staticDiagnostics, await session.readDiagnostics());
+            return {
+                kind: "static",
+                composition: options.compositionId,
+                entry: session.entry,
+                controller: session.controller,
+                metadata,
+                framesChecked: 1,
+                diagnostics,
+                elapsedMs: performance.now() - startedAt,
+            };
+        }
+        const total = metadata.durationInFrames;
         const audio = await inspectTimelineAudio({
             projectRoot: options.project.root,
             clips: timelineAudioClips(session),
-            fps: session.metadata.fps,
+            fps: metadata.fps,
             durationInFrames: total,
             signal: options.signal,
         });
@@ -285,10 +344,11 @@ export async function checkComposition(options) {
         }
         const diagnostics = mergeDiagnostics(await session.readDiagnostics(), audioDiagnostics(audio.warnings), transcriptDiagnostics(transcripts.warnings));
         return {
+            kind: "animated",
             composition: options.compositionId,
             entry: session.entry,
             controller: session.controller,
-            metadata: session.metadata,
+            metadata,
             framesChecked: total,
             audio: { clips: audio.clips.length, details: audio.clips },
             transcripts: {
@@ -300,63 +360,171 @@ export async function checkComposition(options) {
         };
     });
 }
-export async function captureStill(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}.`);
+export async function captureStills(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.");
     }
-    if (path.extname(options.outPath).toLowerCase() !== ".png") {
-        throw new FrameyardError("USAGE", `Still output must use a .png extension: ${options.outPath}`);
+    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 (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();
-    return withSession(options, async (session) => {
-        const total = session.metadata.durationInFrames;
-        if (options.frame >= total) {
-            throw new FrameyardError("FRAME_OUT_OF_RANGE", `Frame ${options.frame} is outside the valid range 0..${total - 1}.`);
-        }
+    const prepared = await prepareComposition(options);
+    const metadata = prepared.staticInfo.metadata;
+    const total = metadata.static === true ? 1 : metadata.durationInFrames;
+    const invalidFrames = options.frames.filter((frame) => frame >= total);
+    if (invalidFrames.length > 0) {
+        const first = invalidFrames[0];
+        throw new FrameyardError("FRAME_OUT_OF_RANGE", `Frame ${first} is outside the valid range 0..${total - 1}.`, {
+            details: { invalidFrames, validRange: { min: 0, max: total - 1 } },
+        });
+    }
+    await assertOutputsAvailable(options.outPaths, overwrite);
+    for (const outPath of options.outPaths) {
+        await mkdir(path.dirname(outPath), { recursive: true });
+    }
+    return withPreparedSessions(options, prepared, () => 1, async (sessions) => {
+        const session = sessions[0];
         const transcripts = await inspectTranscriptClips({
             projectRoot: options.project.root,
             clips: session.transcriptClips,
             signal: options.signal,
         });
-        throwIfAborted(options.signal);
-        await session.seek(options.frame);
-        const png = await session.capture();
-        const diagnostics = mergeDiagnostics(await session.readDiagnostics(), transcriptDiagnostics(transcripts.warnings));
-        const tempPath = path.join(path.dirname(options.outPath), `.${path.basename(options.outPath)}.frameyard-${process.pid}-${randomUUID()}.tmp`);
+        const tempPaths = options.outPaths.map((outPath) => path.join(path.dirname(outPath), `.${path.basename(outPath)}.frameyard-${process.pid}-${randomUUID()}.tmp`));
+        try {
+            for (const [index, frame] of options.frames.entries()) {
+                throwIfAborted(options.signal);
+                try {
+                    await session.seek(frame);
+                    const png = await session.capture();
+                    await writeFile(tempPaths[index], png);
+                }
+                catch (error) {
+                    throw withBatchContext(error, options.frames, frame);
+                }
+            }
+            await assertOutputsAvailable(options.outPaths, overwrite);
+            const diagnostics = mergeDiagnostics(metadata.static === true ? prepared.staticDiagnostics : [], await session.readDiagnostics(), transcriptDiagnostics(transcripts.warnings));
+            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 {
+                composition: options.compositionId,
+                entry: session.entry,
+                controller: session.controller,
+                ...(frames.length === 1 && first !== undefined ? { frame: first.frame, path: first.path } : {}),
+                frames,
+                width: session.metadata.width,
+                height: session.metadata.height,
+                diagnostics,
+                elapsedMs: performance.now() - startedAt,
+            };
+        }
+        finally {
+            await Promise.all(tempPaths.map((tempPath) => rm(tempPath, { force: true })));
+        }
+    });
+}
+export async function captureStill(options) {
+    const { frame, outPath, ...rest } = options;
+    return captureStills({
+        ...rest,
+        frames: [frame],
+        outPaths: [outPath],
+    });
+}
+async function renderStaticComposition(options, prepared, startedAt) {
+    if (options.container !== undefined ||
+        options.codec !== undefined ||
+        options.encoder !== undefined ||
+        options.concurrency !== undefined) {
+        throw new FrameyardError("USAGE", "Static compositions render to PNG; --container, --codec, --encoder, and --concurrency are not valid.");
+    }
+    const metadata = prepared.staticInfo.metadata;
+    if (metadata.static !== true) {
+        throw new FrameyardError("INTERNAL", "renderStaticComposition received an animated composition.");
+    }
+    const outPath = options.outPath ?? path.join(options.project.root, "out", `${options.compositionId}.png`);
+    if (path.extname(outPath).toLowerCase() !== ".png") {
+        throw new FrameyardError("USAGE", `Static compositions render to a .png file: ${outPath}`);
+    }
+    const overwrite = options.overwrite ?? false;
+    await ensureOutputAvailable(outPath, overwrite);
+    return withPreparedSessions(options, prepared, () => 1, async (sessions) => {
+        const session = sessions[0];
+        const tempPath = path.join(path.dirname(outPath), `.${path.basename(outPath)}.frameyard-${process.pid}-${randomUUID()}.tmp`);
         try {
+            throwIfAborted(options.signal);
+            await session.seek(0);
+            const png = await session.capture();
             await writeFile(tempPath, png);
-            await ensureOutputAvailable(options.outPath, overwrite);
-            await publishFile(tempPath, options.outPath, overwrite);
+            await assertOutputsAvailable([outPath], overwrite);
+            await publishFile(tempPath, outPath, overwrite);
+            reportProgress(options, 1, 1, startedAt);
+            const diagnostics = mergeDiagnostics(prepared.staticDiagnostics, await session.readDiagnostics());
+            return {
+                kind: "image",
+                composition: options.compositionId,
+                entry: session.entry,
+                controller: session.controller,
+                path: outPath,
+                width: metadata.width,
+                height: metadata.height,
+                bytes: (await stat(outPath)).size,
+                diagnostics,
+                elapsedMs: performance.now() - startedAt,
+            };
         }
         finally {
             await rm(tempPath, { force: true });
         }
-        return {
-            composition: options.compositionId,
-            entry: session.entry,
-            controller: session.controller,
-            frame: options.frame,
-            path: options.outPath,
-            width: session.metadata.width,
-            height: session.metadata.height,
-            diagnostics,
-            elapsedMs: performance.now() - startedAt,
-        };
     });
 }
 export async function renderComposition(options) {
-    if (path.extname(options.outPath).toLowerCase() !== ".mp4") {
-        throw new FrameyardError("USAGE", `Render output must use an .mp4 extension: ${options.outPath}`);
+    const startedAt = performance.now();
+    const prepared = await prepareComposition(options);
+    if (prepared.staticInfo.metadata.static === true) {
+        return renderStaticComposition(options, prepared, startedAt);
+    }
+    const container = options.container ?? "mp4";
+    const codec = options.codec ?? defaultCodecForContainer(container);
+    assertContainerCodec(container, codec);
+    const extension = `.${CONTAINER_EXTENSION[container]}`;
+    const outPath = options.outPath ?? path.join(options.project.root, "out", `${options.compositionId}${extension}`);
+    if (path.extname(outPath).toLowerCase() !== extension) {
+        throw new FrameyardError("USAGE", `Render output for --container ${container} must use a ${extension} extension: ${outPath}`);
     }
     const requestedConcurrency = validateRenderConcurrency(options.concurrency);
     const overwrite = options.overwrite ?? false;
-    await ensureOutputAvailable(options.outPath, overwrite);
-    await assertFfmpegCapabilities(options.signal);
-    const startedAt = performance.now();
-    return withSessions(options, (first) => Math.min(requestedConcurrency, first.metadata.durationInFrames), async (sessions) => {
+    await ensureOutputAvailable(outPath, overwrite);
+    await assertFfmpegCapabilities(options.signal, codec);
+    const encoderName = await resolveVideoEncoder(codec, options.encoder, options.signal);
+    return withPreparedSessions(options, prepared, (first) => (first.metadata.static === true ? 1 : Math.min(requestedConcurrency, first.metadata.durationInFrames)), async (sessions) => {
         const session = sessions[0];
+        if (session.metadata.static === true) {
+            throw new FrameyardError("INTERNAL", "An animated render opened a static composition session.");
+        }
         const { width, height, fps, durationInFrames } = session.metadata;
         const concurrency = sessions.length;
         if (width % 2 !== 0 || height % 2 !== 0) {
@@ -377,7 +545,7 @@ export async function renderComposition(options) {
             signal: options.signal,
         });
         const scratchDir = await mkdtemp(path.join(tmpdir(), "frameyard-render-"));
-        const tempOut = path.join(path.dirname(options.outPath), `.${path.basename(options.outPath)}.frameyard-${process.pid}-${randomUUID()}.mp4`);
+        const tempOut = path.join(path.dirname(outPath), `.${path.basename(outPath)}.frameyard-${process.pid}-${randomUUID()}.mp4`);
         let encoder;
         let completed = false;
         try {
@@ -403,6 +571,9 @@ export async function renderComposition(options) {
                 fps,
                 frames: total,
                 durationSeconds,
+                encoder: encoderName,
+                codec,
+                container,
                 ...(audioPath !== undefined ? { audioPath } : {}),
                 signal: options.signal,
             });
@@ -428,17 +599,18 @@ export async function renderComposition(options) {
             }
             await encoder.finish();
             encoder = undefined;
-            if (!overwrite && (await pathExists(options.outPath))) {
-                throw new FrameyardError("OUTPUT_EXISTS", `Output already exists: ${options.outPath}. Pass --overwrite to replace it.`);
+            if (!overwrite && (await pathExists(outPath))) {
+                throw new FrameyardError("OUTPUT_EXISTS", `Output already exists: ${outPath}. Pass --overwrite to replace it.`);
             }
-            await publishFile(tempOut, options.outPath, overwrite);
+            await publishFile(tempOut, outPath, overwrite);
             completed = true;
             const diagnostics = mergeDiagnostics(await readSessionDiagnostics(sessions), audioDiagnostics(audio.warnings), transcriptDiagnostics(transcripts.warnings));
             return {
+                kind: "video",
                 composition: options.compositionId,
                 entry: session.entry,
                 controller: session.controller,
-                path: options.outPath,
+                path: outPath,
                 width,
                 height,
                 fps,
@@ -446,7 +618,10 @@ export async function renderComposition(options) {
                 durationSeconds,
                 framesRendered: total,
                 concurrency,
-                bytes: (await stat(options.outPath)).size,
+                codec,
+                container,
+                encoder: encoderName,
+                bytes: (await stat(outPath)).size,
                 audio: { clips: audio.clips.length },
                 transcripts: {
                     clips: transcripts.clips.length,