@openvidstudio/mcp-server 0.1.0

package/dist/tools/captureScreenRecording.js

@@ -0,0 +1,181 @@
+"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.buildFfmpegTranscodeArgs = buildFfmpegTranscodeArgs;
+exports.buildFfprobeDurationArgs = buildFfprobeDurationArgs;
+exports.runCaptureScreenRecording = runCaptureScreenRecording;
+exports.registerCaptureScreenRecording = registerCaptureScreenRecording;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const capture_1 = require("../capture");
+const mcp_1 = require("./mcp");
+/**
+ * Pure argv builder, unit-testable without spawning ffmpeg. Remotion's
+ * OffthreadVideo needs a seekable format, so Playwright's webm output gets
+ * transcoded to mp4 (h264/yuv420p, +faststart) -- same spawn/argv-array
+ * discipline as render_video/qc_extract_frames.
+ */
+function buildFfmpegTranscodeArgs(inputPath, outputPath) {
+    return ["-nostdin", "-i", inputPath, "-c:v", "libx264", "-pix_fmt", "yuv420p", "-movflags", "+faststart", outputPath, "-y"];
+}
+/** Pure argv builder for the best-effort ffprobe duration lookup. */
+function buildFfprobeDurationArgs(filePath) {
+    return ["-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", filePath];
+}
+/**
+ * Best-effort duration via ffprobe. Not a new dependency (ffprobe ships
+ * alongside the ffmpeg this tool already requires for the transcode); if it's
+ * missing or fails, this silently returns undefined rather than failing the
+ * whole capture over a nice-to-have field.
+ */
+async function probeDurationMs(filePath, cwd) {
+    try {
+        const result = await (0, util_1.spawnCapture)("ffprobe", buildFfprobeDurationArgs(filePath), cwd);
+        if (result.code !== 0)
+            return undefined;
+        const seconds = Number.parseFloat(result.stdout.trim());
+        return Number.isFinite(seconds) ? Math.round(seconds * 1000) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function runCaptureScreenRecording(input) {
+    const beatId = (0, util_1.sanitizeSegment)(input.beatId, "beatId");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const target = input.viewport ?? capture_1.DEFAULT_VIEWPORT;
+    const outPathRel = input.outPath ?? path.join("public", "video", `${beatId}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
+    const outPathAbs = path.join(projectRoot, outPathRel);
+    const browser = await (0, capture_1.launchChromium)();
+    try {
+        // Phase 1: a throwaway context/page to detect+compensate zoom (steps 1-2 of
+        // CAPTURE.md, via the shared helper). Playwright's recordVideo.size can only be set
+        // at context creation, before any page exists, so the compensated size has to be
+        // known before the real recording context is opened -- this probe pass is what
+        // makes that possible without guessing.
+        const probeContext = await browser.newContext();
+        let zoom;
+        let compensatedViewport;
+        try {
+            const probePage = await probeContext.newPage();
+            await probePage.setViewportSize(target);
+            await probePage.goto(input.url, { waitUntil: "load" });
+            const compensation = await (0, capture_1.detectAndCompensateZoom)(probePage, target);
+            zoom = compensation.zoom;
+            compensatedViewport = compensation.viewport;
+        }
+        finally {
+            await probeContext.close();
+        }
+        // Phase 2: the real recording context, sized at the compensated (not originally
+        // requested) viewport -- same reasoning as capture_screenshot.
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-capture-"));
+        let webmPath;
+        try {
+            const recordContext = await browser.newContext({
+                viewport: compensatedViewport,
+                recordVideo: { dir: tmpDir, size: compensatedViewport },
+            });
+            try {
+                const page = await recordContext.newPage();
+                await page.goto(input.url, { waitUntil: "load" });
+                await (0, capture_1.replayInteractions)(page, input.interactions);
+                const video = page.video();
+                if (!video) {
+                    throw new Error("Playwright did not attach a Video to this page -- recordVideo may not be active.");
+                }
+                // Closing the context is what flushes the recorded video to disk; it doesn't
+                // exist as a real file before this.
+                await recordContext.close();
+                webmPath = await video.path();
+            }
+            catch (err) {
+                await recordContext.close().catch(() => { });
+                throw err;
+            }
+            fs.mkdirSync(path.dirname(outPathAbs), { recursive: true });
+            const transcodeResult = await (0, util_1.spawnCapture)("ffmpeg", buildFfmpegTranscodeArgs(webmPath, outPathAbs), projectRoot);
+            if (transcodeResult.code !== 0) {
+                throw new Error(`ffmpeg webm->mp4 transcode failed (exit ${transcodeResult.code}): ${transcodeResult.stderr.slice(-1000)}`);
+            }
+            const durationMs = await probeDurationMs(outPathAbs, projectRoot);
+            return {
+                outPath: outPathAbs,
+                width: compensatedViewport.width,
+                height: compensatedViewport.height,
+                zoom,
+                ...(durationMs !== undefined ? { durationMs } : {}),
+            };
+        }
+        finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    }
+    finally {
+        await browser.close();
+    }
+}
+function registerCaptureScreenRecording(server) {
+    server.registerTool("capture_screen_recording", {
+        title: "Capture a zoom-compensated, full-viewport screen recording",
+        description: "Internalizes CAPTURE.md's recording protocol as one atomic call, driving a real headless Chromium " +
+            "directly via the `playwright` package (not a separate Playwright MCP server). Runs the same " +
+            "zoom-desync detection/compensation as capture_screenshot on a throwaway probe page first (Playwright's " +
+            "recordVideo.size can only be set when the context is created, so the compensated size must be known " +
+            "before recording starts), then opens the real recording context at that compensated size, navigates, " +
+            "and replays `interactions` in array order. v1 scope is fixed full-viewport recordings only -- no " +
+            "post-hoc DOM-rect cropping of a moving recording, that's future work. Closing the context flushes " +
+            "Playwright's webm to disk, which is then transcoded to mp4 via ffmpeg (spawn, argv array, same " +
+            "discipline as render_video/qc_extract_frames) since Remotion's OffthreadVideo needs a seekable " +
+            "format; the intermediate webm and temp recording dir are cleaned up after. Default outPath is " +
+            "public/video/<beatId>.mp4 under projectRoot, matching scaffold_scene's real-recording convention. " +
+            "Returns { outPath, width, height, zoom, durationMs? } -- durationMs is a best-effort ffprobe lookup, " +
+            "omitted (not failed) if ffprobe isn't available. Requires Chromium to be installed for Playwright " +
+            "first: run \"npx playwright install chromium\" once wherever this package is installed; a missing " +
+            "browser fails with a message telling you to do exactly that, not a cryptic native error.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            beatId: zod_1.z.string().min(1),
+            url: zod_1.z.string().min(1),
+            viewport: capture_1.viewportSchema.optional(),
+            interactions: zod_1.z.array(capture_1.interactionSchema).optional(),
+            outPath: zod_1.z.string().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("capture_screen_recording", () => runCaptureScreenRecording(input)));
+}

package/dist/tools/captureScreenshot.d.ts

@@ -0,0 +1,34 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Interaction, type Viewport } from "../capture";
+export interface CaptureScreenshotInput {
+    projectRoot?: string;
+    beatId: string;
+    url: string;
+    viewport?: Viewport;
+    interactions?: Interaction[];
+    cropSelector?: string;
+    outPath?: string;
+}
+export interface CaptureScreenshotResult {
+    outPath: string;
+    width: number;
+    height: number;
+    zoom: number;
+}
+export interface CropRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Port of `vidstudio/scripts/crop-shot.py` (see CAPTURE.md step 6): crops the
+ * physical screenshot at `rect * zoom`, then upscales the crop back to
+ * `rect`'s own (w, h) with Lanczos resampling, landing on a pixel-accurate,
+ * unshrunk capture. Pure function of the screenshot buffer, the DOM rect
+ * measured in effective CSS space, and the zoom ratio -- no I/O, unit-testable
+ * without a real browser.
+ */
+export declare function cropAndUpscale(screenshotBuffer: Buffer, rect: CropRect, zoom: number): Promise<Buffer>;
+export declare function runCaptureScreenshot(input: CaptureScreenshotInput): Promise<CaptureScreenshotResult>;
+export declare function registerCaptureScreenshot(server: McpServer): void;

package/dist/tools/captureScreenshot.js

@@ -0,0 +1,148 @@
+"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.cropAndUpscale = cropAndUpscale;
+exports.runCaptureScreenshot = runCaptureScreenshot;
+exports.registerCaptureScreenshot = registerCaptureScreenshot;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const sharp_1 = __importDefault(require("sharp"));
+const util_1 = require("../util");
+const capture_1 = require("../capture");
+const mcp_1 = require("./mcp");
+/**
+ * Port of `vidstudio/scripts/crop-shot.py` (see CAPTURE.md step 6): crops the
+ * physical screenshot at `rect * zoom`, then upscales the crop back to
+ * `rect`'s own (w, h) with Lanczos resampling, landing on a pixel-accurate,
+ * unshrunk capture. Pure function of the screenshot buffer, the DOM rect
+ * measured in effective CSS space, and the zoom ratio -- no I/O, unit-testable
+ * without a real browser.
+ */
+async function cropAndUpscale(screenshotBuffer, rect, zoom) {
+    const left = Math.round(rect.x * zoom);
+    const top = Math.round(rect.y * zoom);
+    const right = Math.round((rect.x + rect.width) * zoom);
+    const bottom = Math.round((rect.y + rect.height) * zoom);
+    const finalWidth = Math.round(rect.width);
+    const finalHeight = Math.round(rect.height);
+    return (0, sharp_1.default)(screenshotBuffer)
+        .extract({ left, top, width: right - left, height: bottom - top })
+        .resize(finalWidth, finalHeight, { kernel: sharp_1.default.kernel.lanczos3 })
+        .png()
+        .toBuffer();
+}
+async function runCaptureScreenshot(input) {
+    const beatId = (0, util_1.sanitizeSegment)(input.beatId, "beatId");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const target = input.viewport ?? capture_1.DEFAULT_VIEWPORT;
+    const outPathRel = input.outPath ?? path.join("public", "images", `${beatId}.png`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
+    const outPathAbs = path.join(projectRoot, outPathRel);
+    const browser = await (0, capture_1.launchChromium)();
+    try {
+        const context = await browser.newContext();
+        try {
+            const page = await context.newPage();
+            await page.setViewportSize(target);
+            // "load" (not "networkidle"): CAPTURE.md's protocol is resize -> navigate -> measure,
+            // and this package targets arbitrary dev-server pages, some of which poll/keep a
+            // websocket open and would never hit networkidle at all.
+            await page.goto(input.url, { waitUntil: "load" });
+            const { zoom, viewport: compensatedViewport } = await (0, capture_1.detectAndCompensateZoom)(page, target);
+            await (0, capture_1.replayInteractions)(page, input.interactions);
+            // Full-viewport screenshot, no fullPage, no element target: CAPTURE.md explains why
+            // element-scoped locator().screenshot() is wrong (it re-measures/auto-scrolls at shot
+            // time, independent of what was measured a moment earlier). Buffered in memory; only
+            // written to disk after an optional crop below.
+            const screenshotBuffer = await page.screenshot({ scale: "css" });
+            let finalBuffer;
+            if (input.cropSelector) {
+                const rect = await page.$eval(input.cropSelector, (el) => {
+                    const r = el.getBoundingClientRect();
+                    return { x: r.x, y: r.y, width: r.width, height: r.height };
+                });
+                finalBuffer = await cropAndUpscale(screenshotBuffer, rect, zoom);
+            }
+            else {
+                finalBuffer = screenshotBuffer;
+            }
+            const meta = await (0, sharp_1.default)(finalBuffer).metadata();
+            const width = meta.width ?? compensatedViewport.width;
+            const height = meta.height ?? compensatedViewport.height;
+            fs.mkdirSync(path.dirname(outPathAbs), { recursive: true });
+            fs.writeFileSync(outPathAbs, finalBuffer);
+            return { outPath: outPathAbs, width, height, zoom };
+        }
+        finally {
+            await context.close();
+        }
+    }
+    finally {
+        await browser.close();
+    }
+}
+function registerCaptureScreenshot(server) {
+    server.registerTool("capture_screenshot", {
+        title: "Capture a zoom-compensated, DOM-rect-cropped screenshot",
+        description: "Internalizes CAPTURE.md's full screenshot protocol as one atomic call, driving a real headless " +
+            "Chromium directly via the `playwright` package (not a separate Playwright MCP server): navigate, " +
+            "measure window.innerWidth/innerHeight against the requested viewport to detect a per-origin zoom " +
+            "desync (never hardcoded, measured live every call), re-request a compensated viewport and re-verify " +
+            "once if needed (a real 'protocol didn't converge' case fails with a structured error rather than " +
+            "proceeding with a wrong crop), replay `interactions` in array order, take a full-viewport screenshot " +
+            "(scale: css, no fullPage, no element target -- see CAPTURE.md for why element-scoped screenshots " +
+            "bleed in neighboring content), then if `cropSelector` is given, measure its DOM rect and run a " +
+            "TypeScript/sharp port of vidstudio/scripts/crop-shot.py (crop at rect*zoom, upscale back to rect's " +
+            "own size with Lanczos) so the result is pixel-accurate with no bleed. Default outPath is " +
+            "public/images/<beatId>.png under projectRoot, matching scaffold_scene's real-screenshot convention. " +
+            "Returns { outPath, width, height, zoom } -- the saved image's actual pixel dimensions and the " +
+            "measured zoom ratio, for STYLE.md's frame-sizing formula. Requires Chromium to be installed for " +
+            "Playwright first: run \"npx playwright install chromium\" once wherever this package is installed; " +
+            "a missing browser fails with a message telling you to do exactly that, not a cryptic native error.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            beatId: zod_1.z.string().min(1),
+            url: zod_1.z.string().min(1),
+            viewport: capture_1.viewportSchema.optional(),
+            interactions: zod_1.z.array(capture_1.interactionSchema).optional(),
+            cropSelector: zod_1.z.string().optional(),
+            outPath: zod_1.z.string().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("capture_screenshot", () => runCaptureScreenshot(input)));
+}

package/dist/tools/contactSheet.d.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * A 5 minute video is 9000 frames and takes tens of minutes to render, which is a
+ * brutal loop for checking whether the framing is right. Getting it wrong on three
+ * scenes meant rendering stills one at a time and tiling them by hand, which is what
+ * this automates.
+ *
+ * Two frames per beat, midpoint and end. The end frame matters as much as the
+ * midpoint: a crop that looks fine early pushes the payoff off the bottom once the
+ * camera has zoomed in, and PIPELINE.md's QC list calls that out specifically.
+ */
+export interface ContactSheetInput {
+    projectRoot?: string;
+    videoName: string;
+    compositionId?: string;
+    /** Sample only these beats. */
+    beatIds?: string[];
+    /** Skip the end-of-beat frame and take midpoints only. Halves the time. */
+    midpointOnly?: boolean;
+    outPath?: string;
+    /** Width of each tile in the sheet. */
+    tileWidth?: number;
+}
+export interface ContactSheetResult {
+    sheetPath: string;
+    frames: {
+        beatId: string;
+        at: "mid" | "end";
+        frame: number;
+        file: string;
+    }[];
+    columns: number;
+    failed: string[];
+}
+export declare function runContactSheet(input: ContactSheetInput): ContactSheetResult;
+export declare function registerContactSheet(server: McpServer): void;

package/dist/tools/contactSheet.js

@@ -0,0 +1,116 @@
+"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.runContactSheet = runContactSheet;
+exports.registerContactSheet = registerContactSheet;
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const mcp_1 = require("./mcp");
+function runContactSheet(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const compositionId = input.compositionId ?? `${(0, util_1.pascalCase)(videoName)}Demo`;
+    const tileWidth = input.tileWidth ?? 480;
+    const beatsFile = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    if (!fs.existsSync(beatsFile)) {
+        throw new Error(`No beats.json at ${beatsFile}. Run write_beats_file first.`);
+    }
+    const doc = JSON.parse(fs.readFileSync(beatsFile, "utf8"));
+    const beats = input.beatIds ? doc.beats.filter((b) => input.beatIds.includes(b.id)) : doc.beats;
+    const outDir = path.join(projectRoot, "out", "contact");
+    fs.mkdirSync(outDir, { recursive: true });
+    const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+    const frames = [];
+    const failed = [];
+    for (const beat of beats) {
+        const picks = [
+            { at: "mid", frame: beat.start + Math.floor(beat.duration * 0.5) },
+        ];
+        if (!input.midpointOnly) {
+            // Two frames back from the cut, so the shot has fully arrived.
+            picks.push({ at: "end", frame: beat.start + Math.max(0, beat.duration - 3) });
+        }
+        for (const pick of picks) {
+            const file = path.join(outDir, `${beat.id}-${pick.at}.png`);
+            const r = (0, node_child_process_1.spawnSync)(npx, ["remotion", "still", compositionId, file, `--frame=${pick.frame}`, "--log=error"], { cwd: projectRoot, encoding: "utf8" });
+            if (r.status === 0 && fs.existsSync(file)) {
+                frames.push({ beatId: beat.id, at: pick.at, frame: pick.frame, file });
+            }
+            else {
+                failed.push(`${beat.id}-${pick.at}`);
+            }
+        }
+    }
+    if (frames.length === 0) {
+        throw new Error(`No frames rendered. Check that composition "${compositionId}" exists.`);
+    }
+    const columns = Math.min(4, Math.ceil(Math.sqrt(frames.length)));
+    const sheetPath = path.join(projectRoot, input.outPath ?? path.join("out", "contact-sheet.jpg"));
+    fs.mkdirSync(path.dirname(sheetPath), { recursive: true });
+    const args = ["-v", "error"];
+    for (const f of frames)
+        args.push("-i", f.file);
+    const scaled = frames.map((_, i) => `[${i}]scale=${tileWidth}:-1[t${i}]`).join(";");
+    const refs = frames.map((_, i) => `[t${i}]`).join("");
+    args.push("-filter_complex", `${scaled};${refs}tile=${columns}x${Math.ceil(frames.length / columns)}:padding=8:color=#0B0E14`, "-frames:v", "1", sheetPath, "-y");
+    const tile = (0, node_child_process_1.spawnSync)("ffmpeg", args, { encoding: "utf8" });
+    if (tile.status !== 0) {
+        throw new Error(`ffmpeg could not tile the frames: ${(tile.stderr ?? "").slice(0, 300)}`);
+    }
+    return { sheetPath, frames, columns, failed };
+}
+function registerContactSheet(server) {
+    server.registerTool("contact_sheet", {
+        title: "Render one image showing every beat",
+        description: "Renders two stills per beat, midpoint and just before the cut, and tiles them into a single " +
+            "image. This is the fastest way to check framing across a whole video: a full render of a five " +
+            "minute video is 9000 frames and tens of minutes, which is far too slow a loop for catching a " +
+            "cropped panel or a caption that has drifted off screen. The end-of-beat frame matters as much as " +
+            "the midpoint, because a crop that looks correct early can push the payoff out of frame once the " +
+            "camera has zoomed in. Pass midpointOnly to halve the time, or beatIds to sample a few.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            compositionId: zod_1.z.string().optional(),
+            beatIds: zod_1.z.array(zod_1.z.string()).optional(),
+            midpointOnly: zod_1.z.boolean().optional(),
+            outPath: zod_1.z.string().optional(),
+            tileWidth: zod_1.z.number().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("contact_sheet", () => runContactSheet(input)));
+}

package/dist/tools/generateNarration.d.ts

@@ -0,0 +1,54 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Narration used to be entirely the caller's problem: PIPELINE.md said "dev
+ * provided", stitch_composition read the mp3s if they happened to exist, and that
+ * was it. In practice that meant most videos shipped silent, because nobody is going
+ * to hand-generate one correctly named clip per beat.
+ *
+ * Two things this gets right that a naive TTS loop does not.
+ *
+ * **Pacing.** Every engine reads at its own speed, so a clip rarely lands on its
+ * beat. The obvious fix, time-stretching audio to fit, is what makes narration sound
+ * artificial: a pitch-preserving stretch past roughly 10% is audible, and at 35% it
+ * is the main reason generated voiceover sounds synthetic. So stretching is clamped
+ * hard, and when a clip is still outside its beat the mismatch is reported as
+ * something to fix in the script or the beat duration instead of being papered over.
+ *
+ * **Silence.** stitch_composition skips a missing clip with no error, so a half
+ * generated narration renders successfully and plays silent in those beats. This
+ * reports exactly which beats have audio and which do not.
+ */
+export type NarrationEngine = "edge-tts" | "say" | "espeak";
+export interface GenerateNarrationInput {
+    projectRoot?: string;
+    videoName: string;
+    engine?: NarrationEngine;
+    voice?: string;
+    /** Seconds of silence left at the end of a beat so the cut does not clip the last word. */
+    padSeconds?: number;
+    /** Regenerate clips that already exist. */
+    overwrite?: boolean;
+    /** Only these beat ids. */
+    beatIds?: string[];
+}
+export interface NarrationClip {
+    beatId: string;
+    path: string;
+    beatSeconds: number;
+    spokenSeconds: number;
+    finalSeconds: number;
+    tempo: number;
+    /** True when the clip could not be fitted inside its beat without an audible stretch. */
+    needsAttention: boolean;
+    note?: string;
+}
+export interface GenerateNarrationResult {
+    engine: NarrationEngine;
+    voice: string;
+    written: NarrationClip[];
+    skipped: string[];
+    missing: string[];
+    warnings: string[];
+}
+export declare function runGenerateNarration(input: GenerateNarrationInput): GenerateNarrationResult;
+export declare function registerGenerateNarration(server: McpServer): void;