@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/renderStills.js

@@ -0,0 +1,399 @@
+"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.cropScale = cropScale;
+exports.resolveBeatFrame = resolveBeatFrame;
+exports.planBeatStills = planBeatStills;
+exports.locateFrame = locateFrame;
+exports.resolveCompositionId = resolveCompositionId;
+exports.buildContactGrid = buildContactGrid;
+exports.runRenderStills = runRenderStills;
+exports.registerRenderStills = registerRenderStills;
+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 stitchComposition_1 = require("./stitchComposition");
+const remotionBridge_1 = require("../remotionBridge");
+const mcp_1 = require("./mcp");
+const validateScenesRender_1 = require("./validateScenesRender");
+/**
+ * A fast QC loop: render a handful of representative frames (not a full video) so an
+ * agent can actually SEE a scene without waiting for a full ffmpeg encode.
+ *
+ * The speed comes entirely from bundling once: `bundle()` (webpack under the hood) is the
+ * slow part of a `remotion still`/`remotion render` CLI invocation, and that CLI re-bundles
+ * on every single call. This tool calls it exactly once per tool call, then calls
+ * `selectComposition`/`renderStill` (also @remotion/renderer's own public API) once per
+ * requested still against that one bundle -- see packages/mcp-server/src/remotionBridge.ts,
+ * ported from this repo's reference/scripts/stills.mjs. It also reuses one opened browser
+ * (via @remotion/renderer's `puppeteerInstance` option) across every still in the call, so
+ * neither the bundle nor the browser launch is repeated per beat.
+ *
+ * It is the review loop's instrument: author a scene, render stills, look (or read the
+ * numbers), fix, repeat. So beyond single frames it can sample several frames per beat
+ * including both sides of every cut, tile them into one labelled contact grid an agent can
+ * judge in a single image, and return the same numeric measurements validate_scenes makes
+ * for an agent that cannot see images.
+ */
+/** Sample positions inside a beat, as a fraction of its length, for `perBeat: "review"`. */
+const REVIEW_POSITIONS = [0, 0.25, 0.5, 0.75, 1];
+/** Frames inset from a beat's edges in review mode, so the shot straddles the cut rather than sitting on it. */
+const REVIEW_EDGE_INSET = 3;
+const GRID_TILE_WIDTH = 480;
+const MAX_PER_BEAT = 12;
+/** The crop is rendered at the whole number of times that brings it nearest this width, capped below. */
+const CROP_TARGET_WIDTH = 960;
+const CROP_MAX_SCALE = 4;
+/** Pure: the render scale for a crop of this width. A whole number, since a fractional one cannot give whole-pixel dimensions. */
+function cropScale(cropWidth) {
+    return Math.min(CROP_MAX_SCALE, Math.max(1, Math.round(CROP_TARGET_WIDTH / cropWidth)));
+}
+/** Pure, unit-testable: resolves which global frame a beat's representative still is at. */
+function resolveBeatFrame(beat, at) {
+    const duration = Math.max(1, beat.duration);
+    if (typeof at === "number") {
+        const offset = Math.min(Math.max(0, Math.round(at)), duration - 1);
+        return beat.start + offset;
+    }
+    if (at === "start")
+        return beat.start;
+    if (at === "end")
+        return beat.start + duration - 1;
+    return beat.start + Math.floor(duration / 2);
+}
+/**
+ * Pure: which frames of a beat to render. Offsets are clamped into the beat and deduplicated,
+ * so a very short beat yields fewer stills rather than the same frame twice.
+ */
+function planBeatStills(beat, perBeat) {
+    const duration = Math.max(1, beat.duration);
+    const last = duration - 1;
+    const clamp = (n) => Math.min(Math.max(0, Math.round(n)), last);
+    let picks;
+    if (perBeat === "review") {
+        picks = REVIEW_POSITIONS.map((p, i) => {
+            if (i === 0)
+                return { offset: clamp(REVIEW_EDGE_INSET), position: `start+${clamp(REVIEW_EDGE_INSET)}` };
+            if (i === REVIEW_POSITIONS.length - 1)
+                return { offset: clamp(last - REVIEW_EDGE_INSET), position: `end-${Math.min(REVIEW_EDGE_INSET, last)}` };
+            return { offset: clamp(last * p), position: p === 0.5 ? "mid" : `${Math.round(p * 100)}%` };
+        });
+    }
+    else if (perBeat <= 1) {
+        picks = [{ offset: Math.floor(duration / 2), position: "mid" }];
+    }
+    else {
+        picks = Array.from({ length: perBeat }, (_, i) => {
+            const fraction = i / (perBeat - 1);
+            const offset = clamp(last * fraction);
+            const position = i === 0 ? "start" : i === perBeat - 1 ? "end" : fraction === 0.5 ? "mid" : `${Math.round(fraction * 100)}%`;
+            return { offset, position };
+        });
+    }
+    const seen = new Set();
+    const out = [];
+    for (const p of picks) {
+        if (seen.has(p.offset))
+            continue;
+        seen.add(p.offset);
+        out.push({ beatId: beat.id, frame: beat.start + p.offset, offset: p.offset, position: p.position });
+    }
+    return out;
+}
+/** Pure: the beat a global frame belongs to, and its offset into it. Frames past the end clamp to the last beat. */
+function locateFrame(beats, frame) {
+    const sorted = [...beats].sort((a, b) => a.start - b.start);
+    const hit = sorted.find((b) => frame >= b.start && frame < b.start + b.duration) ?? sorted[sorted.length - 1];
+    return { beat: hit, offset: Math.min(Math.max(0, frame - hit.start), Math.max(0, hit.duration - 1)) };
+}
+function resolveCompositionId(projectRoot, videoName, override) {
+    if (override)
+        return override;
+    const entry = (0, stitchComposition_1.readRegistry)(projectRoot).find((e) => e.videoName === videoName);
+    if (!entry) {
+        throw new Error(`No composition registered for video "${videoName}" in src/videos/.registry.json. Run ` +
+            `stitch_composition for this video first, or pass compositionId explicitly.`);
+    }
+    return entry.id;
+}
+function escapeXml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/**
+ * Tiles rendered stills into one labelled PNG. A beat's stills share a row when perBeat was
+ * used, so reading across is time within a beat and reading down is the cut from one beat to
+ * the next; otherwise tiles fill rows of up to four. Each tile carries its beat id and
+ * position in a band above its picture, drawn as SVG so no font file has to be installed.
+ */
+async function buildContactGrid(stills, outPath, opts = {}) {
+    if (stills.length === 0)
+        throw new Error("buildContactGrid needs at least one still.");
+    const first = await (0, sharp_1.default)(stills[0].path).metadata();
+    const aspect = (first.height ?? 1080) / (first.width ?? 1920);
+    const tileW = GRID_TILE_WIDTH;
+    const tileH = Math.round(tileW * aspect);
+    const gap = 6;
+    // One row per beat when every beat has the same number of stills, which is what perBeat gives.
+    const perBeatCounts = new Map();
+    for (const s of stills)
+        perBeatCounts.set(s.beatId, (perBeatCounts.get(s.beatId) ?? 0) + 1);
+    const counts = new Set(perBeatCounts.values());
+    const rowPerBeat = counts.size === 1 && [...counts][0] > 1;
+    const columns = opts.columns ?? (rowPerBeat ? [...counts][0] : Math.min(4, stills.length));
+    const rows = Math.ceil(stills.length / columns);
+    // The label sits in its own band above each picture. Laid over the picture it hid the top tenth of
+    // every frame, which is where a headline lives.
+    const barH = 30;
+    const rowH = tileH + barH;
+    const width = columns * tileW + (columns + 1) * gap;
+    const height = rows * rowH + (rows + 1) * gap;
+    const layers = [];
+    for (const [i, s] of stills.entries()) {
+        const col = i % columns;
+        const row = Math.floor(i / columns);
+        const left = gap + col * (tileW + gap);
+        const top = gap + row * (rowH + gap);
+        const tile = await (0, sharp_1.default)(s.path).resize(tileW, tileH, { fit: "cover" }).png().toBuffer();
+        layers.push({ input: tile, left, top: top + barH });
+        const label = escapeXml(`${s.beatId}  ${s.position}  f${s.frame}`);
+        const bar = `<svg xmlns="http://www.w3.org/2000/svg" width="${tileW}" height="${barH}"><rect width="${tileW}" height="${barH}" fill="#000" fill-opacity="0.85"/><text x="10" y="21" font-family="Arial, Helvetica, sans-serif" font-size="17" fill="#fff">${label}</text></svg>`;
+        layers.push({ input: Buffer.from(bar), left, top });
+    }
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    await (0, sharp_1.default)({ create: { width, height, channels: 3, background: { r: 18, g: 18, b: 22 } } })
+        .composite(layers)
+        .png()
+        .toFile(outPath);
+    return { path: outPath, width, height, columns, rows, tiles: stills.length };
+}
+async function runRenderStills(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    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 allBeats = doc.beats ?? [];
+    if (allBeats.length === 0) {
+        throw new Error(`${beatsFile} has no beats.`);
+    }
+    const totalFrames = Math.max(...allBeats.map((b) => b.start + b.duration));
+    let beats = allBeats;
+    if (!input.frames && input.beatIds && input.beatIds.length > 0) {
+        const known = new Set(allBeats.map((b) => b.id));
+        const unknown = input.beatIds.filter((id) => !known.has(id));
+        if (unknown.length > 0) {
+            throw new Error(`beatIds not found in beats.json: ${unknown.join(", ")}`);
+        }
+        const wanted = new Set(input.beatIds);
+        beats = allBeats.filter((b) => wanted.has(b.id));
+    }
+    if (typeof input.perBeat === "number" && (!Number.isInteger(input.perBeat) || input.perBeat < 1 || input.perBeat > MAX_PER_BEAT)) {
+        throw new Error(`perBeat must be a whole number from 1 to ${MAX_PER_BEAT}, or "review". Got ${input.perBeat}.`);
+    }
+    const plan = [];
+    if (input.frames && input.frames.length > 0) {
+        const bad = input.frames.filter((f) => !Number.isInteger(f) || f < 0 || f >= totalFrames);
+        if (bad.length > 0) {
+            throw new Error(`frames must be whole numbers from 0 to ${totalFrames - 1} (this composition has ${totalFrames} frames). Got: ${bad.join(", ")}.`);
+        }
+        for (const frame of [...new Set(input.frames)].sort((a, b) => a - b)) {
+            const { beat, offset } = locateFrame(allBeats, frame);
+            plan.push({ beatId: beat.id, frame, offset, position: `+${offset}` });
+        }
+        beats = allBeats.filter((b) => plan.some((p) => p.beatId === b.id));
+    }
+    else if (input.perBeat !== undefined) {
+        for (const beat of beats)
+            plan.push(...planBeatStills(beat, input.perBeat));
+    }
+    else {
+        for (const beat of beats) {
+            const frame = resolveBeatFrame(beat, input.at);
+            const offset = frame - beat.start;
+            const position = typeof input.at === "number" ? `+${offset}` : (input.at ?? "mid");
+            plan.push({ beatId: beat.id, frame, offset, position });
+        }
+    }
+    const compositionId = resolveCompositionId(projectRoot, videoName, input.compositionId);
+    const crop = input.crop;
+    if (crop) {
+        const whole = [crop.x, crop.y, crop.width, crop.height].every((n) => Number.isInteger(n) && n >= 0);
+        if (!whole || crop.width < 1 || crop.height < 1) {
+            throw new Error(`crop must be { x, y, width, height } in whole composition pixels with a positive width and height. Got ${JSON.stringify(crop)}.`);
+        }
+    }
+    const baseOutRel = input.outDir ?? path.join("output", "stills", videoName);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, baseOutRel, "outDir");
+    const outDirRel = input.round === undefined ? baseOutRel : path.join(baseOutRel, `round-${(0, util_1.sanitizeSegment)(String(input.round), "round")}`);
+    const outDirAbs = path.join(projectRoot, outDirRel);
+    // One still per beat keeps the original <beatId>.png name; several per beat or explicit
+    // frames cannot, since the beat id alone no longer says which frame it is.
+    const perBeatCounts = new Map();
+    for (const p of plan)
+        perBeatCounts.set(p.beatId, (perBeatCounts.get(p.beatId) ?? 0) + 1);
+    const fileFor = (p) => input.frames || (perBeatCounts.get(p.beatId) ?? 1) > 1 ? `${p.beatId}-f${String(p.offset).padStart(4, "0")}.png` : `${p.beatId}.png`;
+    const bundleStarted = Date.now();
+    const serveUrl = await (0, remotionBridge_1.bundleProject)(projectRoot);
+    const bundleMs = Date.now() - bundleStarted;
+    let browser = null;
+    const renderStarted = Date.now();
+    try {
+        browser = await (0, remotionBridge_1.openRenderBrowser)();
+        const composition = await (0, remotionBridge_1.resolveComposition)(serveUrl, compositionId, browser);
+        if (crop && (crop.x + crop.width > composition.width || crop.y + crop.height > composition.height)) {
+            throw new Error(`crop ${JSON.stringify(crop)} reaches outside the ${composition.width}x${composition.height} composition. ` +
+                `Give x, y, width and height in composition pixels that stay inside it.`);
+        }
+        const stills = [];
+        for (const p of plan) {
+            const outPath = path.join(outDirAbs, fileFor(p));
+            const result = await (0, remotionBridge_1.renderStillPng)({ serveUrl, composition, frame: p.frame, outPath, browser, scale: input.scale });
+            let cropOutput;
+            if (crop) {
+                // Re-rendered at a higher scale instead of cropped from the 1x still: enlarging pixels that
+                // were never there would show the blur, not the text.
+                const scale = cropScale(crop.width);
+                const cropPath = outPath.replace(/\.png$/, "-crop.png");
+                const full = outPath.replace(/\.png$/, "-crop-src.png");
+                await (0, remotionBridge_1.renderStillPng)({ serveUrl, composition, frame: p.frame, outPath: full, browser, scale });
+                const width = crop.width * scale;
+                const height = crop.height * scale;
+                await (0, sharp_1.default)(full).extract({ left: crop.x * scale, top: crop.y * scale, width, height }).png().toFile(cropPath);
+                fs.rmSync(full, { force: true });
+                cropOutput = { path: cropPath, width, height, scale };
+            }
+            stills.push({
+                beatId: p.beatId,
+                frame: p.frame,
+                offset: p.offset,
+                position: p.position,
+                path: result.outPath,
+                width: result.width,
+                height: result.height,
+                bytes: result.bytes,
+                ...(cropOutput ? { crop: cropOutput } : {}),
+            });
+        }
+        let contactGrid;
+        if ((input.contactGrid ?? stills.length > 1) && stills.length > 0) {
+            contactGrid = await buildContactGrid(stills, path.join(outDirAbs, "contact-grid.png"));
+        }
+        const renderMs = Date.now() - renderStarted;
+        const result = { compositionId, stills, bundleMs, renderMs, totalMs: bundleMs + renderMs };
+        if (contactGrid)
+            result.contactGrid = contactGrid;
+        if (input.findings !== false) {
+            const measured = await (0, validateScenesRender_1.runRenderChecks)({
+                projectRoot,
+                videoName,
+                compositionId,
+                beats,
+                fps: doc.fps ?? 30,
+                minimums: (0, validateScenesRender_1.readTypeMinimums)(path.join(projectRoot, "src", "videos", videoName)),
+                deliberateHolds: (0, validateScenesRender_1.readDeliberateHolds)(path.join(projectRoot, "src", "videos", videoName)),
+                bundleDir: serveUrl,
+            });
+            result.findings = measured.findings;
+            result.findingsSkipped = measured.beatsSkipped;
+            result.totalMs = Date.now() - bundleStarted;
+        }
+        return result;
+    }
+    finally {
+        if (browser)
+            await browser.close({ silent: true });
+    }
+}
+function registerRenderStills(server) {
+    server.registerTool("render_stills", {
+        title: "Render representative frames without a full video encode",
+        description: "The review loop's instrument: renders real frames so an agent can see a scene without waiting for a " +
+            "full ffmpeg encode of the whole composition. The speed comes from bundling the project with " +
+            "@remotion/bundler exactly once per call and reusing that one bundle plus one headless browser for " +
+            "every still (@remotion/renderer's own selectComposition/renderStill, the same public SSR API " +
+            "`remotion still` itself wraps) -- a full `remotion still` CLI invocation re-bundles on every single " +
+            "call, which is the slow part this avoids. By default it renders one frame per beat (that beat's " +
+            "midpoint). Pass `at` (\"start\"/\"mid\"/\"end\" or a frame offset into the beat) to pick another, " +
+            "`perBeat` for several per beat (a number, or \"review\" for five with the first and last pulled just " +
+            "inside the beat so adjacent beats show both sides of every cut), or `frames` for exact global frame " +
+            "numbers. With more than one still it also writes a labelled contact-grid PNG (one row per beat when " +
+            "perBeat is used: across is time within a beat, down is the cut to the next) so a whole round can be " +
+            "judged from one image; `round` keeps each review round in its own folder. It also returns " +
+            "validate_scenes's numeric render findings for the same beats (cropping, text size, reading time, " +
+            "contrast, em dashes, safe area, HUD overlap, dead frames), reusing this call's bundle, so an agent " +
+            "that cannot view images reviews from the numbers; pass findings: false to skip them. Pass crop " +
+            "({ x, y, width, height } in composition pixels) to also get each still's region re-rendered at a " +
+            "higher scale as <name>-crop.png, for checking small text. The composition " +
+            "id is resolved from src/videos/.registry.json (written by stitch_composition) unless overridden. " +
+            "Writes PNGs to output/stills/<videoName>/ by default (gitignored QC output, same convention as " +
+            "contact_sheet/qc_extract_frames, not shipped media). Returns { compositionId, stills: [{beatId, " +
+            "frame, offset, position, path, width, height, bytes}], contactGrid, findings, findingsSkipped, " +
+            "bundleMs, renderMs, totalMs } -- width/height/bytes are measured from the real file written, not " +
+            "assumed, so a near-empty render is visible in the result rather than silently reported as success.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            beatIds: zod_1.z.array(zod_1.z.string()).optional(),
+            at: zod_1.z.union([zod_1.z.enum(["start", "mid", "end"]), zod_1.z.number().int().nonnegative()]).optional(),
+            perBeat: zod_1.z.union([zod_1.z.number().int().min(1).max(MAX_PER_BEAT), zod_1.z.literal("review")]).optional(),
+            frames: zod_1.z.array(zod_1.z.number().int().nonnegative()).min(1).optional(),
+            compositionId: zod_1.z.string().optional(),
+            outDir: zod_1.z.string().optional(),
+            round: zod_1.z.union([zod_1.z.number().int().nonnegative(), zod_1.z.string().min(1)]).optional(),
+            scale: zod_1.z.number().positive().optional(),
+            contactGrid: zod_1.z.boolean().optional(),
+            findings: zod_1.z.boolean().optional(),
+            crop: zod_1.z
+                .object({
+                x: zod_1.z.number().int().nonnegative(),
+                y: zod_1.z.number().int().nonnegative(),
+                width: zod_1.z.number().int().positive(),
+                height: zod_1.z.number().int().positive(),
+            })
+                .optional()
+                .describe("A region in composition pixels to check closely, for small text. Each still also gets " +
+                "<name>-crop.png next to it: that region re-rendered at a higher scale (a whole number, " +
+                "nearest 960 px wide, at most 4x), not stretched from the 1x still, returned as still.crop " +
+                "{ path, width, height, scale }. A region outside the composition is an error."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("render_stills", () => runRenderStills(input)));
+}

package/dist/tools/renderVideo.d.ts

@@ -16,6 +16,42 @@ export interface RenderVideoInput {
      * box, including a second pipeline step running at the same time.
      */
     concurrency?: number;
+    /**
+     * Brand-lock gate escape hatch (default false): render_video refuses to run unless
+     * src/brand.ts exists (written by extract_brand, even when most of its tokens stayed
+     * at the openvidstudio default -- the point is that extract_brand ran and made an
+     * honest attempt, not that every token resolved). Pass true only when the project
+     * deliberately has no brand to extract, e.g. rendering a demo about openvidstudio
+     * itself. This is a fail-closed default, not a hard law: it exists so a video never
+     * ships wearing openvidstudio's own navy/Inter look by accident, the single loudest
+     * "this looks like a template" signal (see extractBrand.ts).
+     */
+    skipBrandLock?: boolean;
+    /**
+     * Render each beat to its own cached segment and concatenate, re-rendering only the
+     * beats whose inputs actually changed. Costs one extra ffmpeg stream copy and makes a
+     * one caption edit cost one beat instead of nine thousand frames.
+     */
+    incremental?: boolean;
+    /**
+     * Start the render without blocking the request. Returns { jobId, estimate } immediately;
+     * poll job_status for progress and the eventual RenderVideoResult. Exists because a real
+     * render can run 40+ minutes on a modest machine, and an MCP client's own request timeout
+     * (Claude Code's MCP_TOOL_TIMEOUT, or the SDK client default) will have long since killed
+     * a synchronous call by then. See job_status.ts and README's timeout-guidance section.
+     */
+    async?: boolean;
+}
+/** Progress callback shape, shared by the async job-store path and the synchronous
+ * MCP-progress-notification path -- both just want to know frames rendered and the current
+ * beat, they differ only in what they do with that. */
+export type RenderProgress = {
+    framesRendered: number;
+    totalFrames: number;
+    currentBeat: string | null;
+};
+export interface RenderVideoOpts {
+    onProgress?: (progress: RenderProgress) => void;
 }
 export interface RenderVideoResult {
     success: boolean;
@@ -24,6 +60,17 @@ export interface RenderVideoResult {
     elapsedSeconds: number;
     stdout: string;
     stderr: string;
+    /** True when src/brand.ts existed at render time (whether from this call's skipBrandLock or a real extract_brand run). */
+    brandLocked: boolean;
+    /** Set when the brand-lock gate was skipped on purpose: a Supernova lesson has no brand to extract. */
+    brandLockSkipReason?: string;
+    /** Incremental renders only: beats whose cached segment was reused untouched. */
+    reusedBeats?: string[];
+    /** Incremental renders only: beats that were actually re-rendered. */
+    renderedBeats?: string[];
+    /** Incremental renders only: frames sent to the renderer, against the composition's total. */
+    framesRendered?: number;
+    totalFrames?: number;
 }
 export interface RenderCommand {
     command: string;
@@ -38,6 +85,28 @@ export interface RenderCommand {
 export declare function buildRenderCommand(compositionId: string, outPath: string, opts?: {
     draft?: boolean;
     concurrency?: number;
+    browserExecutable?: string;
 }): RenderCommand;
-export declare function runRenderVideo(input: RenderVideoInput): Promise<RenderVideoResult>;
+export interface PreparedRenderVideo {
+    videoName: string;
+    projectRoot: string;
+    compositionId: string;
+    outPathRel: string;
+    brandLocked: boolean;
+    brandLockSkipReason?: string;
+}
+/**
+ * The synchronous half of render_video: validate input and the brand-lock gate, throwing
+ * immediately on anything wrong, before any real work (a render that will take 40+ minutes,
+ * possibly started detached under `async: true`) begins. Split out so the async path can
+ * fail a bad call synchronously too, instead of "succeeding" with a jobId that immediately
+ * errors.
+ */
+export declare function prepareRenderVideo(input: RenderVideoInput): PreparedRenderVideo;
+/**
+ * Records what this render actually did next to what was asked: which beats were rendered
+ * and which came from the cache, and the size of the file that landed. The result's own
+ * stdout/stderr stay out of the record, they are logs, not facts.
+ */
+export declare function runRenderVideo(input: RenderVideoInput, opts?: RenderVideoOpts): Promise<RenderVideoResult>;
 export declare function registerRenderVideo(server: McpServer): void;