@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/tools/composeScore.js

@@ -0,0 +1,330 @@
+"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.resolvePythonCommand = resolvePythonCommand;
+exports.sectionsToPythonSections = sectionsToPythonSections;
+exports.impactPointsToPythonImpacts = impactPointsToPythonImpacts;
+exports.buildComposeScoreSpec = buildComposeScoreSpec;
+exports.computeWarnings = computeWarnings;
+exports.runComposeScore = runComposeScore;
+exports.registerComposeScore = registerComposeScore;
+const node_child_process_1 = require("node:child_process");
+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 paths_1 = require("../paths");
+const mcp_1 = require("./mcp");
+const OUT_FILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*\.mp3$/i;
+/** How far lufsIntegrated may sit from lufsTarget before it is worth flagging. */
+const LUFS_DRIFT_WARNING_LU = 1;
+function which(cmd) {
+    const probe = process.platform === "win32" ? "where" : "which";
+    const r = (0, node_child_process_1.spawnSync)(probe, [cmd], { encoding: "utf8" });
+    if (r.status !== 0)
+        return null;
+    return (r.stdout ?? "").split(/\r?\n/)[0]?.trim() || null;
+}
+/** Same python-then-python3 fallback order preflight.ts's "compose-score-deps" check uses. */
+function resolvePythonCommand() {
+    if (which("python"))
+        return "python";
+    if (which("python3"))
+        return "python3";
+    return null;
+}
+/**
+ * brief's sectionMap: [{label, startBar, endBar}] becomes compose-score.py's
+ * sections: [{label, bars}]. Validated contiguous and strictly in order first, so a
+ * gap or overlap the brief didn't intend to have is caught here rather than silently
+ * producing a score whose structure doesn't match what the brief actually described.
+ */
+function sectionsToPythonSections(sectionMap) {
+    if (!sectionMap || sectionMap.length === 0) {
+        throw new Error("music.sectionMap is empty. At least one section is required.");
+    }
+    for (let i = 0; i < sectionMap.length; i++) {
+        const s = sectionMap[i];
+        if (s.endBar <= s.startBar) {
+            throw new Error(`music.sectionMap's "${s.label}" section has endBar (${s.endBar}) at or before startBar (${s.startBar}).`);
+        }
+        if (i > 0) {
+            const prev = sectionMap[i - 1];
+            if (prev.endBar !== s.startBar) {
+                throw new Error(`music.sectionMap is not contiguous: "${prev.label}" ends at bar ${prev.endBar} but ` +
+                    `"${s.label}" starts at bar ${s.startBar}. Sections must connect exactly, ` +
+                    `each endBar equal to the next section's startBar.`);
+            }
+        }
+    }
+    return sectionMap.map((s) => ({ label: s.label, bars: s.endBar - s.startBar }));
+}
+/**
+ * impactPoints: [{name, bar, note}] to spec's impacts: [{label, atBar, atBeat}]. The
+ * brief has no beat-level granularity, so atBeat is 0, which main() itself treats as
+ * the default (`imp.get("atBeat", 0)`).
+ */
+function impactPointsToPythonImpacts(impactPoints) {
+    return (impactPoints ?? []).map((p) => ({ label: p.name, atBar: p.bar, atBeat: 0 }));
+}
+function buildComposeScoreSpec(music, trackName, outWav, outCues, outSpectrogram, mode, percussion = "none") {
+    return {
+        bpm: music.bpm,
+        key: music.key,
+        sections: sectionsToPythonSections(music.sectionMap),
+        impacts: impactPointsToPythonImpacts(music.impactPoints),
+        mode,
+        percussion,
+        trackName,
+        outWav,
+        outCues,
+        outSpectrogram,
+    };
+}
+/**
+ * Surfaces the script's own diagnostic checks as actionable warnings instead of leaving
+ * them readable only by opening the written cues file. Any of: a band-balance verdict
+ * that isn't "ok", a detected click, a true peak over the limiter's own ceiling, or an
+ * integrated loudness far from the mastering target.
+ */
+function computeWarnings(cues) {
+    const warnings = [];
+    const checks = (cues.checks ?? {});
+    const bandBalance = checks.bandBalance;
+    const verdict = bandBalance?.verdict;
+    if (typeof verdict === "string" && verdict !== "ok") {
+        warnings.push(`Band energy balance verdict is "${verdict}", not "ok".`);
+    }
+    const clickCount = checks.clickCount;
+    if (typeof clickCount === "number" && clickCount > 0) {
+        warnings.push(`${clickCount} click${clickCount === 1 ? "" : "s"} detected in the mastered mix.`);
+    }
+    const tick = checks.percussionTick;
+    if (tick && tick.verdict === "periodic") {
+        warnings.push(`Periodic high-frequency transients every ~${tick.lagMs} ms (autocorrelation ${tick.peak}, threshold ` +
+            `${tick.thresholdPeak}): this score will sound like a ticking clock. Use percussion "none" or vary the rhythm.`);
+    }
+    const truePeakDbtp = cues.truePeakDbtp;
+    const truePeakMaxDbtp = cues.truePeakMaxDbtp;
+    if (typeof truePeakDbtp === "number" && typeof truePeakMaxDbtp === "number" && truePeakDbtp > truePeakMaxDbtp) {
+        warnings.push(`True peak ${truePeakDbtp}dBTP exceeds the limiter's ${truePeakMaxDbtp}dBTP ceiling.`);
+    }
+    const lufsIntegrated = cues.lufsIntegrated;
+    const lufsTarget = cues.lufsTarget;
+    if (typeof lufsIntegrated === "number" &&
+        typeof lufsTarget === "number" &&
+        Math.abs(lufsIntegrated - lufsTarget) > LUFS_DRIFT_WARNING_LU) {
+        warnings.push(`Integrated loudness ${lufsIntegrated} LUFS is more than ${LUFS_DRIFT_WARNING_LU} LU from the ${lufsTarget} LUFS target.`);
+    }
+    return warnings;
+}
+function loadMusicPlan(projectRoot, videoName, override) {
+    if (override)
+        return override;
+    const briefPath = path.join(projectRoot, "src", "videos", videoName, "brief.json");
+    if (!fs.existsSync(briefPath)) {
+        throw new Error(`No music plan was given and no brief.json exists at ${briefPath}. Run write_brief first, or pass ` +
+            `music directly.`);
+    }
+    let brief;
+    try {
+        brief = JSON.parse(fs.readFileSync(briefPath, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${briefPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!brief.music) {
+        throw new Error(`${briefPath} has no "music" field and no music input was given. Run write_brief first, or pass ` +
+            `music directly.`);
+    }
+    return brief.music;
+}
+function probeDurationSeconds(mp3Abs) {
+    const r = (0, node_child_process_1.spawnSync)("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", mp3Abs], { encoding: "utf8" });
+    const v = Number.parseFloat((r.stdout ?? "").trim());
+    return Number.isFinite(v) ? Number(v.toFixed(3)) : 0;
+}
+function runComposeScore(input) {
+    if (input.mode !== "bed" && input.mode !== "music") {
+        throw new Error('mode is required: choose "bed" for narrated video (-15 LUFS) or "music" for music-only video (-14 LUFS).');
+    }
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const music = loadMusicPlan(projectRoot, videoName, input.music);
+    // Validated first, before any temp file, output directory or process: a brief whose
+    // section arc doesn't connect should fail immediately, not after this has already
+    // touched disk or spawned anything.
+    sectionsToPythonSections(music.sectionMap);
+    impactPointsToPythonImpacts(music.impactPoints);
+    const outFile = input.outFile ?? "music-bed.mp3";
+    if (!OUT_FILE_PATTERN.test(outFile)) {
+        throw new Error(`outFile "${outFile}" must be a bare filename ending in .mp3 (letters, numbers, "-", "_").`);
+    }
+    const mp3Rel = path.join("public", "audio", outFile);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, mp3Rel, "outFile");
+    const mp3Abs = path.join(projectRoot, mp3Rel);
+    const trackName = mp3Rel.replace(/\\/g, "/");
+    const stem = outFile.slice(0, -".mp3".length);
+    const cuesAbs = path.join(path.dirname(mp3Abs), `${stem}.cues.json`);
+    const spectrogramAbs = path.join(path.dirname(mp3Abs), `${stem}.spectrogram.png`);
+    const scriptPath = path.join(paths_1.PY_DIR, "compose-score.py");
+    if (!fs.existsSync(scriptPath)) {
+        throw new Error(`compose-score.py not found at ${scriptPath}. This package's py/ directory did not ship, or the DSP ` +
+            `engine has not been added to this checkout yet.`);
+    }
+    const pythonCmd = resolvePythonCommand();
+    if (!pythonCmd) {
+        throw new Error(`No python or python3 on PATH. compose_score needs a python with numpy, scipy, soundfile, ` +
+            `pyloudnorm and matplotlib importable; run preflight to check.`);
+    }
+    // outCues and outSpectrogram point straight at their final home (main() creates the
+    // directory for each of outWav/outCues/outSpectrogram itself via os.makedirs), so
+    // there is no separate move or merge step for either. outWav alone goes to a temp
+    // path: the wav is a transient intermediate, transcoded to mp3 below, then deleted.
+    fs.mkdirSync(path.dirname(mp3Abs), { recursive: true });
+    const tmpWavAbs = path.join(os.tmpdir(), `ovs-compose-score-${process.pid}-${Date.now()}.wav`);
+    const spec = buildComposeScoreSpec(music, trackName, tmpWavAbs, cuesAbs, spectrogramAbs, input.mode, input.percussion ?? "none");
+    const specAbs = path.join(os.tmpdir(), `ovs-compose-score-spec-${process.pid}-${Date.now()}.json`);
+    fs.writeFileSync(specAbs, JSON.stringify(spec, null, 2), "utf8");
+    let proc;
+    try {
+        proc = (0, node_child_process_1.spawnSync)(pythonCmd, [scriptPath, specAbs], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    }
+    finally {
+        fs.rmSync(specAbs, { force: true });
+    }
+    if (proc.error || proc.status !== 0) {
+        // main()'s own except-block already removes any of outWav/outCues/outSpectrogram it
+        // had written before failing, so there is nothing of its own left to clean up here.
+        const tail = (proc.stderr || proc.stdout || String(proc.error ?? "")).slice(-2000);
+        throw new Error(`compose-score.py failed (exit ${proc.status ?? "n/a"}):\n${tail}`);
+    }
+    if (!fs.existsSync(tmpWavAbs) || !fs.existsSync(cuesAbs)) {
+        throw new Error(`compose-score.py exited 0 but did not write both outWav (${tmpWavAbs}) and outCues (${cuesAbs}).`);
+    }
+    // The wav is a transient intermediate, not a shipped artifact: transcode to mp3, then
+    // delete it. Matches generateNarration.ts's own libmp3lame/-q:a convention, one notch
+    // higher quality since this is a full mix, not narration.
+    const ffmpegRes = (0, node_child_process_1.spawnSync)("ffmpeg", ["-y", "-i", tmpWavAbs, "-c:a", "libmp3lame", "-q:a", "2", "-ac", "2", mp3Abs], { encoding: "utf8" });
+    fs.rmSync(tmpWavAbs, { force: true });
+    if (ffmpegRes.status !== 0) {
+        throw new Error(`ffmpeg failed transcoding the mastered score to mp3:\n${(ffmpegRes.stderr ?? "").slice(-2000)}`);
+    }
+    const cuesFromScript = JSON.parse(fs.readFileSync(cuesAbs, "utf8"));
+    // durationSeconds is probed from the real written mp3 rather than trusted from the
+    // script's own report: cheap, since ffmpeg already ran, and removes any dependence on
+    // the wav-to-mp3 transcode preserving duration exactly.
+    const durationSeconds = probeDurationSeconds(mp3Abs);
+    const warnings = computeWarnings(cuesFromScript);
+    // The script already sets track/source/generatedBy itself (given trackName above),
+    // but this re-asserts all three plus the probed durationSeconds: certainty that the
+    // MusicCuesResult-required fields are right regardless of what the script's own
+    // internals happen to default to, and a chance to fix generatedBy's stale "scripts/"
+    // path on the copy this tool actually ships (not the .py source itself).
+    const finalCues = {
+        ...cuesFromScript,
+        durationSeconds,
+        track: trackName,
+        generatedBy: "packages/mcp-server/py/compose-score.py",
+        source: "generated",
+    };
+    fs.writeFileSync(cuesAbs, JSON.stringify(finalCues, null, 2) + "\n", "utf8");
+    const bpm = typeof finalCues.bpm === "number" ? finalCues.bpm : music.bpm;
+    return {
+        mp3Path: trackName,
+        cuesPath: path.relative(projectRoot, cuesAbs).replace(/\\/g, "/"),
+        spectrogramPath: path.relative(projectRoot, spectrogramAbs).replace(/\\/g, "/"),
+        bpm,
+        key: music.key,
+        durationSeconds,
+        warnings,
+        cues: finalCues,
+    };
+}
+const musicSectionSchema = zod_1.z.object({
+    // Not a closed enum: the 7-label vocabulary (intro/tension/reveal/groove/break/peak/
+    // outro) is the documented convention and is what compose-score.py's RENDERERS table
+    // actually keys on, but an unrecognized label is the script's own KeyError to raise,
+    // not a validation this tool duplicates and risks getting out of sync with.
+    label: zod_1.z.string().min(1),
+    startBar: zod_1.z.number().int().nonnegative(),
+    endBar: zod_1.z.number().int().positive(),
+});
+const musicImpactSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1),
+    bar: zod_1.z.number().int().nonnegative(),
+    note: zod_1.z.string().optional(),
+});
+const musicPlanSchema = zod_1.z.object({
+    bpm: zod_1.z.number().positive(),
+    key: zod_1.z.string().min(1),
+    sectionMap: zod_1.z.array(musicSectionSchema).min(1),
+    impactPoints: zod_1.z.array(musicImpactSchema).optional(),
+});
+function registerComposeScore(server) {
+    server.registerTool("compose_score", {
+        title: "Compose an original, arc-matched score",
+        description: "Builds a spec.json from a video's music plan (brief.json's `music` field, or a direct override) " +
+            "and spawns packages/mcp-server/py/compose-score.py to compose and master an original score that " +
+            "follows the brief's section arc (intro/tension/reveal/groove/break/peak/outro) and lands its impact " +
+            "points on the bar they were planned for. Writes the result to public/audio/music-bed.mp3 by default " +
+            "(overridable via outFile, e.g. to A/B two tracks), which is exactly where stitch_composition's own " +
+            "auto-detection already looks. Also writes public/audio/<stem>.cues.json with source: \"generated\", " +
+            "so plan_music_cues treats it as ground truth and returns it directly rather than re-analyzing, and " +
+            "keeps the script's diagnostic spectrogram PNG permanently at public/audio/<stem>.spectrogram.png. " +
+            "mode is required: choose \"bed\" (-15 LUFS) for narrated videos, which most callers want, since it sits under " +
+            "voiceover; choose \"music\" (-14 LUFS) only for a music-only video with no narration. No silent default. Validates that the " +
+            "brief's sectionMap is contiguous (each section's endBar equal to the next section's startBar) " +
+            "before composing anything, and throws naming exactly which two sections don't connect if not. " +
+            "Surfaces the script's own mastering checks as a warnings array: a band-balance verdict other than " +
+            "\"ok\", any detected click, a periodic high-frequency tick pattern, a true peak over the limiter's " +
+            "ceiling, or an integrated loudness far from target. percussion defaults to \"none\": no kick, clap, " +
+            "hat or tick, with uneven bass and arp rhythms, because evenly repeated short hits read as a ticking " +
+            "clock under a voiceover. Pass percussion \"full\" only if you want the old drum-machine arrangement. " +
+            "This is the highest-effort of the music options (the built-in ambient music-bed.mp3, a found CC0 " +
+            "track via find_music_bed, or this), meant for peak creative level: an original score built to match " +
+            "the video's own arc rather than a pre-made or found track.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            music: musicPlanSchema.optional().describe("Direct override, shaped like brief.json's `music` field. If omitted, read from " +
+                "src/videos/<videoName>/brief.json."),
+            outFile: zod_1.z.string().optional().describe('Bare filename under public/audio/, ending in .mp3. Defaults to "music-bed.mp3".'),
+            mode: zod_1.z.enum(["bed", "music"]).describe('Required: "bed" (-15 LUFS) for narrated videos (most common); "music" (-14 LUFS) for music-only videos. No default.'),
+            percussion: zod_1.z.enum(["none", "full"]).optional().describe('Defaults to "none": no kick, clap, hat or tick, uneven bass and arp rhythms. "full" is the old drum-machine arrangement and is flagged by the periodic-tick check.'),
+        },
+    }, async (input) => (0, mcp_1.runTool)("compose_score", () => runComposeScore(input)));
+}

package/dist/tools/contactSheet.d.ts

@@ -32,5 +32,23 @@ export interface ContactSheetResult {
     columns: number;
     failed: string[];
 }
-export declare function runContactSheet(input: ContactSheetInput): ContactSheetResult;
+/**
+ * Pure filtergraph builder, unit-testable without spawning ffmpeg.
+ *
+ * ffmpeg's `tile` filter takes exactly ONE input stream. Feeding it N labelled
+ * scaled streams directly (the old shape here) fails with "More input link
+ * labels specified for filter 'tile' than it has inputs". Every frame is
+ * scaled to the same tileWidth (height forced even via -2, since h264/jpeg
+ * encoders reject odd dimensions), the N scaled streams are concatenated into
+ * ONE stream with `concat`, and only that one stream feeds `tile`. Every frame
+ * here is a still of the same compositionId at a different timestamp, so all
+ * frames already share one source aspect ratio: scaling each to the same width
+ * cannot produce mismatched heights across them, which is what keeps `concat`
+ * (which requires identical dimensions on every input) safe without an
+ * explicit pad step.
+ */
+export declare function buildContactSheetFilterGraph(frameCount: number, tileWidth: number, columns: number, rows: number): string;
+/** Pure argv builder, unit-testable without spawning ffmpeg. */
+export declare function buildContactSheetArgs(frameFiles: string[], tileWidth: number, columns: number, rows: number, sheetPath: string): string[];
+export declare function runContactSheet(input: ContactSheetInput): Promise<ContactSheetResult>;
 export declare function registerContactSheet(server: McpServer): void;

package/dist/tools/contactSheet.js

@@ -33,18 +33,57 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildContactSheetFilterGraph = buildContactSheetFilterGraph;
+exports.buildContactSheetArgs = buildContactSheetArgs;
 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 COMPOSITION_ID_RE = /^[A-Za-z0-9_-]+$/;
+/**
+ * Pure filtergraph builder, unit-testable without spawning ffmpeg.
+ *
+ * ffmpeg's `tile` filter takes exactly ONE input stream. Feeding it N labelled
+ * scaled streams directly (the old shape here) fails with "More input link
+ * labels specified for filter 'tile' than it has inputs". Every frame is
+ * scaled to the same tileWidth (height forced even via -2, since h264/jpeg
+ * encoders reject odd dimensions), the N scaled streams are concatenated into
+ * ONE stream with `concat`, and only that one stream feeds `tile`. Every frame
+ * here is a still of the same compositionId at a different timestamp, so all
+ * frames already share one source aspect ratio: scaling each to the same width
+ * cannot produce mismatched heights across them, which is what keeps `concat`
+ * (which requires identical dimensions on every input) safe without an
+ * explicit pad step.
+ */
+function buildContactSheetFilterGraph(frameCount, tileWidth, columns, rows) {
+    const scaled = Array.from({ length: frameCount }, (_, i) => `[${i}]scale=${tileWidth}:-2[t${i}]`).join(";");
+    const refs = Array.from({ length: frameCount }, (_, i) => `[t${i}]`).join("");
+    return `${scaled};${refs}concat=n=${frameCount}:v=1:a=0,tile=${columns}x${rows}:padding=8:color=#0B0E14`;
+}
+/** Pure argv builder, unit-testable without spawning ffmpeg. */
+function buildContactSheetArgs(frameFiles, tileWidth, columns, rows, sheetPath) {
+    const args = ["-v", "error"];
+    for (const f of frameFiles)
+        args.push("-i", f);
+    args.push("-filter_complex", buildContactSheetFilterGraph(frameFiles.length, tileWidth, columns, rows), "-frames:v", "1", sheetPath, "-y");
+    return args;
+}
+async 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`;
+    // On Windows, npx is a .cmd shim spawned through cmd.exe (see spawnCapture in
+    // @openvidstudio/capture), which quote-wraps every argv entry rather than
+    // escaping it -- a compositionId override containing a `"` could otherwise
+    // break out of that quoting. pascalCase(videoName) can never produce one
+    // (sanitizeSegment already restricts videoName), so this only ever fires on
+    // an explicit, unsafe override.
+    if (!COMPOSITION_ID_RE.test(compositionId)) {
+        throw new Error(`compositionId "${compositionId}" is not safe (letters, numbers, "-", "_" only).`);
+    }
     const tileWidth = input.tileWidth ?? 480;
     const beatsFile = path.join(projectRoot, "src", "videos", videoName, "beats.json");
     if (!fs.existsSync(beatsFile)) {
@@ -52,7 +91,7 @@ function runContactSheet(input) {
     }
     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");
+    const outDir = path.join(projectRoot, "output", "contact");
     fs.mkdirSync(outDir, { recursive: true });
     const npx = process.platform === "win32" ? "npx.cmd" : "npx";
     const frames = [];
@@ -67,8 +106,12 @@ function runContactSheet(input) {
         }
         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)) {
+            // npx is a .cmd shim on Windows; spawnCapture (not a raw spawnSync) is what routes
+            // that one case through cmd.exe, the same fix renderVideo.ts/qcExtractFrames.ts
+            // already carry. Without it, spawnSync throws a synchronous EINVAL for every frame
+            // on Windows and every call below fails before ffmpeg's tile filter ever runs.
+            const r = await (0, util_1.spawnCapture)(npx, ["remotion", "still", compositionId, file, `--frame=${pick.frame}`, "--log=error"], projectRoot);
+            if (r.code === 0 && fs.existsSync(file)) {
                 frames.push({ beatId: beat.id, at: pick.at, frame: pick.frame, file });
             }
             else {
@@ -80,16 +123,12 @@ function runContactSheet(input) {
         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"));
+    const rows = Math.ceil(frames.length / columns);
+    const sheetPath = path.join(projectRoot, input.outPath ?? path.join("output", "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) {
+    const args = buildContactSheetArgs(frames.map((f) => f.file), tileWidth, columns, rows, sheetPath);
+    const tile = await (0, util_1.spawnCapture)("ffmpeg", args, projectRoot);
+    if (tile.code !== 0) {
         throw new Error(`ffmpeg could not tile the frames: ${(tile.stderr ?? "").slice(0, 300)}`);
     }
     return { sheetPath, frames, columns, failed };

package/dist/tools/diffBeats.d.ts

@@ -0,0 +1,48 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type BeatStatus = "added" | "removed" | "unchanged" | "changed";
+export interface BeatArtifactPresence {
+    screenshot: boolean;
+    recording: boolean;
+    vo: boolean;
+}
+export interface BeatDiff {
+    id: string;
+    status: BeatStatus;
+    changedFields: string[];
+    /** True when a capture tool (capture_screenshot/capture_screen_recording/import_higgsfield_clip) should rerun for this beat. */
+    needsRecapture: boolean;
+    /** True when scaffold_scene should rerun (overwrite: true) for this beat. */
+    needsRescaffold: boolean;
+    /** Whether each convention/override output path actually exists on disk right now, checked against the NEW beat's artifacts. */
+    artifactsOnDisk: BeatArtifactPresence;
+}
+export interface DiffBeatsResult {
+    fpsChanged: boolean;
+    titleChanged: boolean;
+    beats: BeatDiff[];
+    summary: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+    };
+    /** Remotion renders the whole composition every time; this is the one whole-video signal. */
+    rerenderNeeded: boolean;
+}
+/**
+ * Pure diff over two already-parsed beats.json documents. `projectRoot` is only used
+ * to check which artifact files actually exist on disk right now (a fresh checkout or
+ * a beat that's never been captured reports every path absent, which is correct, not
+ * a bug); it never reads oldBeatsJson/newBeatsJson from disk itself.
+ */
+export declare function diffBeatsLogic(oldBeatsJson: unknown, newBeatsJson: unknown, projectRoot: string): DiffBeatsResult;
+export interface DiffBeatsInput {
+    projectRoot?: string;
+    videoName: string;
+    newBeatsJson: unknown;
+}
+export type DiffBeatsToolResult = DiffBeatsResult & {
+    oldBeatsFileFound: boolean;
+};
+export declare function runDiffBeats(input: DiffBeatsInput): DiffBeatsToolResult;
+export declare function registerDiffBeats(server: McpServer): void;