@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/tools/exportRendition.js

@@ -0,0 +1,688 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORE_DEVICES = void 0;
+exports.beatMidpointSeconds = beatMidpointSeconds;
+exports.buildPaletteArgs = buildPaletteArgs;
+exports.buildGifArgs = buildGifArgs;
+exports.buildFrameArgs = buildFrameArgs;
+exports.buildStoreFrameArgs = buildStoreFrameArgs;
+exports.buildAttachPosterArgs = buildAttachPosterArgs;
+exports.buildScreenshotIndex = buildScreenshotIndex;
+exports.scoreFrameStats = scoreFrameStats;
+exports.pickBestScore = pickBestScore;
+exports.planShareEncode = planShareEncode;
+exports.buildSharePassArgs = buildSharePassArgs;
+exports.probeMedia = probeMedia;
+exports.planReelsExport = planReelsExport;
+exports.buildReelsArgs = buildReelsArgs;
+exports.runExportRendition = runExportRendition;
+exports.registerExportRendition = registerExportRendition;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const sharp_1 = __importDefault(require("sharp"));
+const util_1 = require("../util");
+const mcp_1 = require("./mcp");
+/**
+ * Exact pixel dimensions each store demands. These are the sizes the review process
+ * rejects a submission over, which is precisely why doing this by hand is tedious and
+ * doing it from a capture pipeline is nearly free.
+ */
+exports.STORE_DEVICES = {
+    "iphone-6.9": { width: 1290, height: 2796, label: "App Store, 6.9 inch iPhone" },
+    "iphone-6.5": { width: 1242, height: 2688, label: "App Store, 6.5 inch iPhone" },
+    "ipad-13": { width: 2064, height: 2752, label: "App Store, 13 inch iPad" },
+    "android-phone": { width: 1080, height: 1920, label: "Play Store, phone" },
+    "android-tablet": { width: 1600, height: 2560, label: "Play Store, 10 inch tablet" },
+};
+/** Mid-beat, in seconds. The midpoint is past any transition in and before any transition out. */
+function beatMidpointSeconds(beat, fps) {
+    return (beat.start + beat.duration / 2) / fps;
+}
+/**
+ * Two-pass GIF, because the one-pass version is why most README GIFs look like that.
+ *
+ * A GIF is limited to 256 colours. Without a generated palette ffmpeg falls back to a
+ * fixed web-safe one and everything banding-dithers into mud, which is the difference
+ * between a GIF that sells the product and one that makes it look like a 2003 screencast.
+ */
+function buildPaletteArgs(inPath, palettePath, fps, width) {
+    return [
+        "-nostdin",
+        "-i",
+        inPath,
+        "-vf",
+        `fps=${fps},scale=${width}:-1:flags=lanczos,palettegen=stats_mode=diff`,
+        palettePath,
+        "-y",
+    ];
+}
+function buildGifArgs(inPath, palettePath, outPath, fps, width) {
+    return [
+        "-nostdin",
+        "-i",
+        inPath,
+        "-i",
+        palettePath,
+        "-lavfi",
+        // bayer dithering rather than the default: it keeps flat UI surfaces flat instead of
+        // speckling them, and flat surfaces are most of what a product demo is.
+        `fps=${fps},scale=${width}:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=3`,
+        "-loop",
+        "0",
+        outPath,
+        "-y",
+    ];
+}
+function buildFrameArgs(inPath, seconds, outPath) {
+    // -ss before -i seeks on keyframes, which is fast and can land on the wrong frame. After
+    // -i it decodes to the exact timestamp, which is what a documentation screenshot needs.
+    return ["-nostdin", "-i", inPath, "-ss", seconds.toFixed(3), "-frames:v", "1", outPath, "-y"];
+}
+/**
+ * One store frame: the shot fitted inside the device's exact canvas, with a dark surround
+ * standing in for device chrome.
+ *
+ * Fitted rather than filled. A store frame that crops the product to fill the canvas
+ * removes exactly the UI the screenshot existed to show.
+ */
+function buildStoreFrameArgs(inPath, seconds, outPath, device, bezel) {
+    const innerW = device.width - bezel * 2;
+    const innerH = device.height - bezel * 2;
+    return [
+        "-nostdin",
+        "-i",
+        inPath,
+        "-ss",
+        seconds.toFixed(3),
+        "-frames:v",
+        "1",
+        "-vf",
+        `scale=${innerW}:${innerH}:force_original_aspect_ratio=decrease,` +
+            `pad=${device.width}:${device.height}:(ow-iw)/2:(oh-ih)/2:0x101014`,
+        outPath,
+        "-y",
+    ];
+}
+/**
+ * Attaches a still image to a video as its embedded thumbnail, the mechanism a podcast
+ * mp3's cover art uses (an `attached_pic`-disposed stream), rather than by re-encoding the
+ * first frame. `-c copy` on the picture stream means the original video and audio are
+ * copied byte-for-byte, not re-encoded, so a poster bake never touches the render's actual
+ * quality: only a thumbnail stream is added.
+ */
+function buildAttachPosterArgs(inPath, posterPath, outPath) {
+    return [
+        "-nostdin",
+        "-i",
+        inPath,
+        "-i",
+        posterPath,
+        "-map",
+        "0",
+        "-map",
+        "1",
+        "-c",
+        "copy",
+        "-c:v:1",
+        "mjpeg",
+        "-disposition:v:1",
+        "attached_pic",
+        outPath,
+        "-y",
+    ];
+}
+/** The docs index. Pairs every shot with what the video says over it, which is already written. */
+function buildScreenshotIndex(videoName, entries) {
+    const rows = entries
+        .map(({ file, beat }, i) => `### ${i + 1}. ${beat.visual?.caption ?? beat.id}\n\n` +
+        `![${beat.id}](./${file})\n\n` +
+        `${beat.vo ?? ""}\n`)
+        .join("\n");
+    return (`# ${videoName} screenshots\n\n` +
+        `Generated by openvidstudio's export_rendition from the same render the demo video was cut from, so\n` +
+        `these cannot drift from the video. Regenerate rather than editing: this file is overwritten.\n\n` +
+        rows);
+}
+/**
+ * Scores one frame as a poster candidate. A good poster is a picture with something in it, so
+ * the score is the frame's luma entropy (a flat or empty frame has little, a UI full of text and
+ * panels has a lot), scaled down when the frame has almost no contrast (stdev under 40) and cut
+ * to 30% when it is near-black or blown out (mean outside 30..225), which is what a fade or a
+ * transition frame looks like. It is a heuristic for "not a dud frame", not a taste judgement:
+ * pass posterBeatId or posterAt when a specific frame is wanted.
+ */
+function scoreFrameStats(stats) {
+    const contrast = Math.min(1, stats.stdev / 40);
+    const exposure = stats.mean >= 30 && stats.mean <= 225 ? 1 : 0.3;
+    return stats.entropy * contrast * exposure;
+}
+/** The highest score wins; a tie goes to the earlier beat, since an opening frame is the safer poster. */
+function pickBestScore(scores) {
+    let best = scores[0];
+    for (const s of scores)
+        if (s.score > best.score)
+            best = s;
+    return best.beatId;
+}
+async function frameStats(file) {
+    const st = await (0, sharp_1.default)(file).greyscale().stats();
+    return { mean: st.channels[0].mean, stdev: st.channels[0].stdev, entropy: st.entropy };
+}
+// ---------------------------------------------------------------------------------------
+// Share: an export with a hard size cap
+// ---------------------------------------------------------------------------------------
+/** Rungs tried from the top, each no taller than the source. */
+const SHARE_HEIGHTS = [1080, 720, 540, 480, 360, 240];
+/** Bits per pixel per frame below which x264 starts to block and smear. Screen content is forgiving; this is not generous. */
+const SHARE_MIN_BPP = 0.05;
+/** Share of the cap the plan aims for, leaving room for container overhead and rate control that overshoots. */
+const SHARE_BUDGET = 0.92;
+/**
+ * Turns a size cap into an encode: the bitrate that fits (cap, minus the audio, over the
+ * duration) and the largest resolution that bitrate can still carry without blocking. A fixed
+ * preset cannot do this; it either blows a short clip's budget on nothing or starves a long
+ * one. Pure, so the arithmetic is testable without encoding anything.
+ */
+function planShareEncode(opts) {
+    const audioKbps = opts.hasAudio ? (opts.audioKbps ?? 96) : 0;
+    const totalKbps = (opts.maxBytes * SHARE_BUDGET * 8) / 1000 / opts.durationSec;
+    const videoKbps = Math.max(50, Math.floor((totalKbps - audioKbps) * (opts.bitrateScale ?? 1)));
+    const fps = Math.min(opts.fps, 30);
+    const rungs = SHARE_HEIGHTS.filter((h) => h <= opts.srcHeight);
+    if (rungs.length === 0)
+        rungs.push(opts.srcHeight);
+    const dims = (h) => ({ w: Math.max(2, Math.round((opts.srcWidth * h) / opts.srcHeight / 2) * 2), h: h - (h % 2) });
+    let chosen = dims(rungs[rungs.length - 1]);
+    let tight = true;
+    for (const h of rungs) {
+        const d = dims(h);
+        if ((videoKbps * 1000) / (d.w * d.h * fps) >= SHARE_MIN_BPP) {
+            chosen = d;
+            tight = false;
+            break;
+        }
+    }
+    return { width: chosen.w, height: chosen.h, videoKbps, audioKbps, fps, tight };
+}
+function buildSharePassArgs(opts) {
+    const { plan, pass } = opts;
+    const video = [
+        "-vf",
+        `scale=${plan.width}:${plan.height}:flags=lanczos,fps=${plan.fps}`,
+        "-c:v",
+        "libx264",
+        "-preset",
+        "medium",
+        "-pix_fmt",
+        "yuv420p",
+        "-b:v",
+        `${plan.videoKbps}k`,
+        // A ceiling just above the target and a buffer of two seconds keep rate control from
+        // spiking on a scene cut and pushing the file past a cap that the average alone would meet.
+        "-maxrate",
+        `${Math.round(plan.videoKbps * 1.25)}k`,
+        "-bufsize",
+        `${plan.videoKbps * 2}k`,
+        "-pass",
+        String(pass),
+        "-passlogfile",
+        opts.passLog,
+    ];
+    if (pass === 1)
+        return ["-nostdin", "-y", "-i", opts.inPath, ...video, "-an", "-f", "null", "-"];
+    return [
+        "-nostdin",
+        "-y",
+        "-i",
+        opts.inPath,
+        ...video,
+        ...(opts.hasAudio ? ["-c:a", "aac", "-b:a", `${plan.audioKbps}k`, "-ar", "48000"] : ["-an"]),
+        "-movflags",
+        "+faststart",
+        opts.outPath,
+    ];
+}
+async function probeMedia(inPath, cwd) {
+    const r = await (0, util_1.spawnCapture)("ffprobe", ["-v", "error", "-show_entries", "stream=codec_type,width,height,r_frame_rate:format=duration", "-of", "json", inPath], cwd);
+    if (r.code !== 0)
+        throw new Error(`ffprobe failed on ${inPath}:\n${r.stderr.slice(-600)}`);
+    const doc = JSON.parse(r.stdout);
+    const video = doc.streams?.find((st) => st.codec_type === "video");
+    if (!video?.width || !video.height)
+        throw new Error(`${inPath} has no video stream.`);
+    const [num, den] = (video.r_frame_rate ?? "30/1").split("/").map(Number);
+    const durationSec = Number.parseFloat(doc.format?.duration ?? "");
+    if (!Number.isFinite(durationSec) || durationSec <= 0)
+        throw new Error(`${inPath} has no usable duration.`);
+    return {
+        width: video.width,
+        height: video.height,
+        fps: den ? num / den : 30,
+        durationSec,
+        hasAudio: doc.streams?.some((st) => st.codec_type === "audio") ?? false,
+    };
+}
+async function exportShare(opts) {
+    const { projectRoot, inPathRel, outRel, notes } = opts;
+    const maxBytes = Math.round(opts.maxMB * 1000000);
+    const probe = await probeMedia(inPathRel, projectRoot);
+    fs.mkdirSync(path.dirname(path.join(projectRoot, outRel)), { recursive: true });
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-share-"));
+    try {
+        const passLog = path.join(work, "pass");
+        let scale = 1;
+        let plan = planShareEncode({ maxBytes, durationSec: probe.durationSec, srcWidth: probe.width, srcHeight: probe.height, fps: probe.fps, hasAudio: probe.hasAudio, audioKbps: opts.audioKbps });
+        if (plan.tight) {
+            notes.push(`${opts.maxMB}MB is tight for ${probe.durationSec.toFixed(0)}s of video: even ${plan.width}x${plan.height} gets ` +
+                `only ${plan.videoKbps}kbps, so expect visible blocking. Raise maxMB or export a shorter cut.`);
+        }
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            plan = planShareEncode({ maxBytes, durationSec: probe.durationSec, srcWidth: probe.width, srcHeight: probe.height, fps: probe.fps, hasAudio: probe.hasAudio, audioKbps: opts.audioKbps, bitrateScale: scale });
+            for (const pass of [1, 2]) {
+                const args = buildSharePassArgs({ inPath: inPathRel, outPath: outRel, plan, pass, passLog, hasAudio: probe.hasAudio });
+                const r = await (0, util_1.spawnCapture)("ffmpeg", args, projectRoot);
+                if (r.code !== 0)
+                    throw new Error(`share encode pass ${pass} failed:\n${r.stderr.slice(-1200)}`);
+            }
+            const bytes = fs.statSync(path.join(projectRoot, outRel)).size;
+            if (bytes <= maxBytes) {
+                notes.push(`${(bytes / 1000000).toFixed(2)}MB, under the ${opts.maxMB}MB cap, at ${plan.width}x${plan.height}.`);
+                return { path: outRel, bytes, maxBytes, withinCap: true, width: plan.width, height: plan.height, videoKbps: plan.videoKbps, audioKbps: plan.audioKbps, attempts: attempt };
+            }
+            // Over the cap: aim for 3% under it from the size this attempt actually produced.
+            scale *= (maxBytes * 0.97) / bytes;
+        }
+        const bytes = fs.statSync(path.join(projectRoot, outRel)).size;
+        notes.push(`Still ${(bytes / 1000000).toFixed(2)}MB after 3 attempts, over the ${opts.maxMB}MB cap. Raise maxMB or export a shorter cut.`);
+        return { path: outRel, bytes, maxBytes, withinCap: false, width: plan.width, height: plan.height, videoKbps: plan.videoKbps, audioKbps: plan.audioKbps, attempts: 3 };
+    }
+    finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+}
+// ---------------------------------------------------------------------------------------
+// Reels: a native 9:16 render, packaged for upload
+// ---------------------------------------------------------------------------------------
+/** The Reels frame: 1080x1920, 30fps, H.264 in yuv420p, AAC audio, moov atom first. */
+const REELS = { width: 1080, height: 1920, fps: 30 };
+/** How far a source's aspect ratio may sit from 9:16 before it is not a vertical render at all. */
+const REELS_ASPECT_TOLERANCE = 0.01;
+/**
+ * Decides what a source needs to become a Reels file, and nothing more. A 9:16 source that is
+ * already 1080x1920 H.264 yuv420p at 30fps keeps its video stream byte for byte, and AAC audio is
+ * copied too; only the container is rewritten so the moov atom leads. A source that is not 9:16 is
+ * refused: turning a 16:9 render into a vertical one means cropping or letterboxing it, which
+ * cuts diagrams off or shrinks them to a strip, and that is a choice for reformat_vertical or a
+ * native render, not something an export step should make silently. Pure, so the rules are
+ * testable without encoding anything.
+ */
+function planReelsExport(src) {
+    const aspect = src.width / src.height;
+    const target = REELS.width / REELS.height;
+    if (Math.abs(aspect - target) / target > REELS_ASPECT_TOLERANCE) {
+        return {
+            ok: false,
+            reason: `The source is ${src.width}x${src.height}, not 9:16. A reels export never crops or letterboxes a frame ` +
+                `silently. For a finished 16:9 render, use reformat_vertical (it crops per beat from the manifest, and a ` +
+                `crop can cut a diagram off). For a lesson with diagrams, render natively vertical instead: init_project ` +
+                `with videoConfig { width: 1080, height: 1920 }, then render and export that. PIPELINE.md, "Native ` +
+                `vertical (9:16)", says when to use which.`,
+        };
+    }
+    const scale = src.width !== REELS.width || src.height !== REELS.height;
+    const retime = Math.abs(src.fps - REELS.fps) > 0.01;
+    const videoReencode = scale || retime || src.videoCodec !== "h264" || src.pixFmt !== "yuv420p";
+    const audioReencode = src.audioCodec !== null && src.audioCodec !== "aac";
+    return { ok: true, videoReencode, audioReencode, scale, retime };
+}
+function buildReelsArgs(opts) {
+    const { plan } = opts;
+    const args = ["-nostdin", "-y", "-i", opts.inPath, "-map", "0:v:0"];
+    if (opts.hasAudio)
+        args.push("-map", "0:a:0");
+    if (plan.videoReencode) {
+        const filters = [
+            ...(plan.scale ? [`scale=${REELS.width}:${REELS.height}:flags=lanczos`, "setsar=1"] : []),
+            ...(plan.retime ? [`fps=${REELS.fps}`] : []),
+        ];
+        // crf 18 is close to visually lossless; Instagram re-encodes on upload, so the file it receives
+        // should be the clean one, not one already compressed hard.
+        args.push(...(filters.length ? ["-vf", filters.join(",")] : []), "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p");
+    }
+    else {
+        args.push("-c:v", "copy");
+    }
+    if (opts.hasAudio) {
+        args.push(...(plan.audioReencode ? ["-c:a", "aac", "-b:a", "128k", "-ar", "48000"] : ["-c:a", "copy"]));
+    }
+    args.push("-movflags", "+faststart", opts.outPath);
+    return args;
+}
+async function probeReelsSource(inPath, cwd) {
+    const r = await (0, util_1.spawnCapture)("ffprobe", ["-v", "error", "-show_streams", "-show_format", "-of", "json", inPath], cwd);
+    if (r.code !== 0)
+        throw new Error(`ffprobe failed on ${inPath}:\n${r.stderr.slice(-600)}`);
+    const doc = JSON.parse(r.stdout);
+    // A baked poster is a second, one-frame video stream; the picture is the first real one.
+    const video = doc.streams?.find((st) => st.codec_type === "video" && !st.disposition?.attached_pic);
+    if (!video?.width || !video.height)
+        throw new Error(`${inPath} has no video stream.`);
+    const [num, den] = (video.r_frame_rate ?? "30/1").split("/").map(Number);
+    const durationSec = Number.parseFloat(doc.format?.duration ?? "");
+    if (!Number.isFinite(durationSec) || durationSec <= 0)
+        throw new Error(`${inPath} has no usable duration.`);
+    return {
+        width: video.width,
+        height: video.height,
+        fps: den ? num / den : 30,
+        videoCodec: video.codec_name ?? "",
+        pixFmt: video.pix_fmt ?? "",
+        audioCodec: doc.streams?.find((st) => st.codec_type === "audio")?.codec_name ?? null,
+        durationSec,
+    };
+}
+async function exportReels(opts) {
+    const { projectRoot, inPathRel, outRel, notes } = opts;
+    const src = await probeReelsSource(inPathRel, projectRoot);
+    const plan = planReelsExport(src);
+    if (!plan.ok)
+        throw new Error(plan.reason);
+    fs.mkdirSync(path.dirname(path.join(projectRoot, outRel)), { recursive: true });
+    const r = await (0, util_1.spawnCapture)("ffmpeg", buildReelsArgs({ inPath: inPathRel, outPath: outRel, plan, hasAudio: src.audioCodec !== null }), projectRoot);
+    if (r.code !== 0)
+        throw new Error(`reels export failed:\n${r.stderr.slice(-1200)}`);
+    // Measured from the file on disk, not assumed from the plan.
+    const out = await probeReelsSource(outRel, projectRoot);
+    const bytes = fs.statSync(path.join(projectRoot, outRel)).size;
+    const video = plan.videoReencode ? "re-encoded (the source was not already 1080x1920 H.264 yuv420p at 30fps)" : "copied unchanged";
+    const audio = src.audioCodec === null
+        ? "no audio in the source and none added"
+        : plan.audioReencode
+            ? `audio ${src.audioCodec} re-encoded to AAC`
+            : "audio AAC copied unchanged";
+    notes.push(`${out.width}x${out.height} at ${out.fps}fps, ${(bytes / 1000000).toFixed(2)}MB. Video ${video}, ${audio}, moov atom first.`);
+    if (src.audioCodec === null) {
+        notes.push("The source has no audio, so the file has none. Reels accept a silent video; add a music bed first if the reel should have sound.");
+    }
+    notes.push('Instagram\'s own interface covers part of the top, bottom and right edge of a reel. PIPELINE.md, "Native vertical (9:16)", lists approximate safe zones.');
+    return {
+        path: outRel,
+        bytes,
+        width: out.width,
+        height: out.height,
+        fps: out.fps,
+        durationSec: out.durationSec,
+        videoCodec: out.videoCodec,
+        audioCodec: out.audioCodec,
+        videoReencoded: plan.videoReencode,
+        audioReencoded: plan.audioReencode,
+    };
+}
+function readBeats(projectRoot, videoName) {
+    const beatsPath = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    if (!fs.existsSync(beatsPath)) {
+        throw new Error(`${beatsPath} does not exist. Every rendition is driven by the manifest.`);
+    }
+    const doc = JSON.parse(fs.readFileSync(beatsPath, "utf8"));
+    if (!Array.isArray(doc.beats) || doc.beats.length === 0)
+        throw new Error(`${beatsPath} has no beats.`);
+    return { fps: doc.fps ?? 30, beats: doc.beats };
+}
+async function runExportRendition(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const { fps, beats } = readBeats(projectRoot, videoName);
+    const inPathRel = input.inPath ?? path.join("output", `${videoName}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, inPathRel, "inPath");
+    if (!fs.existsSync(path.join(projectRoot, inPathRel))) {
+        throw new Error(`${inPathRel} does not exist. Every rendition is cut from the finished render, which is what keeps ` +
+            `them in step with the video. Run render_video first.`);
+    }
+    const notes = [];
+    const files = [];
+    if (input.format === "gif") {
+        const outRel = input.outPath ?? path.join("output", `${videoName}.gif`);
+        (0, util_1.sanitizeRelativeOutPath)(projectRoot, outRel, "outPath");
+        fs.mkdirSync(path.dirname(path.join(projectRoot, outRel)), { recursive: true });
+        const gifFps = input.fps ?? 12;
+        const gifWidth = input.width ?? 720;
+        // Beside the gif, not in a fixed directory: the palette is an intermediate and it gets
+        // deleted, but if a run dies between the two passes the leftover should be findable.
+        const paletteRel = path.join(path.dirname(outRel), `${videoName}-palette.png`);
+        const palette = await (0, util_1.spawnCapture)("ffmpeg", buildPaletteArgs(inPathRel, paletteRel, gifFps, gifWidth), projectRoot);
+        if (palette.code !== 0)
+            throw new Error(`palettegen failed:\n${palette.stderr.slice(-1200)}`);
+        const gif = await (0, util_1.spawnCapture)("ffmpeg", buildGifArgs(inPathRel, paletteRel, outRel, gifFps, gifWidth), projectRoot);
+        if (gif.code !== 0)
+            throw new Error(`GIF encode failed:\n${gif.stderr.slice(-1200)}`);
+        fs.rmSync(path.join(projectRoot, paletteRel), { force: true });
+        const bytes = fs.statSync(path.join(projectRoot, outRel)).size;
+        files.push(outRel);
+        notes.push(`${(bytes / 1000000).toFixed(2)}MB at ${gifWidth}px wide and ${gifFps}fps.`);
+        if (bytes > 10000000) {
+            notes.push("GitHub will render this but it is large for a README. Drop the width or the fps, or export a " +
+                "shorter cut, before committing it.");
+        }
+        return { format: "gif", files, notes };
+    }
+    if (input.format === "screenshots") {
+        const dirRel = input.outDir ?? path.join("docs", "screenshots", videoName);
+        (0, util_1.sanitizeRelativeOutPath)(projectRoot, dirRel, "outDir");
+        fs.mkdirSync(path.join(projectRoot, dirRel), { recursive: true });
+        const entries = [];
+        for (const [i, beat] of beats.entries()) {
+            const name = `${String(i + 1).padStart(2, "0")}-${beat.id}.png`;
+            const rel = path.join(dirRel, name);
+            const shot = await (0, util_1.spawnCapture)("ffmpeg", buildFrameArgs(inPathRel, beatMidpointSeconds(beat, fps), rel), projectRoot);
+            if (shot.code !== 0)
+                throw new Error(`frame extraction failed for beat "${beat.id}":\n${shot.stderr.slice(-800)}`);
+            files.push(rel);
+            entries.push({ file: name, beat });
+        }
+        const indexRel = path.join(dirRel, "README.md");
+        fs.writeFileSync(path.join(projectRoot, indexRel), buildScreenshotIndex(videoName, entries), "utf8");
+        notes.push("These are frames of the video itself, so they cannot drift from it. Re-export after a re-render " +
+            "rather than editing them.");
+        return { format: "screenshots", files, indexPath: indexRel, notes };
+    }
+    if (input.format === "poster") {
+        let atSeconds;
+        let pickInfo;
+        if (typeof input.posterAt === "number") {
+            atSeconds = input.posterAt;
+        }
+        else if (!input.posterBeatId && input.posterPick !== "last") {
+            // Score every beat's midpoint frame and take the best. Frames go to a temp dir: they are
+            // an intermediate, and the winner is re-extracted below like any other poster.
+            const work = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-poster-"));
+            try {
+                const scores = [];
+                for (const beat of beats) {
+                    const probeFile = path.join(work, `${beat.id}.png`);
+                    const r = await (0, util_1.spawnCapture)("ffmpeg", buildFrameArgs(inPathRel, beatMidpointSeconds(beat, fps), probeFile), projectRoot);
+                    if (r.code !== 0 || !fs.existsSync(probeFile))
+                        throw new Error(`poster scoring: frame extraction failed for beat "${beat.id}":\n${r.stderr.slice(-600)}`);
+                    scores.push({ beatId: beat.id, score: Number(scoreFrameStats(await frameStats(probeFile)).toFixed(3)) });
+                }
+                const winner = beats.find((b) => b.id === pickBestScore(scores));
+                atSeconds = beatMidpointSeconds(winner, fps);
+                pickInfo = { beatId: winner.id, seconds: atSeconds, scores };
+                notes.push(`posterPick auto chose beat "${winner.id}" (score ${scores.find((x) => x.beatId === winner.id).score}).`);
+            }
+            finally {
+                fs.rmSync(work, { recursive: true, force: true });
+            }
+        }
+        else {
+            const beatId = input.posterBeatId ?? beats[beats.length - 1].id;
+            const beat = beats.find((b) => b.id === beatId);
+            if (!beat)
+                throw new Error(`No beat "${beatId}" in this video's manifest.`);
+            atSeconds = beatMidpointSeconds(beat, fps);
+        }
+        const posterRel = input.outPath ?? path.join("output", `${videoName}-poster.jpg`);
+        (0, util_1.sanitizeRelativeOutPath)(projectRoot, posterRel, "outPath");
+        fs.mkdirSync(path.dirname(path.join(projectRoot, posterRel)), { recursive: true });
+        const frame = await (0, util_1.spawnCapture)("ffmpeg", buildFrameArgs(inPathRel, atSeconds, posterRel), projectRoot);
+        if (frame.code !== 0)
+            throw new Error(`poster frame extraction failed:\n${frame.stderr.slice(-800)}`);
+        files.push(posterRel);
+        notes.push(`Poster taken at ${atSeconds.toFixed(2)}s.`);
+        let bakedPath;
+        if (input.bake !== false) {
+            const bakedRel = path.join(path.dirname(inPathRel), `${videoName}-poster.mp4`);
+            const bake = await (0, util_1.spawnCapture)("ffmpeg", buildAttachPosterArgs(inPathRel, posterRel, bakedRel), projectRoot);
+            if (bake.code !== 0)
+                throw new Error(`baking the poster into the video failed:\n${bake.stderr.slice(-800)}`);
+            files.push(bakedRel);
+            bakedPath = bakedRel;
+            notes.push(`${bakedRel} is the same render with the poster baked in as its embedded thumbnail, video and ` +
+                `audio copied unchanged. Swap it in for ${inPathRel} once you are happy with the frame.`);
+        }
+        return { format: "poster", files, notes, ...(bakedPath ? { bakedPath } : {}), ...(pickInfo ? { posterPick: pickInfo } : {}) };
+    }
+    if (input.format === "share") {
+        const outRel = input.outPath ?? path.join(path.dirname(inPathRel), `${videoName}-share.mp4`);
+        (0, util_1.sanitizeRelativeOutPath)(projectRoot, outRel, "outPath");
+        if (path.resolve(projectRoot, outRel) === path.resolve(projectRoot, inPathRel)) {
+            throw new Error("outPath is the same file as the input render. Pick a different outPath.");
+        }
+        const maxMB = input.maxMB ?? 10;
+        if (!(maxMB > 0))
+            throw new Error("maxMB must be a positive number.");
+        const share = await exportShare({ projectRoot, inPathRel, outRel, maxMB, audioKbps: input.audioKbps, notes });
+        files.push(outRel);
+        return { format: "share", files, notes, share };
+    }
+    if (input.format === "reels") {
+        const outRel = input.outPath ?? path.join(path.dirname(inPathRel), `${videoName}-reels.mp4`);
+        (0, util_1.sanitizeRelativeOutPath)(projectRoot, outRel, "outPath");
+        if (path.resolve(projectRoot, outRel) === path.resolve(projectRoot, inPathRel)) {
+            throw new Error("outPath is the same file as the input render. Pick a different outPath.");
+        }
+        const reels = await exportReels({ projectRoot, inPathRel, outRel, notes });
+        files.push(outRel);
+        return { format: "reels", files, notes, reels };
+    }
+    if (input.format !== "store-frames") {
+        throw new Error(`Unknown format "${String(input.format)}". Known: gif, screenshots, store-frames, poster, share, reels.`);
+    }
+    const deviceKey = input.device ?? "iphone-6.9";
+    const device = exports.STORE_DEVICES[deviceKey];
+    if (!device)
+        throw new Error(`Unknown device "${deviceKey}". Known: ${Object.keys(exports.STORE_DEVICES).join(", ")}.`);
+    const dirRel = input.outDir ?? path.join("output", "store", deviceKey);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, dirRel, "outDir");
+    fs.mkdirSync(path.join(projectRoot, dirRel), { recursive: true });
+    const wanted = input.beatIds?.length ? beats.filter((b) => input.beatIds.includes(b.id)) : beats;
+    if (wanted.length === 0)
+        throw new Error(`None of the requested beatIds exist in this video's manifest.`);
+    const bezel = Math.round(device.width * 0.03);
+    for (const [i, beat] of wanted.entries()) {
+        const rel = path.join(dirRel, `${String(i + 1).padStart(2, "0")}-${beat.id}.png`);
+        const shot = await (0, util_1.spawnCapture)("ffmpeg", buildStoreFrameArgs(inPathRel, beatMidpointSeconds(beat, fps), rel, device, bezel), projectRoot);
+        if (shot.code !== 0)
+            throw new Error(`store frame failed for beat "${beat.id}":\n${shot.stderr.slice(-800)}`);
+        files.push(rel);
+    }
+    notes.push(`${device.label}: exactly ${device.width}x${device.height}, which is the dimension the review process ` +
+        `rejects a submission over.`);
+    notes.push("The shot is fitted inside the canvas rather than filling it. Filling would crop away the UI the " +
+        "screenshot exists to show.");
+    return { format: "store-frames", files, notes };
+}
+function registerExportRendition(server) {
+    server.registerTool("export_rendition", {
+        title: "Export the same beats as a GIF, a docs screenshot set, or store frames",
+        description: "Video is one consumer of the capture engine and the manifest, not the only one. This renders the " +
+            "same finished video into the other artefacts a project actually needs. format: \"gif\" produces a " +
+            "README GIF through a real two-pass palette (a one-pass GIF falls back to a fixed 256 colour palette " +
+            "and bands flat UI into mud, which is why most README GIFs look the way they do), defaulting to 720px " +
+            "at 12fps and warning when the result is too large to commit. format: \"screenshots\" pulls one frame " +
+            "per beat at its midpoint into docs/screenshots/<videoName>/ and writes a README.md pairing each shot " +
+            "with that beat's narration, so the docs images are frames of the same footage the video shows and " +
+            "cannot drift from it. format: \"store-frames\" produces App Store and Play Store images at the exact " +
+            "pixel dimensions each store demands (6.9 and 6.5 inch iPhone, 13 inch iPad, Play Store phone and " +
+            "tablet), fitting the shot inside the canvas rather than filling it, because filling crops away the " +
+            "UI the screenshot exists to show. format: \"poster\" picks one frame (a beat's midpoint, or an exact " +
+            "posterAt timestamp) and writes it as <videoName>-poster.jpg, then, unless bake is set to false, also " +
+            "writes <videoName>-poster.mp4: the same render with that frame baked in as the file's embedded " +
+            "thumbnail (an attached_pic stream, the same mechanism a podcast mp3's cover art uses), copied not " +
+            "re-encoded, so video and audio quality are untouched. Skipping this step is why a shared video's idle " +
+            "thumbnail is so often a black frame or a mid-motion blur instead of the frame that was actually chosen " +
+            "to represent it. By default the frame is chosen by scoring every beat's midpoint (luma entropy and " +
+            "contrast, penalising near-black and blown-out frames), posterPick: \"last\" reverts to always taking " +
+            "the last beat's midpoint instead. format: \"share\" encodes a copy under a hard size cap " +
+            "(maxMB, default 10): the bitrate is computed from the cap and the duration, the largest resolution " +
+            "that bitrate can carry is chosen, it is encoded two-pass H.264 with +faststart, and the file on disk " +
+            "is measured and re-encoded smaller if it came out over the cap. format: \"reels\" packages a render " +
+            "that is already native 9:16 (init_project videoConfig 1080x1920) as an Instagram Reels file: 1080x1920 " +
+            "H.264 + AAC at 30fps with the moov atom first, re-encoding only what the source is not already (a " +
+            "1080x1920 H.264 AAC 30fps source keeps its streams byte for byte; a 60fps one, or an mp3 track, is " +
+            "converted, and a smaller 9:16 one is scaled). It refuses a 16:9 render instead of cropping it, and " +
+            "points at reformat_vertical or a native render, since a crop can cut a diagram off. All six formats " +
+            "read the finished render plus beats.json rather than re-capturing, so run render_video first.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            format: zod_1.z.enum(["gif", "screenshots", "store-frames", "poster", "share", "reels"]),
+            inPath: zod_1.z.string().optional().describe("The finished render. Defaults to output/<videoName>.mp4."),
+            outDir: zod_1.z.string().optional(),
+            outPath: zod_1.z.string().optional().describe("gif, poster, share and reels. Reels defaults to output/<videoName>-reels.mp4."),
+            fps: zod_1.z.number().int().positive().optional().describe("gif only. Defaults to 12."),
+            width: zod_1.z.number().int().positive().optional().describe("gif only. Defaults to 720."),
+            device: zod_1.z
+                .enum(["iphone-6.9", "iphone-6.5", "ipad-13", "android-phone", "android-tablet"])
+                .optional()
+                .describe("store-frames only. Defaults to iphone-6.9."),
+            beatIds: zod_1.z.array(zod_1.z.string()).optional().describe("store-frames only. Defaults to every beat."),
+            posterBeatId: zod_1.z.string().optional().describe("poster only. An exact beat to use instead of letting posterPick choose."),
+            posterAt: zod_1.z.number().optional().describe("poster only. Exact seconds, overriding posterBeatId."),
+            bake: zod_1.z.boolean().optional().describe("poster only. Defaults to true."),
+            posterPick: zod_1.z
+                .enum(["last", "auto"])
+                .optional()
+                .describe('poster only. "auto" (default) scores every beat\'s midpoint and takes the most representative frame; "last" always takes the last beat\'s midpoint instead.'),
+            maxMB: zod_1.z.number().positive().optional().describe("share only. Size cap in megabytes (1MB = 1,000,000 bytes). Defaults to 10."),
+            audioKbps: zod_1.z.number().int().positive().optional().describe("share only. Defaults to 96."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("export_rendition", () => runExportRendition(input)));
+}