@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/qcExtractFrames.js

@@ -41,14 +41,43 @@ const path = __importStar(require("node:path"));
 const zod_1 = require("zod");
 const util_1 = require("../util");
 const mcp_1 = require("./mcp");
-/** Pure argv builder, unit-testable without spawning ffmpeg. */
-function buildFfmpegFrameArgs(videoPath, timestampSeconds, outFile) {
+/**
+ * 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.
+ */
+function buildFfmpegFrameArgs(videoPath, targetFrame, fps, outFile) {
+    const marginFrames = Math.min(targetFrame, Math.max(1, Math.round(fps)));
+    const seekFrame = targetFrame - marginFrames;
+    // Floor (never round-to-nearest) so the requested seek time is never greater than the
+    // seek frame's true PTS -- rounding up by even one ULP is what causes accurate-seek to
+    // skip past the intended frame.
+    const seekSeconds = Math.floor((seekFrame / fps) * 1e6) / 1e6;
     return [
         "-nostdin",
         "-ss",
-        timestampSeconds.toFixed(3),
+        seekSeconds.toFixed(6),
         "-i",
         videoPath,
+        "-vf",
+        `select=eq(n\\,${marginFrames})`,
+        "-vsync",
+        "0",
         "-frames:v",
         "1",
         "-q:v",
@@ -61,8 +90,11 @@ function buildFfmpegFrameArgs(videoPath, timestampSeconds, outFile) {
  * 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.
  */
 async function runQcExtractFrames(input) {
     const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
@@ -78,48 +110,69 @@ async function runQcExtractFrames(input) {
         throw new Error(`${beatsPath} has no beats.`);
     }
     const fps = beatsData.fps ?? 30;
-    const videoPathRel = input.videoPath ?? path.join("out", `${videoName}.mp4`);
+    const videoPathRel = input.videoPath ?? path.join("output", `${videoName}.mp4`);
     (0, util_1.sanitizeRelativeOutPath)(projectRoot, videoPathRel, "videoPath");
     const videoPathAbs = path.join(projectRoot, videoPathRel);
     if (!fs.existsSync(videoPathAbs)) {
         throw new Error(`${videoPathAbs} does not exist. Call render_video first (or pass an explicit videoPath).`);
     }
-    const outDirRel = path.join("out", "qc", videoName);
+    const outDirRel = path.join("output", "qc", videoName);
     (0, util_1.sanitizeRelativeOutPath)(projectRoot, outDirRel, "outDir");
     const outDirAbs = path.join(projectRoot, outDirRel);
     fs.mkdirSync(outDirAbs, { recursive: true });
+    /**
+     * Runs ffmpeg for one frame and verifies it actually produced a usable file. ffmpeg can
+     * exit 0 having written nothing (or an empty file) if the requested frame doesn't exist
+     * in the stream; a non-zero exit is caught the same way. Either way, this beat's field
+     * gets `path: null` plus a plain-language reason instead of a path to a file that isn't
+     * really there.
+     */
+    async function extractFrame(targetFrame, outFile, beatId, which) {
+        const result = await (0, util_1.spawnCapture)("ffmpeg", buildFfmpegFrameArgs(videoPathAbs, targetFrame, fps, outFile), projectRoot);
+        const wroteRealFile = fs.existsSync(outFile) && fs.statSync(outFile).size > 0;
+        if (result.code === 0 && wroteRealFile) {
+            return { path: outFile };
+        }
+        const reason = result.code !== 0
+            ? `ffmpeg exited ${result.code}: ${result.stderr.slice(-500)}`
+            : "ffmpeg exited 0 but wrote no usable frame (missing or empty output) -- the target frame may be past the video's real length";
+        return { path: null, error: `${beatId} (${which}): ${reason}` };
+    }
     const frames = [];
-    const failures = [];
+    const warnings = [];
     for (const beat of beats) {
-        const midFrame = beat.start + beat.duration / 2;
-        const endFrame = beat.start + beat.duration - 1;
+        const midFrame = Math.round(beat.start + beat.duration / 2);
+        const endFrame = Math.round(beat.start + beat.duration - 1);
         const midPath = path.join(outDirAbs, `${beat.id}-mid.jpg`);
         const endPath = path.join(outDirAbs, `${beat.id}-end.jpg`);
-        const midResult = await (0, util_1.spawnCapture)("ffmpeg", buildFfmpegFrameArgs(videoPathAbs, midFrame / fps, midPath), projectRoot);
-        if (midResult.code !== 0) {
-            failures.push(`${beat.id} (mid): ffmpeg exited ${midResult.code}: ${midResult.stderr.slice(-500)}`);
-        }
-        const endResult = await (0, util_1.spawnCapture)("ffmpeg", buildFfmpegFrameArgs(videoPathAbs, endFrame / fps, endPath), projectRoot);
-        if (endResult.code !== 0) {
-            failures.push(`${beat.id} (end): ffmpeg exited ${endResult.code}: ${endResult.stderr.slice(-500)}`);
-        }
-        frames.push({ beatId: beat.id, midPath, endPath });
-    }
-    if (failures.length > 0) {
-        throw new Error(`ffmpeg frame extraction failed for:\n${failures.join("\n")}`);
+        const mid = await extractFrame(midFrame, midPath, beat.id, "mid");
+        const end = await extractFrame(endFrame, endPath, beat.id, "end");
+        if (mid.error)
+            warnings.push(mid.error);
+        if (end.error)
+            warnings.push(end.error);
+        frames.push({
+            beatId: beat.id,
+            midPath: mid.path,
+            ...(mid.error ? { midError: mid.error } : {}),
+            endPath: end.path,
+            ...(end.error ? { endError: end.error } : {}),
+        });
     }
-    return { frames };
+    return warnings.length > 0 ? { frames, warnings } : { frames };
 }
 function registerQcExtractFrames(server) {
     server.registerTool("qc_extract_frames", {
         title: "Extract QC frames for every beat",
         description: "Wraps PIPELINE.md's QC frame-extraction step. Reads beats.json, and for every beat computes its " +
             "midpoint frame AND its end frame (PIPELINE.md's QC checklist specifically calls out checking the " +
-            "end of every real-screenshot/recording beat, not just the midpoint), converts frame numbers to " +
-            "timestamps using the beats file's fps, and shells out to ffmpeg per beat via child_process.spawn " +
-            "with an argv array (never a shell string). Default videoPath is out/<videoName>.mp4, default " +
-            "output dir is out/qc/<videoName>/. Returns { frames: [{ beatId, midPath, endPath }] } so the " +
-            "calling agent knows exactly which paths to Read as images for its own visual QC pass.",
+            "end of every real-screenshot/recording beat, not just the midpoint), extracts each by frame index " +
+            "(never by seeking to a timestamp, which is frame-inexact at the boundary) and shells out to ffmpeg " +
+            "per beat via child_process.spawn with an argv array (never a shell string). Default videoPath is " +
+            "output/<videoName>.mp4, default output dir is output/qc/<videoName>/. Returns " +
+            "{ frames: [{ beatId, midPath, endPath }], warnings? }: a beat whose extraction produced no real " +
+            "file gets midPath/endPath: null plus a matching midError/endError explaining why, never a path " +
+            "that looks valid but points at nothing -- check warnings for a flat list of the same failures.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),
             videoName: zod_1.z.string().min(1),

package/dist/tools/reformatVertical.d.ts

@@ -0,0 +1,112 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Reformats a finished 16:9 composition to 9:16, with the crop decided per beat from the
+ * manifest rather than by taking the middle of the frame.
+ *
+ * Automated reframing usually looks wrong for one reason: a fixed centre crop does not
+ * know what is on screen. A terminal is text pinned to the left, so centring it cuts the
+ * command in half. A phone recording is already portrait and needs no crop at all, only
+ * padding. A constructed panel really is centred. The manifest already records which of
+ * those each beat is, so the crop can follow the content instead of guessing at it.
+ *
+ * A beat can override the inference with `vertical.focus` or an explicit `vertical.crop`
+ * rectangle, which is the escape hatch for the case where the content is off to one side
+ * for a reason the manifest cannot see.
+ *
+ * Active speaker tracking, the full version of this, needs real face and audio analysis
+ * and is deliberately out of scope. This is the manifest-driven crop, which is achievable
+ * now and useful on its own.
+ */
+export type CropFocus = "left" | "center" | "right";
+export interface CropRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface VerticalBeat {
+    id: string;
+    start: number;
+    duration: number;
+    visual?: {
+        captureMethod?: string;
+        source?: string;
+    };
+    vertical?: {
+        focus?: CropFocus;
+        crop?: CropRect;
+    };
+}
+export interface ReformatVerticalInput {
+    projectRoot?: string;
+    videoName: string;
+    inPath?: string;
+    outPath?: string;
+    /** Target frame. Defaults to 1080x1920, which every short-form platform accepts. */
+    width?: number;
+    height?: number;
+}
+export interface BeatCrop {
+    beatId: string;
+    focus: CropFocus;
+    crop: CropRect;
+    reason: string;
+    startSeconds: number;
+    endSeconds: number;
+}
+export interface ReformatVerticalResult {
+    outPath: string;
+    width: number;
+    height: number;
+    sourceWidth: number;
+    sourceHeight: number;
+    beats: BeatCrop[];
+    elapsedSeconds: number;
+}
+/**
+ * What the manifest implies about where the content of a beat sits.
+ *
+ * These are defaults, not laws: every one of them is overridable per beat, and the reason
+ * is reported back so a wrong guess is visible in the result rather than only in the file.
+ */
+export declare function inferFocus(beat: VerticalBeat): {
+    focus: CropFocus;
+    reason: string;
+};
+/**
+ * The largest rectangle of the target aspect that fits in the source, positioned by focus.
+ *
+ * Even dimensions and even offsets throughout: h264 in yuv420p subsamples chroma 2x2, and
+ * an odd crop fails at the encoder with an error that says nothing about the real cause.
+ */
+export declare function cropRect(sourceWidth: number, sourceHeight: number, targetWidth: number, targetHeight: number, focus: CropFocus): CropRect;
+export declare function planCrops(opts: {
+    beats: VerticalBeat[];
+    fps: number;
+    sourceWidth: number;
+    sourceHeight: number;
+    targetWidth: number;
+    targetHeight: number;
+}): BeatCrop[];
+/**
+ * One filter_complex that trims the source per beat, crops each slice on its own terms,
+ * and concatenates the result.
+ *
+ * Done in a single pass rather than as N renders plus a join: the crop differs per beat but
+ * the encode does not, so there is nothing to gain from writing intermediates and a
+ * generation of quality to lose.
+ *
+ * `force_original_aspect_ratio=decrease` plus a pad is what handles a beat whose source is
+ * already portrait (a phone recording): it fits rather than stretches, and the letterbox is
+ * black instead of a distorted face.
+ */
+export declare function buildVerticalFilterGraph(crops: BeatCrop[], targetWidth: number, targetHeight: number, hasAudio: boolean): string;
+export declare function buildReformatArgs(inPath: string, outPath: string, filterGraph: string, hasAudio: boolean): string[];
+export declare function buildProbeArgs(inPath: string): string[];
+export declare function parseProbe(stdout: string): {
+    width: number;
+    height: number;
+    hasAudio: boolean;
+};
+export declare function runReformatVertical(input: ReformatVerticalInput): Promise<ReformatVerticalResult>;
+export declare function registerReformatVertical(server: McpServer): void;

package/dist/tools/reformatVertical.js

@@ -0,0 +1,260 @@
+"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.inferFocus = inferFocus;
+exports.cropRect = cropRect;
+exports.planCrops = planCrops;
+exports.buildVerticalFilterGraph = buildVerticalFilterGraph;
+exports.buildReformatArgs = buildReformatArgs;
+exports.buildProbeArgs = buildProbeArgs;
+exports.parseProbe = parseProbe;
+exports.runReformatVertical = runReformatVertical;
+exports.registerReformatVertical = registerReformatVertical;
+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");
+/**
+ * What the manifest implies about where the content of a beat sits.
+ *
+ * These are defaults, not laws: every one of them is overridable per beat, and the reason
+ * is reported back so a wrong guess is visible in the result rather than only in the file.
+ */
+function inferFocus(beat) {
+    if (beat.vertical?.focus) {
+        return { focus: beat.vertical.focus, reason: "the beat sets vertical.focus explicitly" };
+    }
+    const source = beat.visual?.source ?? "browser";
+    if (source === "terminal") {
+        return {
+            focus: "left",
+            reason: "a terminal is text pinned to the left margin, so a centre crop cuts the command in half",
+        };
+    }
+    if (source === "mobile") {
+        return { focus: "center", reason: "a phone recording is already portrait, so the crop is a no-op" };
+    }
+    if (beat.visual?.captureMethod === "dom-demo") {
+        return { focus: "center", reason: "a constructed panel is laid out centred on the stage" };
+    }
+    return { focus: "center", reason: "a browser capture has no side the manifest knows to prefer" };
+}
+/**
+ * Sizes and offsets round down to even, but a size may never round to zero: a 1px-wide
+ * crop is useless and a 0px-wide one is an ffmpeg error, while a 0 offset is correct and
+ * common (it is exactly what a left-focused crop wants).
+ */
+const evenSize = (n) => Math.max(2, Math.floor(n / 2) * 2);
+const evenOffset = (n) => Math.max(0, Math.floor(n / 2) * 2);
+/**
+ * The largest rectangle of the target aspect that fits in the source, positioned by focus.
+ *
+ * Even dimensions and even offsets throughout: h264 in yuv420p subsamples chroma 2x2, and
+ * an odd crop fails at the encoder with an error that says nothing about the real cause.
+ */
+function cropRect(sourceWidth, sourceHeight, targetWidth, targetHeight, focus) {
+    const targetRatio = targetWidth / targetHeight;
+    let width = evenSize(Math.round(sourceHeight * targetRatio));
+    let height = evenSize(sourceHeight);
+    if (width > sourceWidth) {
+        width = evenSize(sourceWidth);
+        height = evenSize(Math.round(sourceWidth / targetRatio));
+    }
+    const x = focus === "left"
+        ? 0
+        : focus === "right"
+            ? evenOffset(sourceWidth - width)
+            : evenOffset(Math.round((sourceWidth - width) / 2));
+    const y = evenOffset(Math.round((sourceHeight - height) / 2));
+    return { x, y, width, height };
+}
+function planCrops(opts) {
+    return opts.beats.map((beat) => {
+        const { focus, reason } = inferFocus(beat);
+        const crop = beat.vertical?.crop ??
+            cropRect(opts.sourceWidth, opts.sourceHeight, opts.targetWidth, opts.targetHeight, focus);
+        return {
+            beatId: beat.id,
+            focus,
+            crop: beat.vertical?.crop
+                ? {
+                    x: evenOffset(beat.vertical.crop.x),
+                    y: evenOffset(beat.vertical.crop.y),
+                    width: evenSize(beat.vertical.crop.width),
+                    height: evenSize(beat.vertical.crop.height),
+                }
+                : crop,
+            reason: beat.vertical?.crop ? "the beat sets an explicit vertical.crop rectangle" : reason,
+            startSeconds: beat.start / opts.fps,
+            endSeconds: (beat.start + beat.duration) / opts.fps,
+        };
+    });
+}
+/**
+ * One filter_complex that trims the source per beat, crops each slice on its own terms,
+ * and concatenates the result.
+ *
+ * Done in a single pass rather than as N renders plus a join: the crop differs per beat but
+ * the encode does not, so there is nothing to gain from writing intermediates and a
+ * generation of quality to lose.
+ *
+ * `force_original_aspect_ratio=decrease` plus a pad is what handles a beat whose source is
+ * already portrait (a phone recording): it fits rather than stretches, and the letterbox is
+ * black instead of a distorted face.
+ */
+function buildVerticalFilterGraph(crops, targetWidth, targetHeight, hasAudio) {
+    const parts = [];
+    crops.forEach((c, i) => {
+        parts.push(`[0:v]trim=start=${c.startSeconds.toFixed(4)}:end=${c.endSeconds.toFixed(4)},setpts=PTS-STARTPTS,` +
+            `crop=${c.crop.width}:${c.crop.height}:${c.crop.x}:${c.crop.y},` +
+            `scale=${targetWidth}:${targetHeight}:force_original_aspect_ratio=decrease,` +
+            `pad=${targetWidth}:${targetHeight}:(ow-iw)/2:(oh-ih)/2:black,setsar=1[v${i}]`);
+        if (hasAudio) {
+            parts.push(`[0:a]atrim=start=${c.startSeconds.toFixed(4)}:end=${c.endSeconds.toFixed(4)},asetpts=PTS-STARTPTS[a${i}]`);
+        }
+    });
+    const streams = crops.map((_, i) => (hasAudio ? `[v${i}][a${i}]` : `[v${i}]`)).join("");
+    parts.push(`${streams}concat=n=${crops.length}:v=1:a=${hasAudio ? 1 : 0}[vout]${hasAudio ? "[aout]" : ""}`);
+    return parts.join(";");
+}
+function buildReformatArgs(inPath, outPath, filterGraph, hasAudio) {
+    const args = ["-nostdin", "-i", inPath, "-filter_complex", filterGraph, "-map", "[vout]"];
+    if (hasAudio)
+        args.push("-map", "[aout]", "-c:a", "aac", "-b:a", "160k");
+    args.push("-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "20", "-movflags", "+faststart", outPath, "-y");
+    return args;
+}
+function buildProbeArgs(inPath) {
+    return [
+        "-v",
+        "error",
+        "-show_entries",
+        "stream=codec_type,width,height",
+        "-of",
+        "json",
+        inPath,
+    ];
+}
+function parseProbe(stdout) {
+    const parsed = JSON.parse(stdout);
+    const streams = parsed.streams ?? [];
+    const video = streams.find((s) => s.codec_type === "video");
+    if (!video?.width || !video?.height) {
+        throw new Error("ffprobe found no video stream in the input, so there is nothing to reformat.");
+    }
+    return { width: video.width, height: video.height, hasAudio: streams.some((s) => s.codec_type === "audio") };
+}
+async function runReformatVertical(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const targetWidth = input.width ?? 1080;
+    const targetHeight = input.height ?? 1920;
+    const beatsPath = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    if (!fs.existsSync(beatsPath)) {
+        throw new Error(`${beatsPath} does not exist. The crop is driven by the manifest, so it has to be there.`);
+    }
+    const doc = JSON.parse(fs.readFileSync(beatsPath, "utf8"));
+    const beats = doc.beats;
+    if (!Array.isArray(beats) || beats.length === 0) {
+        throw new Error(`${beatsPath} has no beats.`);
+    }
+    const inPathRel = input.inPath ?? path.join("output", `${videoName}.mp4`);
+    const outPathRel = input.outPath ?? path.join("output", `${videoName}-${targetWidth}x${targetHeight}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, inPathRel, "inPath");
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
+    const inPathAbs = path.join(projectRoot, inPathRel);
+    if (!fs.existsSync(inPathAbs)) {
+        throw new Error(`${inPathAbs} does not exist. Render the 16:9 video first, then reformat it.`);
+    }
+    fs.mkdirSync(path.dirname(path.join(projectRoot, outPathRel)), { recursive: true });
+    const started = Date.now();
+    const probe = await (0, util_1.spawnCapture)("ffprobe", buildProbeArgs(inPathRel), projectRoot);
+    if (probe.code !== 0) {
+        throw new Error(`ffprobe could not read ${inPathRel}:\n${probe.stderr.slice(-800)}`);
+    }
+    const { width: sourceWidth, height: sourceHeight, hasAudio } = parseProbe(probe.stdout);
+    const crops = planCrops({
+        beats,
+        fps: doc.fps ?? 30,
+        sourceWidth,
+        sourceHeight,
+        targetWidth,
+        targetHeight,
+    });
+    const graph = buildVerticalFilterGraph(crops, targetWidth, targetHeight, hasAudio);
+    const result = await (0, util_1.spawnCapture)("ffmpeg", buildReformatArgs(inPathRel, outPathRel, graph, hasAudio), projectRoot);
+    if (result.code !== 0 || !fs.existsSync(path.join(projectRoot, outPathRel))) {
+        throw new Error(`ffmpeg reformat failed:\n${result.stderr.slice(-1500)}`);
+    }
+    return {
+        outPath: path.join(projectRoot, outPathRel),
+        width: targetWidth,
+        height: targetHeight,
+        sourceWidth,
+        sourceHeight,
+        beats: crops,
+        elapsedSeconds: Math.round((Date.now() - started) / 1000),
+    };
+}
+function registerReformatVertical(server) {
+    server.registerTool("reformat_vertical", {
+        title: "Reformat a finished video to 9:16 using the manifest",
+        description: "Turns a rendered 16:9 composition into a 9:16 cut for short-form platforms, deciding the crop per " +
+            "beat from beats.json instead of taking the middle of every frame. That fixed centre crop is why most " +
+            "automated reframing looks wrong: it does not know what is on screen. This does, because the manifest " +
+            "already says. A terminal beat crops left, since a terminal is text pinned to the left margin and " +
+            "centring it cuts the command in half. A mobile recording is already portrait, so it is fitted and " +
+            "padded rather than cropped. A dom-demo panel really is centred. Any beat can override the inference " +
+            "with vertical.focus (left, center, right) or an explicit vertical.crop rectangle, and the result " +
+            "reports the crop chosen for every beat with the reason, so a wrong guess is visible rather than " +
+            "silent. Runs as one ffmpeg pass (trim, crop, scale, pad, concat) rather than N renders and a join, " +
+            "so there are no intermediates and no extra generation of quality lost. Active speaker tracking is " +
+            "deliberately not in scope: it needs real face and audio analysis. Defaults to 1080x1920 written to " +
+            "output/<videoName>-1080x1920.mp4. This is a crop of a finished 16:9 render, never a re-layout: each " +
+            "crop is a 608x1080 slice, under a third of the frame width, so a diagram or a wide equation is cut " +
+            "off. For content that has to be seen whole, render natively vertical instead (init_project with " +
+            "videoConfig 1080x1920), then package it with export_rendition format \"reels\"; PIPELINE.md, " +
+            "\"Native vertical (9:16)\", says when to use which.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            inPath: zod_1.z.string().optional().describe("The finished 16:9 render. Defaults to output/<videoName>.mp4."),
+            outPath: zod_1.z.string().optional(),
+            width: zod_1.z.number().int().positive().optional(),
+            height: zod_1.z.number().int().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("reformat_vertical", () => runReformatVertical(input)));
+}

package/dist/tools/releaseDiff.d.ts

@@ -0,0 +1,96 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Interaction, type Viewport } from "@openvidstudio/capture";
+/**
+ * Two refs in, a what's-new clip out.
+ *
+ * Today a project makes one demo video, ever. This is the change that turns that into one
+ * video per release, which is the difference between a tool someone uses once and a tool
+ * wired into how they ship.
+ *
+ * The hard part is not capturing twice. It is not making a video about nothing: a release
+ * is mostly dependency bumps and refactors, and a "what's new" clip that shows four
+ * identical pages is worse than no clip. So every candidate route is captured on both
+ * sides and compared, and the ones that did not actually change visually are dropped, with
+ * the numbers reported so the decision is auditable rather than mysterious.
+ *
+ * What this needs from the caller is two running instances, one per ref. It does not check
+ * out, build, and serve an arbitrary project, because doing that safely for any stack is
+ * not a thing a video tool should claim it can do. In practice both instances already
+ * exist: a preview deployment and production are exactly this, and so are two local ports.
+ * The git refs are used for what git is actually good for here, which is working out which
+ * routes are worth looking at in the first place.
+ */
+export interface ReleaseDiffInput {
+    /** The video project, where the captures and the draft manifest land. */
+    projectRoot?: string;
+    videoName: string;
+    /** The product repository, used only to work out which routes changed. */
+    repoRoot: string;
+    beforeRef: string;
+    afterRef: string;
+    /** A running instance of each ref. A preview deployment and production are the usual pair. */
+    beforeUrl: string;
+    afterUrl: string;
+    /** Skip route detection and check exactly these. */
+    routes?: string[];
+    interactions?: Interaction[];
+    viewport?: Viewport;
+    /** Pixels captured per CSS pixel. Defaults to 2, matching capture_screenshot's own default. */
+    deviceScaleFactor?: number;
+    changedRatioThreshold?: number;
+    meanDeltaThreshold?: number;
+}
+export interface RouteChange {
+    route: string;
+    changed: boolean;
+    reason: string;
+    changedRatio: number;
+    meanDelta: number;
+    beforePath: string;
+    afterPath: string;
+    diffPath: string;
+}
+export interface ReleaseDiffResult {
+    beforeRef: string;
+    afterRef: string;
+    routesConsidered: string[];
+    changedRoutes: string[];
+    routes: RouteChange[];
+    /** Draft manifest, written to disk but deliberately NOT installed as the video's beats.json. */
+    draftPath: string;
+    nextSteps: string[];
+}
+/** Turns a route into a beat id and a file name. */
+export declare function routeSlug(route: string): string;
+/**
+ * Which routes a diff between two refs could plausibly have changed.
+ *
+ * Deliberately generous. A changed component under src/components has no route of its own
+ * but can repaint every page, so when anything outside the route tree changes, every route
+ * becomes a candidate. The visual comparison is what narrows it back down, and it is a far
+ * more reliable filter than guessing at an import graph.
+ */
+export declare function routesFromDiff(changedFiles: string[], allRoutes: string[]): string[];
+/**
+ * The draft manifest: a before/after pair per changed route.
+ *
+ * Both sides are `existing-asset` beats, because that is what they honestly are. The
+ * "before" frame cannot be re-captured from a live URL once the release is out, and the
+ * "after" frame was captured at a specific ref rather than from whatever is running now.
+ * Attribution on each says which ref it came from, which is the point of that field.
+ *
+ * `vo` is left empty on purpose. Writing the narration is drafting content, this server
+ * does not draft content, and PLANNING.md's approval gate exists precisely so a human sees
+ * the words before they are spoken over their product. The suggested word count is included
+ * so whoever writes them knows what fits.
+ */
+export declare function buildDraftManifest(opts: {
+    videoName: string;
+    beforeRef: string;
+    afterRef: string;
+    changes: RouteChange[];
+    fps: number;
+    beatFrames: number;
+}): unknown;
+export declare function runReleaseDiff(input: ReleaseDiffInput): Promise<ReleaseDiffResult>;
+export declare function registerReleaseDiff(server: McpServer): void;