@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/renderCache.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Per-beat render caching, so changing one caption does not cost a full re-render.
+ *
+ * diff_beats can already tell you that exactly one beat changed. Until now the only
+ * available response was render_video, which re-renders the whole composition, because
+ * Remotion has no partial-render mode. On a five minute video that is 9000 frames for a
+ * one word edit, which is slow enough that nobody edits.
+ *
+ * The way around it is that Remotion does support rendering a frame RANGE. A beat owns a
+ * contiguous range (`start` to `start + duration - 1`), so each beat can be rendered to
+ * its own segment and the segments concatenated with ffmpeg's concat demuxer under stream
+ * copy: no re-encode, no generation loss, and the result is the same bytes the encoder
+ * would have produced for that range in one pass.
+ *
+ * What makes it safe is hashing the real inputs. A segment is reused only when the beat's
+ * own JSON, its scene source, every artifact it references, its narration file, and the
+ * project-wide inputs that affect every frame (brand tokens, the generated composition,
+ * the music bed) are all byte-identical to when that segment was rendered. Anything this
+ * cannot see is a correctness bug, so the hash deliberately errs toward including too much:
+ * a false cache miss costs one segment render, a false cache hit ships a wrong video.
+ */
+export declare const CACHE_VERSION = 2;
+export interface CachedSegment {
+    hash: string;
+    /** Project-relative path, so a cache written on one machine is readable on another. */
+    file: string;
+    start: number;
+    duration: number;
+    renderedAt: string;
+}
+export interface RenderCacheManifest {
+    version: number;
+    compositionId: string;
+    /** Render settings that change every frame, so a draft segment is never reused for a final. */
+    renderKey: string;
+    segments: Record<string, CachedSegment>;
+}
+export interface BeatLike {
+    id: string;
+    start: number;
+    duration: number;
+    visual?: {
+        assetPath?: string;
+    };
+    artifacts?: Record<string, string | undefined>;
+}
+/**
+ * Hash of a file's contents, or a fixed sentinel when it does not exist.
+ *
+ * Absence is hashed rather than skipped: a beat whose screenshot was deleted has genuinely
+ * changed, and skipping a missing file would make the deletion invisible to the cache.
+ */
+export declare function hashFile(absPath: string): string;
+/**
+ * Inputs shared by every beat: change any of them and no segment is reusable.
+ *
+ * brand.ts is here because applyBrand mutates the token objects every scene reads, so a
+ * brand change repaints frames whose own scene file never moved. The generated composition
+ * is here because it owns the audio layout and the sequence boundaries.
+ */
+export declare function globalInputsHash(projectRoot: string, videoName: string, compositionId: string): string;
+/** Every file on disk a single beat's frames are drawn from. */
+export declare function beatInputFiles(projectRoot: string, videoName: string, beat: BeatLike): string[];
+export declare function beatHash(projectRoot: string, videoName: string, beat: BeatLike, globalHash: string): string;
+/**
+ * Settings that change the pixels of every frame. Kept separate from the per-beat hash so
+ * a switch between draft and final invalidates the whole cache in one comparison rather
+ * than looking like every beat changed at once.
+ */
+export declare function renderKey(opts: {
+    draft?: boolean;
+    width: number;
+    height: number;
+    fps: number;
+}): string;
+export declare function cachePath(projectRoot: string, videoName: string): string;
+export declare function segmentsDir(projectRoot: string, videoName: string): string;
+export declare function readCache(projectRoot: string, videoName: string): RenderCacheManifest | null;
+export declare function writeCache(projectRoot: string, videoName: string, manifest: RenderCacheManifest): void;
+export interface SegmentPlan {
+    beatId: string;
+    hash: string;
+    /** Project-relative. */
+    file: string;
+    firstFrame: number;
+    lastFrame: number;
+    reused: boolean;
+}
+/**
+ * Decides, per beat, whether the existing segment can be reused.
+ *
+ * A cache entry is trusted only if the hash matches, the render settings match, AND the
+ * segment file is still on disk: a manifest that outlived its own output is the commonest
+ * way a cache lies.
+ */
+export declare function planSegments(opts: {
+    projectRoot: string;
+    videoName: string;
+    compositionId: string;
+    beats: BeatLike[];
+    renderKey: string;
+    cache: RenderCacheManifest | null;
+}): {
+    plan: SegmentPlan[];
+    globalHash: string;
+};
+/**
+ * Remotion's frame-range render, for one beat.
+ *
+ * `--enforce-audio-track` is not optional here. A beat with no narration renders with no
+ * audio stream at all, and the concat demuxer under stream copy cannot join a segment that
+ * has an audio track to one that does not: it either fails or silently drops the audio for
+ * the rest of the file. Forcing a silent track onto every segment costs nothing and makes
+ * the streams uniform, which is the precondition for copying rather than re-encoding.
+ */
+export declare function buildSegmentRenderArgs(compositionId: string, outPath: string, firstFrame: number, lastFrame: number, opts?: {
+    draft?: boolean;
+    concurrency?: number;
+    browserExecutable?: string;
+}): {
+    command: string;
+    args: string[];
+};
+/**
+ * concat demuxer list. Paths are single-quoted with embedded quotes escaped per ffmpeg's
+ * own rules, and written relative to the list file's directory so the list is portable.
+ */
+export declare function buildConcatList(segmentFiles: string[]): string;
+export declare function buildConcatArgs(listPath: string, outPath: string): string[];
+/**
+ * Sample-exact audio join for the incremental render's concat step.
+ *
+ * Each per-beat segment is rendered separately and its AAC track ends up a little longer
+ * than its video: the encoder pads to a full AAC frame (1024 samples), typically tens of ms
+ * per segment. Stream-copying every segment's audio track under the same concat demuxer that
+ * joins the video stacks that padding beat over beat, so a 16-beat video can end with its
+ * audio visibly behind its video even though every individual segment looks fine in
+ * isolation. The fix joins video and audio through two different paths: video stays a
+ * gapless stream copy (no per-segment padding on the video side), audio is decoded to raw
+ * PCM per segment, trimmed or padded to exactly `duration/fps` seconds, concatenated as raw
+ * samples, and encoded to AAC once at the end -- so the only rounding that can happen is
+ * inside a single final encode, not once per beat.
+ */
+export declare const AUDIO_SAMPLE_RATE = 48000;
+export declare const AUDIO_CHANNELS = 2;
+export declare function pcmFileName(beatId: string): string;
+/** ffmpeg args to decode one segment's audio to raw interleaved s16le PCM. */
+export declare function buildExtractPcmArgs(segmentFile: string, pcmOutPath: string): string[];
+/** Exact PCM byte length for a beat of `durationFrames` at `fps`, at the canonical rate above. */
+export declare function expectedPcmBytes(durationFrames: number, fps: number): number;
+/**
+ * Trims or zero-pads (silence) a PCM buffer to exactly `expectedBytes`. Pure and
+ * frame-count-based, so this is what makes the join sample-exact rather than
+ * "close, rounded to whatever the codec happened to produce."
+ */
+export declare function fitPcmLength(buf: Buffer, expectedBytes: number): Buffer;
+/**
+ * Strips a segment's audio into its own fresh container.
+ *
+ * This has to happen before concatenation, not as an `-an` flag on the concat step itself:
+ * each beat's segment is muxed with audio deliberately longer than its video (the padding
+ * this whole join exists to defeat), so the segment's own container-level duration reflects
+ * that longer audio track, not the true video length. The concat demuxer trusts each input's
+ * container duration to place the next file's start, so concatenating the original segments
+ * with `-an` still leaves a gap at every join equal to that segment's audio overrun -- the
+ * video track ends up gapful, just silent instead of desynced. Re-muxing video-only into its
+ * own container first drops that stale duration along with the audio, so the isolated file's
+ * own duration is the true one and concatenation is actually gapless.
+ */
+export declare function buildIsolateVideoArgs(segmentFile: string, videoOnlyOutPath: string): string[];
+export declare function videoOnlyFileName(beatId: string): string;
+/** Video-only stream copy over already-isolated per-segment files: gapless picture track. */
+export declare function buildVideoOnlyConcatArgs(listPath: string, outPath: string): string[];
+/**
+ * Final mux: the gapless video-only file plus one raw-PCM audio input (already the exact
+ * concatenation of every beat's trimmed/padded PCM), encoded to AAC exactly once.
+ */
+export declare function buildFinalMuxArgs(videoOnlyPath: string, concatPcmPath: string, outPath: string): string[];

package/dist/renderCache.js

@@ -0,0 +1,371 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDIO_CHANNELS = exports.AUDIO_SAMPLE_RATE = exports.CACHE_VERSION = void 0;
+exports.hashFile = hashFile;
+exports.globalInputsHash = globalInputsHash;
+exports.beatInputFiles = beatInputFiles;
+exports.beatHash = beatHash;
+exports.renderKey = renderKey;
+exports.cachePath = cachePath;
+exports.segmentsDir = segmentsDir;
+exports.readCache = readCache;
+exports.writeCache = writeCache;
+exports.planSegments = planSegments;
+exports.buildSegmentRenderArgs = buildSegmentRenderArgs;
+exports.buildConcatList = buildConcatList;
+exports.buildConcatArgs = buildConcatArgs;
+exports.pcmFileName = pcmFileName;
+exports.buildExtractPcmArgs = buildExtractPcmArgs;
+exports.expectedPcmBytes = expectedPcmBytes;
+exports.fitPcmLength = fitPcmLength;
+exports.buildIsolateVideoArgs = buildIsolateVideoArgs;
+exports.videoOnlyFileName = videoOnlyFileName;
+exports.buildVideoOnlyConcatArgs = buildVideoOnlyConcatArgs;
+exports.buildFinalMuxArgs = buildFinalMuxArgs;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
+const util_1 = require("./util");
+/**
+ * Per-beat render caching, so changing one caption does not cost a full re-render.
+ *
+ * diff_beats can already tell you that exactly one beat changed. Until now the only
+ * available response was render_video, which re-renders the whole composition, because
+ * Remotion has no partial-render mode. On a five minute video that is 9000 frames for a
+ * one word edit, which is slow enough that nobody edits.
+ *
+ * The way around it is that Remotion does support rendering a frame RANGE. A beat owns a
+ * contiguous range (`start` to `start + duration - 1`), so each beat can be rendered to
+ * its own segment and the segments concatenated with ffmpeg's concat demuxer under stream
+ * copy: no re-encode, no generation loss, and the result is the same bytes the encoder
+ * would have produced for that range in one pass.
+ *
+ * What makes it safe is hashing the real inputs. A segment is reused only when the beat's
+ * own JSON, its scene source, every artifact it references, its narration file, and the
+ * project-wide inputs that affect every frame (brand tokens, the generated composition,
+ * the music bed) are all byte-identical to when that segment was rendered. Anything this
+ * cannot see is a correctness bug, so the hash deliberately errs toward including too much:
+ * a false cache miss costs one segment render, a false cache hit ships a wrong video.
+ */
+exports.CACHE_VERSION = 2;
+const EMPTY = "0".repeat(64);
+function sha256(data) {
+    const input = typeof data === "string" || ArrayBuffer.isView(data) ? data : Buffer.from(data);
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+/**
+ * Hash of a file's contents, or a fixed sentinel when it does not exist.
+ *
+ * Absence is hashed rather than skipped: a beat whose screenshot was deleted has genuinely
+ * changed, and skipping a missing file would make the deletion invisible to the cache.
+ */
+function hashFile(absPath) {
+    if (!fs.existsSync(absPath))
+        return EMPTY;
+    const stat = fs.statSync(absPath);
+    if (!stat.isFile())
+        return EMPTY;
+    return sha256(fs.readFileSync(absPath));
+}
+/**
+ * Inputs shared by every beat: change any of them and no segment is reusable.
+ *
+ * brand.ts is here because applyBrand mutates the token objects every scene reads, so a
+ * brand change repaints frames whose own scene file never moved. The generated composition
+ * is here because it owns the audio layout and the sequence boundaries.
+ */
+function globalInputsHash(projectRoot, videoName, compositionId) {
+    const files = [
+        path.join(projectRoot, "src", "brand.ts"),
+        path.join(projectRoot, "src", "videos", videoName, `${compositionId}.tsx`),
+        path.join(projectRoot, "public", "audio", "music-bed.mp3"),
+        path.join(projectRoot, "openvidstudio.config.json"),
+    ];
+    return sha256(files.map(hashFile).join(":"));
+}
+/** Every file on disk a single beat's frames are drawn from. */
+function beatInputFiles(projectRoot, videoName, beat) {
+    const files = [
+        path.join(projectRoot, "src", "videos", videoName, "scenes", `${(0, util_1.pascalCase)(beat.id)}.tsx`),
+        path.join(projectRoot, "public", "audio", "vo", `${beat.id}.mp3`),
+        // Convention paths for each capture kind. Hashing all of them regardless of this
+        // beat's captureMethod costs nothing (a missing file hashes to the sentinel) and means
+        // a beat that switches from a screenshot to a recording is not mistaken for unchanged.
+        path.join(projectRoot, "public", "images", `${beat.id}.png`),
+        path.join(projectRoot, "public", "video", `${beat.id}.mp4`),
+        path.join(projectRoot, "public", "terminal", `${beat.id}.json`),
+    ];
+    for (const rel of Object.values(beat.artifacts ?? {})) {
+        if (typeof rel === "string" && rel.length > 0)
+            files.push(path.join(projectRoot, rel));
+    }
+    if (beat.visual?.assetPath)
+        files.push(path.join(projectRoot, beat.visual.assetPath));
+    return files;
+}
+function beatHash(projectRoot, videoName, beat, globalHash) {
+    const parts = [
+        String(exports.CACHE_VERSION),
+        globalHash,
+        JSON.stringify(beat),
+        ...beatInputFiles(projectRoot, videoName, beat).map(hashFile),
+    ];
+    return sha256(parts.join(":"));
+}
+/**
+ * Settings that change the pixels of every frame. Kept separate from the per-beat hash so
+ * a switch between draft and final invalidates the whole cache in one comparison rather
+ * than looking like every beat changed at once.
+ */
+function renderKey(opts) {
+    return `${opts.draft ? "draft" : "final"}-${opts.width}x${opts.height}@${opts.fps}`;
+}
+function cachePath(projectRoot, videoName) {
+    return path.join(projectRoot, "output", "segments", videoName, "cache.json");
+}
+function segmentsDir(projectRoot, videoName) {
+    return path.join(projectRoot, "output", "segments", videoName);
+}
+function readCache(projectRoot, videoName) {
+    const p = cachePath(projectRoot, videoName);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
+        return parsed.version === exports.CACHE_VERSION ? parsed : null;
+    }
+    catch {
+        // A half-written manifest is a reason to re-render everything, not to fail the render.
+        return null;
+    }
+}
+function writeCache(projectRoot, videoName, manifest) {
+    const p = cachePath(projectRoot, videoName);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+/**
+ * Decides, per beat, whether the existing segment can be reused.
+ *
+ * A cache entry is trusted only if the hash matches, the render settings match, AND the
+ * segment file is still on disk: a manifest that outlived its own output is the commonest
+ * way a cache lies.
+ */
+function planSegments(opts) {
+    const { projectRoot, videoName, compositionId, beats, cache } = opts;
+    const globalHash = globalInputsHash(projectRoot, videoName, compositionId);
+    const usable = cache && cache.renderKey === opts.renderKey && cache.compositionId === compositionId ? cache : null;
+    const plan = beats.map((beat) => {
+        const hash = beatHash(projectRoot, videoName, beat, globalHash);
+        // Posix separators, deliberately: this string is written into a manifest that should
+        // still read correctly if the project is opened on another platform.
+        const file = `output/segments/${videoName}/${beat.id}.mp4`;
+        const cached = usable?.segments[beat.id];
+        const reused = Boolean(cached) &&
+            cached.hash === hash &&
+            cached.start === beat.start &&
+            cached.duration === beat.duration &&
+            fs.existsSync(path.join(projectRoot, file));
+        return {
+            beatId: beat.id,
+            hash,
+            file,
+            firstFrame: beat.start,
+            lastFrame: beat.start + beat.duration - 1,
+            reused,
+        };
+    });
+    return { plan, globalHash };
+}
+/**
+ * Remotion's frame-range render, for one beat.
+ *
+ * `--enforce-audio-track` is not optional here. A beat with no narration renders with no
+ * audio stream at all, and the concat demuxer under stream copy cannot join a segment that
+ * has an audio track to one that does not: it either fails or silently drops the audio for
+ * the rest of the file. Forcing a silent track onto every segment costs nothing and makes
+ * the streams uniform, which is the precondition for copying rather than re-encoding.
+ */
+function buildSegmentRenderArgs(compositionId, outPath, firstFrame, lastFrame, opts = {}) {
+    const args = ["remotion", "render", compositionId, outPath, `--frames=${firstFrame}-${lastFrame}`, "--enforce-audio-track"];
+    if (opts.draft)
+        args.push("--scale=0.5", "--crf=32", "--x264-preset=veryfast");
+    if (opts.concurrency && opts.concurrency > 0)
+        args.push(`--concurrency=${Math.floor(opts.concurrency)}`);
+    // See buildRenderCommand's matching option (renderVideo.ts): reuses the project's
+    // configured browser instead of Remotion downloading its own.
+    if (opts.browserExecutable)
+        args.push(`--browser-executable=${opts.browserExecutable}`);
+    args.push("--log=verbose");
+    return { command: process.platform === "win32" ? "npx.cmd" : "npx", args };
+}
+/**
+ * concat demuxer list. Paths are single-quoted with embedded quotes escaped per ffmpeg's
+ * own rules, and written relative to the list file's directory so the list is portable.
+ */
+function buildConcatList(segmentFiles) {
+    return segmentFiles.map((f) => `file '${f.replace(/'/g, "'\\''")}'`).join("\n") + "\n";
+}
+function buildConcatArgs(listPath, outPath) {
+    return [
+        "-nostdin",
+        "-f",
+        "concat",
+        // The list holds relative names; -safe 0 is what allows anything but a bare basename.
+        "-safe",
+        "0",
+        "-i",
+        listPath,
+        "-c",
+        "copy",
+        "-movflags",
+        "+faststart",
+        outPath,
+        "-y",
+    ];
+}
+/**
+ * Sample-exact audio join for the incremental render's concat step.
+ *
+ * Each per-beat segment is rendered separately and its AAC track ends up a little longer
+ * than its video: the encoder pads to a full AAC frame (1024 samples), typically tens of ms
+ * per segment. Stream-copying every segment's audio track under the same concat demuxer that
+ * joins the video stacks that padding beat over beat, so a 16-beat video can end with its
+ * audio visibly behind its video even though every individual segment looks fine in
+ * isolation. The fix joins video and audio through two different paths: video stays a
+ * gapless stream copy (no per-segment padding on the video side), audio is decoded to raw
+ * PCM per segment, trimmed or padded to exactly `duration/fps` seconds, concatenated as raw
+ * samples, and encoded to AAC once at the end -- so the only rounding that can happen is
+ * inside a single final encode, not once per beat.
+ */
+exports.AUDIO_SAMPLE_RATE = 48000;
+exports.AUDIO_CHANNELS = 2;
+const BYTES_PER_SAMPLE = 2; // s16le
+function pcmFileName(beatId) {
+    return `${beatId}.pcm`;
+}
+/** ffmpeg args to decode one segment's audio to raw interleaved s16le PCM. */
+function buildExtractPcmArgs(segmentFile, pcmOutPath) {
+    return [
+        "-nostdin",
+        "-i",
+        segmentFile,
+        "-vn",
+        "-ar",
+        String(exports.AUDIO_SAMPLE_RATE),
+        "-ac",
+        String(exports.AUDIO_CHANNELS),
+        "-f",
+        "s16le",
+        "-y",
+        pcmOutPath,
+    ];
+}
+/** Exact PCM byte length for a beat of `durationFrames` at `fps`, at the canonical rate above. */
+function expectedPcmBytes(durationFrames, fps) {
+    const samples = Math.round((durationFrames / fps) * exports.AUDIO_SAMPLE_RATE);
+    return samples * exports.AUDIO_CHANNELS * BYTES_PER_SAMPLE;
+}
+/**
+ * Trims or zero-pads (silence) a PCM buffer to exactly `expectedBytes`. Pure and
+ * frame-count-based, so this is what makes the join sample-exact rather than
+ * "close, rounded to whatever the codec happened to produce."
+ */
+function fitPcmLength(buf, expectedBytes) {
+    if (buf.length === expectedBytes)
+        return buf;
+    if (buf.length > expectedBytes)
+        return buf.subarray(0, expectedBytes);
+    const out = Buffer.alloc(expectedBytes);
+    buf.copy(out);
+    return out;
+}
+/**
+ * Strips a segment's audio into its own fresh container.
+ *
+ * This has to happen before concatenation, not as an `-an` flag on the concat step itself:
+ * each beat's segment is muxed with audio deliberately longer than its video (the padding
+ * this whole join exists to defeat), so the segment's own container-level duration reflects
+ * that longer audio track, not the true video length. The concat demuxer trusts each input's
+ * container duration to place the next file's start, so concatenating the original segments
+ * with `-an` still leaves a gap at every join equal to that segment's audio overrun -- the
+ * video track ends up gapful, just silent instead of desynced. Re-muxing video-only into its
+ * own container first drops that stale duration along with the audio, so the isolated file's
+ * own duration is the true one and concatenation is actually gapless.
+ */
+function buildIsolateVideoArgs(segmentFile, videoOnlyOutPath) {
+    return ["-nostdin", "-i", segmentFile, "-an", "-c:v", "copy", "-y", videoOnlyOutPath];
+}
+function videoOnlyFileName(beatId) {
+    return `_vo-${beatId}.mp4`;
+}
+/** Video-only stream copy over already-isolated per-segment files: gapless picture track. */
+function buildVideoOnlyConcatArgs(listPath, outPath) {
+    return ["-nostdin", "-f", "concat", "-safe", "0", "-i", listPath, "-an", "-c", "copy", "-y", outPath];
+}
+/**
+ * Final mux: the gapless video-only file plus one raw-PCM audio input (already the exact
+ * concatenation of every beat's trimmed/padded PCM), encoded to AAC exactly once.
+ */
+function buildFinalMuxArgs(videoOnlyPath, concatPcmPath, outPath) {
+    return [
+        "-nostdin",
+        "-i",
+        videoOnlyPath,
+        "-f",
+        "s16le",
+        "-ar",
+        String(exports.AUDIO_SAMPLE_RATE),
+        "-ac",
+        String(exports.AUDIO_CHANNELS),
+        "-i",
+        concatPcmPath,
+        "-map",
+        "0:v:0",
+        "-map",
+        "1:a:0",
+        "-c:v",
+        "copy",
+        "-c:a",
+        "aac",
+        "-b:a",
+        "192k",
+        "-movflags",
+        "+faststart",
+        "-y",
+        outPath,
+    ];
+}

package/dist/scenes/castToSteps.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a capture_terminal cast into TerminalReplay's TermStep[].
+ *
+ * The cast stores what actually happened: every stdout/stderr chunk with the millisecond
+ * offset it arrived at. TerminalReplay thinks in frames and in typed commands versus
+ * revealed output. This bridges the two, and the thing it must not lose is the real
+ * timing: a build that paused four seconds should pause four seconds on screen, because
+ * honest waiting is most of what makes a terminal demo convincing.
+ */
+export interface TerminalCastLike {
+    command?: string;
+    cols?: number;
+    rows?: number;
+    durationMs?: number;
+    events?: [number, string, string][];
+}
+export type TermLine = {
+    text: string;
+    color?: string;
+    glow?: boolean;
+    bold?: boolean;
+};
+export type TermStep = {
+    type: "cmd";
+    text: string;
+} | {
+    type: "out";
+    lines: TermLine[];
+    stagger?: number;
+    preDelay?: number;
+} | {
+    type: "pause";
+    frames: number;
+};
+/**
+ * Strips ANSI escape sequences. TerminalReplay renders plain text with its own colours,
+ * so leaving raw escapes in would print literal garbage like `[0;32m` on screen.
+ * Colour intent is preserved coarsely instead, via the stdout/stderr split.
+ */
+export declare function stripAnsi(text: string): string;
+export declare function castToSteps(cast: TerminalCastLike, fps?: number): TermStep[];
+/**
+ * Serializes steps into the generated scene.
+ *
+ * `color.textSecondary` has to appear as an identifier in the emitted TSX, not as the
+ * string "color.textSecondary", so the scene picks up whatever palette extract_brand
+ * resolved. JSON.stringify would quote it, so the quotes are removed afterwards.
+ */
+export declare function serializeSteps(steps: TermStep[]): string;

package/dist/scenes/castToSteps.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Converts a capture_terminal cast into TerminalReplay's TermStep[].
+ *
+ * The cast stores what actually happened: every stdout/stderr chunk with the millisecond
+ * offset it arrived at. TerminalReplay thinks in frames and in typed commands versus
+ * revealed output. This bridges the two, and the thing it must not lose is the real
+ * timing: a build that paused four seconds should pause four seconds on screen, because
+ * honest waiting is most of what makes a terminal demo convincing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripAnsi = stripAnsi;
+exports.castToSteps = castToSteps;
+exports.serializeSteps = serializeSteps;
+/** Gaps shorter than this are just chunk boundaries, not real waiting, so they are not drawn. */
+const MIN_PAUSE_MS = 220;
+/** A very long wait is real but boring; compress it rather than stalling the video on it. */
+const MAX_PAUSE_MS = 2500;
+const COLOR_STDERR = "color.danger";
+const COLOR_STDOUT = "color.textSecondary";
+/**
+ * Strips ANSI escape sequences. TerminalReplay renders plain text with its own colours,
+ * so leaving raw escapes in would print literal garbage like `[0;32m` on screen.
+ * Colour intent is preserved coarsely instead, via the stdout/stderr split.
+ */
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\r/g, "");
+}
+function castToSteps(cast, fps = 30) {
+    const steps = [];
+    const command = (cast.command ?? "").trim();
+    if (command.length > 0) {
+        steps.push({ type: "cmd", text: command });
+    }
+    const events = Array.isArray(cast.events) ? cast.events : [];
+    let prevMs = 0;
+    for (const event of events) {
+        if (!Array.isArray(event) || event.length < 3)
+            continue;
+        const [ms, stream, raw] = event;
+        if (typeof ms !== "number" || typeof raw !== "string")
+            continue;
+        const gap = ms - prevMs;
+        prevMs = ms;
+        if (gap >= MIN_PAUSE_MS) {
+            steps.push({ type: "pause", frames: Math.round((Math.min(gap, MAX_PAUSE_MS) / 1000) * fps) });
+        }
+        const lines = stripAnsi(raw)
+            .split("\n")
+            .filter((l) => l.trim().length > 0)
+            .map((text) => ({ text, color: stream === "e" ? COLOR_STDERR : COLOR_STDOUT }));
+        if (lines.length > 0) {
+            steps.push({ type: "out", lines });
+        }
+    }
+    return steps;
+}
+/**
+ * Serializes steps into the generated scene.
+ *
+ * `color.textSecondary` has to appear as an identifier in the emitted TSX, not as the
+ * string "color.textSecondary", so the scene picks up whatever palette extract_brand
+ * resolved. JSON.stringify would quote it, so the quotes are removed afterwards.
+ */
+function serializeSteps(steps) {
+    const json = JSON.stringify(steps, null, 2);
+    return json.replace(/"color":\s*"(color\.[A-Za-z]+)"/g, '"color": $1');
+}