@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/tools/preflight.js

@@ -33,14 +33,21 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_NODE_MAJOR = void 0;
+exports.buildBenchmarkArgs = buildBenchmarkArgs;
+exports.parseBenchmarkSeconds = parseBenchmarkSeconds;
+exports.checkNodeVersion = checkNodeVersion;
 exports.runPreflight = runPreflight;
 exports.registerPreflight = registerPreflight;
 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 capture_1 = require("@openvidstudio/capture");
 const util_1 = require("../util");
 const config_1 = require("../config");
+const stitchComposition_1 = require("./stitchComposition");
 const mcp_1 = require("./mcp");
 function which(cmd) {
     const probe = process.platform === "win32" ? "where" : "which";
@@ -56,6 +63,63 @@ function platformFix(win, mac, linux) {
         return mac;
     return linux;
 }
+const BENCHMARK_FRAMES = 60;
+/** Pure argv builder, unit-testable without spawning a real process. */
+function buildBenchmarkArgs(projectRoot, opts = {}) {
+    const frames = opts.frames ?? BENCHMARK_FRAMES;
+    const args = [
+        "remotion",
+        "benchmark",
+        path.join(projectRoot, "src", "index.ts"),
+        stitchComposition_1.PREFLIGHT_BENCHMARK_COMPOSITION_ID,
+        `--frames=0-${frames - 1}`,
+        "--width=1920",
+        "--height=1080",
+        "--runs=1",
+    ];
+    if (opts.browserExecutable)
+        args.push(`--browser-executable=${opts.browserExecutable}`);
+    return args;
+}
+/**
+ * Strips ANSI colour codes (the CLI has no machine-readable output mode) and reads the
+ * "Time (mean ± σ): X.XXXXXs" summary line `remotion benchmark` always prints at the end
+ * of a run.
+ */
+function parseBenchmarkSeconds(stdout) {
+    // eslint-disable-next-line no-control-regex
+    const plain = stdout.replace(/\x1b\[[0-9;]*m/g, "");
+    const m = /Time \(mean[^)]*\):\s+([\d.]+)s/.exec(plain);
+    return m ? Number.parseFloat(m[1]) : null;
+}
+async function runBenchmark(projectRoot, browserExecutable) {
+    const cpuCount = os.cpus().length;
+    if (!fs.existsSync(path.join(projectRoot, "src", "index.ts"))) {
+        return { ok: false, framesTimed: 0, secondsElapsed: 0, fps: 0, cpuCount, error: "src/index.ts not found -- run init_project first" };
+    }
+    const startedAt = Date.now();
+    const result = await (0, util_1.spawnCapture)(process.platform === "win32" ? "npx.cmd" : "npx", buildBenchmarkArgs(projectRoot, { browserExecutable }), projectRoot);
+    const wallSeconds = (Date.now() - startedAt) / 1000;
+    const seconds = parseBenchmarkSeconds(result.stdout) ?? parseBenchmarkSeconds(result.stderr);
+    if (seconds === null || seconds <= 0) {
+        return {
+            ok: false,
+            framesTimed: 0,
+            secondsElapsed: 0,
+            fps: 0,
+            cpuCount,
+            error: `could not parse a benchmark time from remotion's output: ${(result.stderr || result.stdout).slice(-1000)}`,
+        };
+    }
+    return {
+        ok: true,
+        framesTimed: BENCHMARK_FRAMES,
+        secondsElapsed: seconds,
+        fps: Number((BENCHMARK_FRAMES / seconds).toFixed(2)),
+        cpuCount,
+        bundleSeconds: Number(Math.max(0, wallSeconds - seconds).toFixed(1)),
+    };
+}
 async function urlResponds(url, timeoutMs = 4000) {
     try {
         const ctl = new AbortController();
@@ -68,17 +132,26 @@ async function urlResponds(url, timeoutMs = 4000) {
         return false;
     }
 }
+/** The oldest Node major openvidstudio supports. It matches the packages' `engines` field and what CI runs. */
+exports.MIN_NODE_MAJOR = 20;
+/** Whether a `process.versions.node` string is new enough, and what to tell the user if not. */
+function checkNodeVersion(version) {
+    const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
+    if (major >= exports.MIN_NODE_MAJOR)
+        return { ok: true };
+    return { ok: false, fix: `Install Node ${exports.MIN_NODE_MAJOR} or newer from nodejs.org.` };
+}
 async function runPreflight(input) {
     const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
     const config = (0, config_1.loadConfig)(projectRoot);
     const appUrl = input.appUrl ?? config.capture.appUrl;
     const checks = [];
-    const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    const nodeVersion = checkNodeVersion(process.versions.node);
     checks.push({
         name: "node",
-        ok: nodeMajor >= 18,
+        ok: nodeVersion.ok,
         detail: `node ${process.versions.node}`,
-        fix: nodeMajor >= 18 ? undefined : "Install Node 18 or newer from nodejs.org.",
+        fix: nodeVersion.fix,
         blocking: true,
     });
     const ffmpeg = which("ffmpeg");
@@ -92,7 +165,12 @@ async function runPreflight(input) {
         blocking: true,
     });
     // Playwright keeps its browsers in a per-user cache; the surest check is asking it.
-    const pw = (0, node_child_process_1.spawnSync)(process.platform === "win32" ? "npx.cmd" : "npx", ["playwright", "--version"], { cwd: projectRoot, encoding: "utf8" });
+    // On Windows, npx is a .cmd shim, and Node refuses to spawn a batch file with shell:false
+    // (EINVAL), which reported Playwright as missing even when it was installed. The command is a
+    // fixed string with no user input, so routing it through cmd.exe is safe.
+    const pw = process.platform === "win32"
+        ? (0, node_child_process_1.spawnSync)("npx playwright --version", { cwd: projectRoot, encoding: "utf8", shell: true })
+        : (0, node_child_process_1.spawnSync)("npx", ["playwright", "--version"], { cwd: projectRoot, encoding: "utf8" });
     const pwOk = pw.status === 0;
     checks.push({
         name: "playwright",
@@ -101,19 +179,72 @@ async function runPreflight(input) {
         fix: pwOk ? undefined : "npm install playwright && npx playwright install chromium",
         blocking: true,
     });
-    const cacheDirs = [
-        path.join(process.env.LOCALAPPDATA ?? "", "ms-playwright"),
-        path.join(process.env.HOME ?? "", ".cache", "ms-playwright"),
-        path.join(process.env.HOME ?? "", "Library", "Caches", "ms-playwright"),
-    ].filter(Boolean);
-    const chromium = cacheDirs.some((d) => fs.existsSync(d) && fs.readdirSync(d).some((e) => e.startsWith("chromium")));
+    // Resolved the same way real capture actually launches it (@openvidstudio/capture's
+    // browser.ts, the module captureScreenshot.ts/captureScreenRecording.ts both call into),
+    // not a second, separately guessed lookup. Guessing fixed OS cache dirs (the old approach)
+    // reported "no chromium" whenever browsers lived under PLAYWRIGHT_BROWSERS_PATH instead, and
+    // could report OK on a *different* chromium build than the one this exact resolution wants
+    // (a version mismatch: the server's playwright expects one build, the machine has an older
+    // one already downloaded from a previous playwright version). executablePath() embeds the
+    // exact expected build revision in the path it returns (e.g. ".../chromium-1243/..."), so
+    // fs.existsSync() on it catches both cases the old check missed.
+    let chromiumPath = null;
+    let chromiumResolveError = null;
+    try {
+        chromiumPath = capture_1.chromium.executablePath();
+    }
+    catch (err) {
+        chromiumResolveError = err instanceof Error ? err.message : String(err);
+    }
+    const playwrightVersion = (() => {
+        try {
+            return (0, capture_1.resolvedPlaywrightVersion)();
+        }
+        catch {
+            return "unknown";
+        }
+    })();
+    const chromiumOk = chromiumPath !== null && fs.existsSync(chromiumPath);
     checks.push({
         name: "chromium",
-        ok: chromium,
-        detail: chromium ? "browser binaries present" : "no chromium build in the Playwright cache",
-        fix: chromium ? undefined : "npx playwright install chromium",
+        ok: chromiumOk,
+        detail: chromiumOk
+            ? `resolved build present at ${chromiumPath} (playwright ${playwrightVersion})`
+            : chromiumPath
+                ? `playwright ${playwrightVersion} expects a build at ${chromiumPath}, which does not exist` +
+                    (process.env.PLAYWRIGHT_BROWSERS_PATH
+                        ? ` (PLAYWRIGHT_BROWSERS_PATH=${process.env.PLAYWRIGHT_BROWSERS_PATH})`
+                        : "")
+                : `could not resolve Chromium's executable path (playwright ${playwrightVersion}): ${chromiumResolveError}`,
+        fix: chromiumOk ? undefined : "npx playwright install chromium",
         blocking: true,
     });
+    // render.browserExecutable (openvidstudio.config.json) is what render_video actually
+    // passes to Remotion's --browser-executable when set, instead of letting Remotion manage
+    // its own chrome-headless-shell download -- check that exact path too, separately from
+    // the chromium check above, since a project can have real Playwright Chromium (the
+    // "chromium" check passes) while still pointing render.browserExecutable at something
+    // stale or never configured for this machine.
+    if (config.render.browserExecutable) {
+        const configuredOk = fs.existsSync(config.render.browserExecutable);
+        checks.push({
+            name: "render.browserExecutable",
+            ok: configuredOk,
+            detail: configuredOk
+                ? `${config.render.browserExecutable} exists; render_video will pass --browser-executable to reuse it`
+                : `openvidstudio.config.json sets render.browserExecutable to ${config.render.browserExecutable}, which does not exist`,
+            fix: configuredOk
+                ? undefined
+                : chromiumOk
+                    ? `Point render.browserExecutable at the resolved build instead: ${chromiumPath}`
+                    : "Fix the \"chromium\" check above first, then point render.browserExecutable at its resolved path.",
+            blocking: true,
+        });
+    }
+    let benchmarkResult;
+    if (input.benchmark) {
+        benchmarkResult = await runBenchmark(projectRoot, config.render.browserExecutable);
+    }
     const responds = await urlResponds(appUrl);
     checks.push({
         name: "app",
@@ -150,21 +281,58 @@ async function runPreflight(input) {
         fix: narration ? undefined : "pip install edge-tts",
         blocking: false,
     });
+    // compose_score needs a real python with its DSP stack importable, not just a python on
+    // PATH, so this checks the same import line the tool itself depends on rather than
+    // guessing from the interpreter's presence alone. Same python-then-python3 fallback order
+    // composeScore.ts uses internally. Non-blocking: a video with no original score still
+    // renders, same reasoning as the narration check above.
+    const composeScorePython = which("python") ? "python" : which("python3") ? "python3" : null;
+    const composeScoreDeps = composeScorePython
+        ? (0, node_child_process_1.spawnSync)(composeScorePython, ["-c", "import numpy, scipy, soundfile, pyloudnorm, matplotlib"], { encoding: "utf8" })
+        : null;
+    const composeScoreOk = composeScorePython !== null && composeScoreDeps?.status === 0;
+    checks.push({
+        name: "compose-score-deps",
+        ok: composeScoreOk,
+        detail: composeScoreOk
+            ? `${composeScorePython} has numpy, scipy, soundfile, pyloudnorm and matplotlib importable`
+            : composeScorePython
+                ? `${composeScorePython} is missing one or more of numpy/scipy/soundfile/pyloudnorm/matplotlib`
+                : "no python or python3 on PATH",
+        fix: composeScoreOk
+            ? undefined
+            : `${composeScorePython ?? "python"} -m pip install numpy scipy soundfile pyloudnorm matplotlib`,
+        blocking: false,
+    });
     const blockers = checks.filter((c) => !c.ok && c.blocking).map((c) => `${c.name}: ${c.fix ?? c.detail}`);
-    return { ok: blockers.length === 0, platform: process.platform, checks, blockers };
+    return {
+        ok: blockers.length === 0,
+        platform: process.platform,
+        checks,
+        blockers,
+        ...(benchmarkResult ? { benchmarkResult } : {}),
+    };
 }
 function registerPreflight(server) {
     server.registerTool("preflight", {
         title: "Check the machine can actually run the pipeline",
         description: "Verifies node, ffmpeg, Playwright and its Chromium build, that the app you want to film is " +
             "responding, that the project directory is writable, and that a narration engine is available. " +
+            "If openvidstudio.config.json sets render.browserExecutable, also checks that exact path exists, " +
+            "separately from the chromium check (render_video passes it to Remotion as --browser-executable " +
+            "so a render reuses that browser instead of downloading its own, which fails with no network). " +
             "Every failure names the fix with the command for this platform, rather than describing a symptom. " +
             "Run it before init_project on a new machine: without it a missing dependency surfaces several " +
             "steps later, often after a long render has already started. Narration is reported as non blocking, " +
-            "since a silent video still renders.",
+            "since a silent video still renders. Pass benchmark: true to also render ~60 frames of a fixed " +
+            "benchmark composition (init_project seeds it, so this works even before any real video is planned) " +
+            "and report real frames/sec plus CPU count in benchmarkResult -- off by default since it costs a " +
+            "real 10-20s render; plan_production turns it on when it needs a measured fps to base a time " +
+            "estimate on rather than guessing one.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),
             appUrl: zod_1.z.string().optional(),
+            benchmark: zod_1.z.boolean().optional(),
         },
     }, async (input) => (0, mcp_1.runTool)("preflight", () => runPreflight(input)));
 }

package/dist/tools/qcCapture.d.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Flags capture artifacts that are technically present but wrong in a way nothing else
+ * catches before the render, run over what's on disk plus beats.json -- before scaffolding,
+ * unlike validate_scenes (which needs a scene file to exist first). The three failure
+ * modes here are all silent: the capture succeeds, the file is on disk, and the defect is
+ * only visible once someone actually watches the frame.
+ *
+ * 1. A screenshot smaller than the frame templates.ts's browser-capture template will
+ *    build from it. FRAME_W there is `Math.min(1200, w + 80)`: below 1200px native width,
+ *    the frame is already larger than the source at rest, before any camera push -- this
+ *    reuses that exact formula rather than a separate guessed threshold, so it agrees with
+ *    what scaffold_scene will actually do.
+ * 2. A recording (or screenshot) whose own `<asset>.settle.json` sidecar says
+ *    `settled: false` -- the same signal validate_scenes already reads post-scaffold,
+ *    checked here pre-scaffold instead of inventing a new heuristic for "still loading".
+ * 3. A terminal cast capture_terminal marked truncated. TerminalCast has no `truncated`
+ *    field of its own (see @openvidstudio/capture's terminal.ts) -- truncation is recorded
+ *    as a literal `"[openvidstudio: output truncated]"` marker pushed into `events`, which
+ *    is what's actually checked here, not a field that doesn't exist on disk.
+ */
+export interface QcCaptureInput {
+    projectRoot?: string;
+    videoName: string;
+}
+export interface QcFinding {
+    beatId: string;
+    asset: string;
+    severity: "error" | "warning";
+    message: string;
+}
+export interface QcCaptureResult {
+    ok: boolean;
+    assetsChecked: number;
+    findings: QcFinding[];
+}
+export declare function runQcCapture(input: QcCaptureInput): QcCaptureResult;
+export declare function registerQcCapture(server: McpServer): void;

package/dist/tools/qcCapture.js

@@ -0,0 +1,206 @@
+"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.runQcCapture = runQcCapture;
+exports.registerQcCapture = registerQcCapture;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const capture_1 = require("@openvidstudio/capture");
+const pngSize_1 = require("../scenes/pngSize");
+const mcp_1 = require("./mcp");
+/** Below this native pixel width, templates.ts's own FRAME_W formula already upscales the
+ * frame at rest (Math.min(1200, w + 80) > w for any w < 1200) -- this is that same formula's
+ * crossover point, not a separately chosen number. */
+const MIN_SCREENSHOT_WIDTH = 1200;
+/** A capture this short is almost certainly broken (a blank/near-instant screenshot), not a
+ * legitimately tiny frame -- catches a bad crop or a zero-content page distinctly from the
+ * resolution check above. */
+const MIN_SCREENSHOT_HEIGHT = 200;
+const TRUNCATED_MARKER = "[openvidstudio: output truncated]";
+function readSettleSidecar(assetPathAbs) {
+    const sidecarPath = (0, capture_1.settleSidecarPath)(assetPathAbs);
+    if (!fs.existsSync(sidecarPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(sidecarPath, "utf8"));
+    }
+    catch {
+        return null; // Malformed sidecar: not this tool's job to diagnose, skip rather than crash.
+    }
+}
+function pendingSummary(report) {
+    const pending = [];
+    if (!report.fontsReady)
+        pending.push("fonts");
+    if (!report.imagesReady)
+        pending.push("images");
+    if (report.pendingAnimations > 0)
+        pending.push(`${report.pendingAnimations} animation(s)`);
+    return pending.join(", ") || "unknown";
+}
+function runQcCapture(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 findings = [];
+    let checked = 0;
+    for (const beat of doc.beats) {
+        const method = beat.visual?.captureMethod;
+        const source = beat.visual?.source ?? "browser";
+        const artifacts = beat.artifacts ?? {};
+        if (method === "screenshot" && source === "browser") {
+            const rel = artifacts.screenshotPath ?? path.join("public", "images", `${beat.id}.png`);
+            const assetPathAbs = path.join(projectRoot, rel);
+            if (!fs.existsSync(assetPathAbs))
+                continue; // Not captured yet -- nothing to QC.
+            checked++;
+            const size = (0, pngSize_1.pngSize)(assetPathAbs);
+            if (size) {
+                if (size.width < MIN_SCREENSHOT_WIDTH) {
+                    findings.push({
+                        beatId: beat.id,
+                        asset: rel,
+                        severity: "warning",
+                        message: `${size.width}px native width is below the ${MIN_SCREENSHOT_WIDTH}px the browser-capture scene ` +
+                            `template will build a frame from (FRAME_W = min(1200, w + 80)); the frame will be visibly soft ` +
+                            `even before any camera push. Re-capture at a wider viewport, or raise deviceScaleFactor.`,
+                    });
+                }
+                if (size.height < MIN_SCREENSHOT_HEIGHT) {
+                    findings.push({
+                        beatId: beat.id,
+                        asset: rel,
+                        severity: "error",
+                        message: `${size.height}px native height is suspiciously small for a real capture -- looks like a broken or empty crop, not a legitimately short beat.`,
+                    });
+                }
+            }
+            else {
+                findings.push({
+                    beatId: beat.id,
+                    asset: rel,
+                    severity: "error",
+                    message: `Could not read PNG dimensions from ${rel} -- the file may be missing its PNG header or corrupted.`,
+                });
+            }
+            const settle = readSettleSidecar(assetPathAbs);
+            if (settle && !settle.settled) {
+                findings.push({
+                    beatId: beat.id,
+                    asset: rel,
+                    severity: "error",
+                    message: `Settle timed out after ${settle.waitedMs}ms, still pending: ${pendingSummary(settle)}. The frame may still be a loading state, not the product's real one. Re-run capture_screenshot with a larger settleTimeoutMs.`,
+                });
+            }
+        }
+        if (method === "recording" && source !== "terminal") {
+            const rel = artifacts.recordingPath ?? path.join("public", "video", `${beat.id}.mp4`);
+            const assetPathAbs = path.join(projectRoot, rel);
+            if (!fs.existsSync(assetPathAbs))
+                continue;
+            checked++;
+            // Settling is a browser-capture concept: capture_desktop/mobile have no settlePage
+            // call and never write this sidecar, so there is nothing to check for those sources.
+            if (source === "browser") {
+                const settle = readSettleSidecar(assetPathAbs);
+                if (settle && !settle.settled) {
+                    findings.push({
+                        beatId: beat.id,
+                        asset: rel,
+                        severity: "error",
+                        message: `Settle timed out after ${settle.waitedMs}ms, still pending: ${pendingSummary(settle)}. The opening of this recording may still show a loading state instead of the product working. Re-run capture_screen_recording with a larger settleTimeoutMs.`,
+                    });
+                }
+            }
+        }
+        if (source === "terminal") {
+            const rel = artifacts.terminalPath ?? path.join("public", "terminal", `${beat.id}.json`);
+            const assetPathAbs = path.join(projectRoot, rel);
+            if (!fs.existsSync(assetPathAbs))
+                continue;
+            checked++;
+            try {
+                const cast = JSON.parse(fs.readFileSync(assetPathAbs, "utf8"));
+                const truncatedEvent = cast.events?.find(([, , text]) => text.includes(TRUNCATED_MARKER));
+                if (truncatedEvent) {
+                    findings.push({
+                        beatId: beat.id,
+                        asset: rel,
+                        severity: "error",
+                        message: `Cast was truncated (capture_terminal's maxOutputChars or retention cap was hit) -- the replay will end mid-output rather than at the command's real completion. Re-run with a larger maxOutputChars, or trim the command to what actually fits a beat.`,
+                    });
+                }
+            }
+            catch {
+                findings.push({
+                    beatId: beat.id,
+                    asset: rel,
+                    severity: "error",
+                    message: `Could not parse ${rel} as a terminal cast -- the file may be missing or malformed.`,
+                });
+            }
+        }
+    }
+    return { ok: !findings.some((f) => f.severity === "error"), assetsChecked: checked, findings };
+}
+function registerQcCapture(server) {
+    server.registerTool("qc_capture", {
+        title: "Flag capture artifacts that are present but wrong",
+        description: "Runs over capture artifacts already on disk (plus beats.json) before scaffolding, checking what " +
+            "succeeding at capture time doesn't guarantee: (a) a screenshot narrower than 1200px native width, " +
+            "the exact crossover where templates.ts's own browser-capture FRAME_W formula (min(1200, w + 80)) " +
+            "starts upscaling the frame at rest, before any camera push -- warning, since it is visible softness " +
+            "not a broken file, plus an error if height is under 200px (looks like a broken/empty crop); (b) a " +
+            "screenshot or recording whose `<asset>.settle.json` sidecar reports settled: false (the same signal " +
+            "validate_scenes reads post-scaffold, reused here rather than a new heuristic for 'still looks like " +
+            "loading') -- error, the opening frame may not be the product's real state; (c) a terminal cast " +
+            "capture_terminal marked truncated, detected by the literal " +
+            "\"[openvidstudio: output truncated]\" marker event it pushes into `events` (TerminalCast has no " +
+            "boolean truncated field of its own) -- error, the replay ends mid-output. A beat with no artifact " +
+            "on disk yet is skipped, not flagged: this tool checks what exists, it doesn't require everything to " +
+            "already be captured. Returns { ok, assetsChecked, findings } with every failure found, never just " +
+            "the first.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+        },
+    }, async (input) => (0, mcp_1.runTool)("qc_capture", () => runQcCapture(input)));
+}

package/dist/tools/qcExtractFrames.d.ts

@@ -6,20 +6,50 @@ export interface QcExtractFramesInput {
 }
 export interface QcFrame {
     beatId: string;
-    midPath: string;
-    endPath: string;
+    /** Absolute path to the extracted midpoint frame, or null if extraction produced no file. */
+    midPath: string | null;
+    /** Set only when midPath is null: why the extraction didn't produce a usable frame. */
+    midError?: string;
+    /** Absolute path to the extracted end frame, or null if extraction produced no file. */
+    endPath: string | null;
+    /** Set only when endPath is null: why the extraction didn't produce a usable frame. */
+    endError?: string;
 }
 export interface QcExtractFramesResult {
     frames: QcFrame[];
+    /** Plain-language entry per failed extraction (same beats as the null path fields above). */
+    warnings?: string[];
 }
-/** Pure argv builder, unit-testable without spawning ffmpeg. */
-export declare function buildFfmpegFrameArgs(videoPath: string, timestampSeconds: number, outFile: string): string[];
+/**
+ * Pure argv builder, unit-testable without spawning ffmpeg.
+ *
+ * Extracts by frame INDEX, not by seeking to a timestamp. The previous version converted
+ * a frame number to `frame/fps` seconds and asked ffmpeg's accurate-seek to land on "the
+ * frame at or after time T" -- but any rounding that pushes T even a fraction of a
+ * millisecond past the target frame's true PTS makes accurate-seek skip it and return the
+ * NEXT frame instead (for the last frame in the whole file, there is no next frame to land
+ * on, so ffmpeg writes nothing at all). Frame counting sidesteps this entirely: `-vf
+ * select=eq(n,N)` asks for the Nth frame ffmpeg actually decodes, an integer comparison
+ * with no rounding boundary to trip over.
+ *
+ * `-ss` (input-level, before `-i`) is still used, but only as a coarse, deliberately-early
+ * jump to skip most of the file for speed, never as the thing that has to land exactly on
+ * the target frame. `marginFrames` frames before the target (about a second's worth, or
+ * fewer near the start of the file) is always FLOORED to microsecond precision, never
+ * rounded to nearest, so the seek can only land at-or-before its own frame boundary, never
+ * past it. `N` for the select filter is then the constant, exactly-known `marginFrames`,
+ * never anything derived from comparing two timestamps.
+ */
+export declare function buildFfmpegFrameArgs(videoPath: string, targetFrame: number, fps: number, outFile: string): string[];
 /**
  * Wraps PIPELINE.md's QC frame-extraction step. For every beat, computes both its
  * midpoint frame AND its end frame (a static crop that looks fine early can push
  * content off-frame once the camera has zoomed in, so the end matters too, not just
- * the midpoint), converts to timestamps using the beats file's fps, and shells out to
- * ffmpeg via spawn with an argv array.
+ * the midpoint), extracts each by frame index (see buildFfmpegFrameArgs), and shells out
+ * to ffmpeg via spawn with an argv array. A beat whose extraction produced no real file
+ * (ffmpeg can exit 0 while writing nothing, e.g. a seek that lands past the video's real
+ * length) gets a null path and an explicit `*Error` entry instead of a phantom path that
+ * looks like it exists but doesn't.
  */
 export declare function runQcExtractFrames(input: QcExtractFramesInput): Promise<QcExtractFramesResult>;
 export declare function registerQcExtractFrames(server: McpServer): void;