@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/finalizeVideo.js

@@ -0,0 +1,300 @@
+"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.LOUDNESS_TOLERANCE_LU = exports.DEFAULT_LRA = exports.DEFAULT_TRUE_PEAK_DB = exports.DEFAULT_TARGET_LUFS = void 0;
+exports.buildLoudnormMeasureArgs = buildLoudnormMeasureArgs;
+exports.buildLoudnormApplyArgs = buildLoudnormApplyArgs;
+exports.parseLoudnormJson = parseLoudnormJson;
+exports.runFinalizeVideo = runFinalizeVideo;
+exports.registerFinalizeVideo = registerFinalizeVideo;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const exportRendition_1 = require("./exportRendition");
+const writeDescription_1 = require("./writeDescription");
+const facts_1 = require("../facts");
+const audioTick_1 = require("../audioTick");
+const mcp_1 = require("./mcp");
+/**
+ * The last pass over a finished render: a loudness target on the mix, a poster frame, and a
+ * copy small enough to share.
+ *
+ * Loudness is where the earlier stages stop short. compose_score and generate_narration each
+ * aim at a level for their own track (a bed sits at -15 LUFS under narration), but nothing
+ * measures the two together after the mix, so a finished video's loudness is whatever the sum
+ * happened to be. This measures it and moves it to a target, two-pass: the first pass reads
+ * the real integrated loudness, true peak and range, and the second applies a linear gain
+ * computed from those numbers rather than a guessed constant.
+ *
+ * The target is -14 LUFS integrated with a -1.5 dBTP ceiling. The bed's -15 is the music alone
+ * under a voice, not the finished mix, and -14 is the level the large video platforms normalise
+ * to, so a master at -14 is neither turned down (too loud) nor left quiet (too soft).
+ */
+exports.DEFAULT_TARGET_LUFS = -14;
+exports.DEFAULT_TRUE_PEAK_DB = -1.5;
+exports.DEFAULT_LRA = 11;
+/** How far the finished file's measured loudness may sit from the target before it is reported as a miss. */
+exports.LOUDNESS_TOLERANCE_LU = 1;
+function buildLoudnormMeasureArgs(inPath, target) {
+    return [
+        "-nostdin",
+        "-hide_banner",
+        "-i",
+        inPath,
+        "-map",
+        "0:a:0",
+        "-af",
+        `loudnorm=I=${target.lufs}:TP=${target.truePeakDb}:LRA=${target.lra}:print_format=json`,
+        "-f",
+        "null",
+        "-",
+    ];
+}
+/**
+ * Second pass. Feeding loudnorm the numbers the first pass measured is what makes this a
+ * two-pass normalisation: with them it can apply one linear gain for the whole file (`linear=true`)
+ * instead of the dynamic, moment-to-moment adjustment its single pass falls back on, which pumps
+ * quiet narration against loud music. The video stream is copied, never re-encoded.
+ */
+function buildLoudnormApplyArgs(inPath, outPath, target, measured, 
+/**
+ * The video's own duration in seconds. loudnorm's lookahead makes its output about 100 ms
+ * longer than its input, which would leave the audio running three frames past the picture,
+ * so the file is cut at the video's end. Omit to leave the output length to ffmpeg.
+ */
+videoDurationSeconds) {
+    const filter = `loudnorm=I=${target.lufs}:TP=${target.truePeakDb}:LRA=${target.lra}` +
+        `:measured_I=${measured.integratedLufs}:measured_TP=${measured.truePeakDb}:measured_LRA=${measured.loudnessRange}` +
+        `:measured_thresh=${measured.threshold}:offset=${measured.targetOffset}:linear=true:print_format=summary`;
+    return [
+        "-nostdin",
+        "-y",
+        "-i",
+        inPath,
+        "-map",
+        "0:v",
+        "-map",
+        "0:a:0",
+        "-c:v",
+        "copy",
+        "-af",
+        filter,
+        "-c:a",
+        "aac",
+        "-b:a",
+        "192k",
+        "-ar",
+        "48000",
+        "-movflags",
+        "+faststart",
+        ...(videoDurationSeconds !== undefined ? ["-t", videoDurationSeconds.toFixed(6)] : []),
+        outPath,
+    ];
+}
+/** Pulls the JSON block loudnorm prints to stderr after its progress output. */
+function parseLoudnormJson(stderr) {
+    const end = stderr.lastIndexOf("}");
+    const start = end === -1 ? -1 : stderr.lastIndexOf("{", end);
+    if (start === -1)
+        throw new Error(`No loudnorm measurement in ffmpeg's output:\n${stderr.slice(-600)}`);
+    const raw = JSON.parse(stderr.slice(start, end + 1));
+    const num = (key) => {
+        const v = Number.parseFloat(raw[key]);
+        if (!Number.isFinite(v))
+            throw new Error(`loudnorm reported "${raw[key]}" for ${key}. The audio may be silent.`);
+        return v;
+    };
+    return {
+        integratedLufs: num("input_i"),
+        truePeakDb: num("input_tp"),
+        loudnessRange: num("input_lra"),
+        threshold: num("input_thresh"),
+        targetOffset: num("target_offset"),
+    };
+}
+/** The first video stream's duration, or null if ffprobe cannot read one. */
+async function videoDurationSeconds(inPathRel, projectRoot) {
+    const r = await (0, util_1.spawnCapture)("ffprobe", ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=duration", "-of", "csv=p=0", inPathRel], projectRoot);
+    if (r.code !== 0)
+        return null;
+    const value = Number.parseFloat(r.stdout.trim());
+    return Number.isFinite(value) && value > 0 ? value : null;
+}
+async function measure(inPathRel, projectRoot, target) {
+    const r = await (0, util_1.spawnCapture)("ffmpeg", buildLoudnormMeasureArgs(inPathRel, target), projectRoot);
+    if (r.code !== 0)
+        throw new Error(`Loudness measurement failed:\n${r.stderr.slice(-800)}`);
+    return parseLoudnormJson(r.stderr);
+}
+async function runFinalizeVideo(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const inRel = input.inPath ?? path.join("output", `${videoName}.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, inRel, "inPath");
+    if (!fs.existsSync(path.join(projectRoot, inRel))) {
+        throw new Error(`${inRel} does not exist. Run render_video first.`);
+    }
+    const outRel = input.outPath ?? path.join(path.dirname(inRel), `${videoName}-final.mp4`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outRel, "outPath");
+    if (path.resolve(projectRoot, outRel) === path.resolve(projectRoot, inRel)) {
+        throw new Error("outPath is the same file as inPath. Pick a different outPath so the original render is kept.");
+    }
+    const target = {
+        lufs: input.targetLufs ?? exports.DEFAULT_TARGET_LUFS,
+        truePeakDb: input.truePeakDb ?? exports.DEFAULT_TRUE_PEAK_DB,
+        lra: exports.DEFAULT_LRA,
+    };
+    const notes = [];
+    fs.mkdirSync(path.dirname(path.join(projectRoot, outRel)), { recursive: true });
+    const probe = await (0, util_1.spawnCapture)("ffprobe", ["-v", "error", "-select_streams", "a", "-show_entries", "stream=codec_type", "-of", "csv=p=0", inRel], projectRoot);
+    const hasAudio = probe.code === 0 && probe.stdout.trim().length > 0;
+    let loudness = null;
+    if (hasAudio) {
+        const before = await measure(inRel, projectRoot, target);
+        const videoSeconds = await videoDurationSeconds(inRel, projectRoot);
+        const apply = await (0, util_1.spawnCapture)("ffmpeg", buildLoudnormApplyArgs(inRel, outRel, target, before, videoSeconds ?? undefined), projectRoot);
+        if (apply.code !== 0)
+            throw new Error(`Loudness normalisation failed:\n${apply.stderr.slice(-1200)}`);
+        const after = await measure(outRel, projectRoot, target);
+        const withinTolerance = Math.abs(after.integratedLufs - target.lufs) <= exports.LOUDNESS_TOLERANCE_LU;
+        loudness = { target, before, after, withinTolerance, toleranceLu: exports.LOUDNESS_TOLERANCE_LU };
+        notes.push(`Loudness ${before.integratedLufs} LUFS -> ${after.integratedLufs} LUFS (target ${target.lufs}), ` +
+            `true peak ${after.truePeakDb} dBTP.`);
+        if (!withinTolerance) {
+            notes.push(`The result is more than ${exports.LOUDNESS_TOLERANCE_LU} LU from the target. A very wide loudness range ` +
+                `(${before.loudnessRange} LU in) can stop linear normalisation reaching it without clipping the peak ceiling.`);
+        }
+    }
+    else {
+        // Nothing to normalise. The final file is still the video, unchanged, so the later steps have one name to read.
+        fs.copyFileSync(path.join(projectRoot, inRel), path.join(projectRoot, outRel));
+        notes.push("The render has no audio track, so there was nothing to loudness-normalise. The video was copied as is.");
+    }
+    const result = { finalPath: outRel, loudness, notes };
+    if (hasAudio) {
+        const tick = await (0, audioTick_1.measureAudioTick)(outRel, projectRoot);
+        if (tick) {
+            result.audioTick = tick;
+            const warning = (0, audioTick_1.describeTick)(tick);
+            if (warning)
+                notes.push(warning);
+        }
+    }
+    if (input.poster !== false) {
+        result.poster = await (0, exportRendition_1.runExportRendition)({
+            projectRoot,
+            videoName,
+            format: "poster",
+            inPath: outRel,
+            posterPick: "auto",
+            bake: false,
+        });
+    }
+    if (input.share !== false) {
+        result.share = await (0, exportRendition_1.runExportRendition)({
+            projectRoot,
+            videoName,
+            format: "share",
+            inPath: outRel,
+            maxMB: input.shareMaxMB,
+        });
+    }
+    // The description is part of the finished video, not an extra: a launch video goes up with its
+    // chapters, its credits and its sample-content disclosure, and one that was never written is
+    // one that gets posted without them. Only a missing beats.json is tolerated (nothing to
+    // describe); a malformed brief or a lost disclosure throws, because shipping those quietly
+    // is the failure this file exists to prevent.
+    if (input.description !== false) {
+        if (fs.existsSync(path.join(projectRoot, "src", "videos", videoName, "beats.json"))) {
+            result.description = (0, writeDescription_1.runWriteDescription)({ projectRoot, videoName });
+        }
+        else {
+            notes.push(`No description written: src/videos/${videoName}/beats.json does not exist, so there is nothing to describe.`);
+        }
+    }
+    (0, facts_1.writeFactRecord)(projectRoot, {
+        tool: "finalize_video",
+        videoName,
+        facts: {
+            finalPath: (0, facts_1.relToProject)(projectRoot, path.join(projectRoot, outRel)),
+            bytes: (0, facts_1.fileBytes)(path.join(projectRoot, outRel)),
+            loudness: loudness && {
+                targetLufs: target.lufs,
+                beforeLufs: loudness.before.integratedLufs,
+                afterLufs: loudness.after.integratedLufs,
+                afterTruePeakDb: loudness.after.truePeakDb,
+                withinTolerance: loudness.withinTolerance,
+            },
+            audioTick: result.audioTick ? { peak: result.audioTick.peak, lagMs: result.audioTick.lagMs, verdict: result.audioTick.verdict } : null,
+            description: result.description ? (0, facts_1.relToProject)(projectRoot, result.description.path) : null,
+            poster: result.poster?.files[0] ?? null,
+            posterBeat: result.poster?.posterPick?.beatId ?? null,
+            share: result.share?.share ? { path: result.share.share.path, bytes: result.share.share.bytes, maxBytes: result.share.share.maxBytes, withinCap: result.share.share.withinCap } : null,
+        },
+    });
+    return result;
+}
+function registerFinalizeVideo(server) {
+    server.registerTool("finalize_video", {
+        title: "Final assembly: loudness target, poster frame, size-capped share copy",
+        description: "The last pass over a finished render (run render_video first). Measures the mix's real integrated " +
+            "loudness, true peak and range, then normalises it two-pass with ffmpeg's loudnorm to a target " +
+            "(default -14 LUFS, -1.5 dBTP): the first pass measures, the second applies a linear gain computed from " +
+            "those numbers rather than a guessed constant, and the video stream is copied untouched. The written " +
+            "file is measured again and the result reports before, after, and whether it landed within 1 LU of the " +
+            "target, so the number is one that was measured, not one that was asked for. Writes " +
+            "<videoName>-final.mp4 and leaves the original render in place. Also writes a poster frame (export_" +
+            "rendition's poster with posterPick auto, so the thumbnail is the most representative beat rather " +
+            "than the last one) and a share copy under a hard size cap (shareMaxMB, default 10). Pass poster: " +
+            "false or share: false to skip either. Also writes output/<videoName>-DESCRIPTION.md (write_description: " +
+            "chapters from the beats, credits, and the disclosure of any constructed sample content), because a " +
+            "finished video is posted with it; pass description: false to skip. Also checks the finished audio for " +
+            "a ticking-clock pattern (short high-frequency hits repeating evenly) and adds an audio-tick note with " +
+            "the interval when it finds one. A render with no audio track skips loudness and the tick check, and says so.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            inPath: zod_1.z.string().optional().describe("The finished render. Defaults to output/<videoName>.mp4."),
+            outPath: zod_1.z.string().optional().describe("Defaults to output/<videoName>-final.mp4."),
+            targetLufs: zod_1.z.number().max(0).optional().describe("Integrated loudness target. Defaults to -14."),
+            truePeakDb: zod_1.z.number().max(0).optional().describe("True peak ceiling in dBTP. Defaults to -1.5."),
+            poster: zod_1.z.boolean().optional().describe("Defaults to true."),
+            share: zod_1.z.boolean().optional().describe("Defaults to true."),
+            shareMaxMB: zod_1.z.number().positive().optional().describe("Defaults to 10."),
+            description: zod_1.z.boolean().optional().describe("Write the DESCRIPTION.md file. Defaults to true."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("finalize_video", () => runFinalizeVideo(input)));
+}

package/dist/tools/fitBeats.d.ts

@@ -0,0 +1,69 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ValidateBeatsResult } from "./validateBeats";
+/**
+ * Sizes each beat from the measured voice. A real voice does not read at the pace a word count predicts
+ * (plain prose is about 3 words per second, number-heavy lines about 2.2), and validate_beats wants 2.3 to
+ * 2.9 words per second over the beat, so a beat sized by words alone overruns or sits half empty. The fix
+ * used to be a manual loop: provisional beats, generate_narration, read every spokenSeconds, compute new
+ * lengths in a script, rewrite beats.json, generate again. This is that loop's middle.
+ *
+ * Only `duration` and, to keep the beats contiguous, `start` change. The `vo` is never touched.
+ */
+/** Silence kept after the voice, so a line does not end on the cut. */
+export declare const DEFAULT_FIT_PAD_SECONDS = 0.5;
+export interface FitBeatsInput {
+    projectRoot?: string;
+    videoName: string;
+    /** Spoken length of each beat's clip in seconds, as generate_narration reports it. Overrides the clips on disk. */
+    spokenSeconds?: Record<string, number>;
+    /** generate_narration's result (only `written[].beatId` and `.spokenSeconds` are read). Same as spokenSeconds. */
+    narration?: {
+        written?: {
+            beatId: string;
+            spokenSeconds: number;
+            language?: string;
+        }[];
+    };
+    /** Seconds of silence after the spoken line. Default 0.5. */
+    padSeconds?: number;
+    /** Return the proposed durations without writing beats.json. */
+    dryRun?: boolean;
+}
+export interface FittedBeat {
+    beatId: string;
+    /** Duration in frames before and after. */
+    before: number;
+    after: number;
+    words: number;
+    /** The measured spoken length, and where it came from. */
+    spokenSeconds: number | null;
+    source: "report" | "raw-clip" | "final-clip" | null;
+    /** Words per second over the new beat length. */
+    pace: number | null;
+    status: "fitted" | "unchanged" | "unfittable" | "skipped";
+    /** "min" or "max" when the pace window, not the voice, decided the length. */
+    clampedTo?: "min" | "max";
+    note?: string;
+}
+export interface FitBeatsResult {
+    videoName: string;
+    dryRun: boolean;
+    written: boolean;
+    path: string;
+    beats: FittedBeat[];
+    /** Beats whose line cannot fit inside the pace window: shorten the sentence, or lengthen the beat past it. */
+    unfittable: FittedBeat[];
+    /** Total frames before and after. */
+    framesBefore: number;
+    framesAfter: number;
+    /** validate_beats run on the fitted beats. */
+    validation: ValidateBeatsResult;
+}
+/** Pure: the frames a line of `words` words, said in `spoken` seconds, should get. */
+export declare function fitFrames(words: number, spoken: number, fps: number, pad: number): {
+    frames: number;
+    clampedTo?: "min" | "max";
+    overruns: boolean;
+};
+export declare function runFitBeats(input: FitBeatsInput): FitBeatsResult;
+export declare function registerFitBeats(server: McpServer): void;

package/dist/tools/fitBeats.js

@@ -0,0 +1,229 @@
+"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.DEFAULT_FIT_PAD_SECONDS = void 0;
+exports.fitFrames = fitFrames;
+exports.runFitBeats = runFitBeats;
+exports.registerFitBeats = registerFitBeats;
+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");
+const validateBeats_1 = require("./validateBeats");
+const generateNarration_1 = require("./generateNarration");
+/**
+ * Sizes each beat from the measured voice. A real voice does not read at the pace a word count predicts
+ * (plain prose is about 3 words per second, number-heavy lines about 2.2), and validate_beats wants 2.3 to
+ * 2.9 words per second over the beat, so a beat sized by words alone overruns or sits half empty. The fix
+ * used to be a manual loop: provisional beats, generate_narration, read every spokenSeconds, compute new
+ * lengths in a script, rewrite beats.json, generate again. This is that loop's middle.
+ *
+ * Only `duration` and, to keep the beats contiguous, `start` change. The `vo` is never touched.
+ */
+/** Silence kept after the voice, so a line does not end on the cut. */
+exports.DEFAULT_FIT_PAD_SECONDS = 0.5;
+/** Pure: the frames a line of `words` words, said in `spoken` seconds, should get. */
+function fitFrames(words, spoken, fps, pad) {
+    const lo = Math.ceil((words / validateBeats_1.MAX_PACE) * fps - 1e-9);
+    const hi = Math.floor((words / validateBeats_1.MIN_PACE) * fps + 1e-9);
+    const wanted = Math.round((spoken + pad) * fps);
+    let frames = wanted;
+    let clampedTo;
+    if (frames < lo) {
+        frames = lo;
+        clampedTo = "min";
+    }
+    else if (frames > hi && hi >= lo) {
+        frames = hi;
+        clampedTo = "max";
+    }
+    // The clip is stretched by at most TEMPO_CEIL, so a beat shorter than that cannot hold it.
+    const overruns = frames / fps < spoken / generateNarration_1.TEMPO_CEIL - 1e-9;
+    return { frames, clampedTo, overruns };
+}
+function spokenFromDisk(projectRoot, beatId) {
+    const raw = path.join(projectRoot, ".openvidstudio", "narration", `${beatId}.raw`);
+    if (fs.existsSync(raw)) {
+        const s = (0, generateNarration_1.probeDuration)(raw);
+        if (s > 0)
+            return { seconds: s, source: "raw-clip" };
+    }
+    // The fitted clip has been stretched by an unknown tempo, so it is an estimate, and said to be one.
+    const finalClip = path.join(projectRoot, "public", "audio", "vo", `${beatId}.mp3`);
+    if (fs.existsSync(finalClip)) {
+        const s = (0, generateNarration_1.probeDuration)(finalClip);
+        if (s > 0)
+            return { seconds: s, source: "final-clip" };
+    }
+    return null;
+}
+function runFitBeats(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 fps = doc.fps && doc.fps > 0 ? doc.fps : 30;
+    const pad = input.padSeconds ?? exports.DEFAULT_FIT_PAD_SECONDS;
+    const silent = doc.narration === "none";
+    const reported = new Map();
+    for (const clip of input.narration?.written ?? []) {
+        if (clip.language === undefined || clip.language === "en" || !reported.has(clip.beatId))
+            reported.set(clip.beatId, clip.spokenSeconds);
+    }
+    for (const [id, seconds] of Object.entries(input.spokenSeconds ?? {}))
+        reported.set(id, seconds);
+    const unknown = [...reported.keys()].filter((id) => !doc.beats.some((b) => b.id === id));
+    if (unknown.length > 0)
+        throw new Error(`spokenSeconds names beats that are not in beats.json: ${unknown.join(", ")}.`);
+    const fitted = [];
+    let shift = 0;
+    const next = doc.beats.map((beat) => {
+        const words = (0, validateBeats_1.wordCount)(beat.vo ?? "");
+        const base = { beatId: beat.id, before: beat.duration, after: beat.duration, words, spokenSeconds: null, source: null, pace: null, status: "skipped" };
+        const moved = { ...beat, start: beat.start + shift };
+        const skip = (note) => {
+            fitted.push({ ...base, note });
+            return moved;
+        };
+        if (silent)
+            return skip(`narration is "none", so there is no voice to fit.`);
+        if (words === 0)
+            return skip("no vo on this beat.");
+        let spoken = null;
+        let source = null;
+        const given = reported.get(beat.id);
+        if (given !== undefined) {
+            spoken = given;
+            source = "report";
+        }
+        else {
+            const disk = spokenFromDisk(projectRoot, beat.id);
+            if (disk) {
+                spoken = disk.seconds;
+                source = disk.source;
+            }
+        }
+        if (spoken === null || !(spoken > 0))
+            return skip("no measured voice for this beat. Run generate_narration first, or pass spokenSeconds.");
+        const fit = fitFrames(words, spoken, fps, pad);
+        const entry = {
+            ...base,
+            after: fit.frames,
+            spokenSeconds: Number(spoken.toFixed(2)),
+            source,
+            pace: Number((words / (fit.frames / fps)).toFixed(2)),
+            status: fit.frames === beat.duration ? "unchanged" : "fitted",
+            ...(fit.clampedTo ? { clampedTo: fit.clampedTo } : {}),
+        };
+        if (source === "final-clip") {
+            entry.note = "Measured from the fitted clip, which generate_narration has already stretched, so this is an estimate. Run generate_narration with overwrite to measure the raw voice.";
+        }
+        if (fit.overruns) {
+            entry.status = "unfittable";
+            const maxWords = Math.max(1, Math.floor(((fit.frames / fps) * generateNarration_1.TEMPO_CEIL * words) / spoken));
+            const needSeconds = spoken / generateNarration_1.TEMPO_CEIL;
+            entry.note =
+                `The voice needs ${spoken.toFixed(2)}s (${needSeconds.toFixed(2)}s at the fastest natural stretch), but ${words} words only ` +
+                    `allow a beat of ${(fit.frames / fps).toFixed(2)}s at ${validateBeats_1.MIN_PACE} words/sec. Shorten this line to about ${maxWords} words or fewer, ` +
+                    `or lengthen the beat to ${Math.ceil(needSeconds * fps)} frames and accept a pace under ${validateBeats_1.MIN_PACE} words/sec (validate_beats will say so).`;
+            // Closest legal length, so the rest of the lesson still lines up; the finding is the report.
+        }
+        else if (fit.clampedTo === "min") {
+            entry.note = `The voice is quicker than ${validateBeats_1.MAX_PACE} words/sec, so the beat was held at ${(fit.frames / fps).toFixed(2)}s, the shortest the pace window allows. Add words to the line if the gap is noticeable.`;
+        }
+        else if (fit.clampedTo === "max") {
+            entry.note = `The voice would take longer than the ${validateBeats_1.MIN_PACE} words/sec window, so the beat was held at ${(fit.frames / fps).toFixed(2)}s, the longest it allows.`;
+        }
+        fitted.push(entry);
+        shift += fit.frames - beat.duration;
+        return { ...moved, duration: fit.frames };
+    });
+    const fittedDoc = { ...doc, beats: next };
+    const validation = (0, validateBeats_1.validateBeatsLogic)(fittedDoc);
+    const dryRun = input.dryRun === true;
+    const framesBefore = doc.beats.reduce((n, b) => n + b.duration, 0);
+    const framesAfter = next.reduce((n, b) => n + b.duration, 0);
+    const changed = fitted.some((b) => b.after !== b.before);
+    // A beats.json that would not change is left alone.
+    let written = false;
+    if (!dryRun && changed) {
+        fs.writeFileSync(beatsFile, JSON.stringify(fittedDoc, null, 2) + "\n", "utf8");
+        written = true;
+    }
+    return {
+        videoName,
+        dryRun,
+        written,
+        path: beatsFile,
+        beats: fitted,
+        unfittable: fitted.filter((b) => b.status === "unfittable"),
+        framesBefore,
+        framesAfter,
+        validation,
+    };
+}
+function registerFitBeats(server) {
+    server.registerTool("fit_beats", {
+        title: "Size the beats from the measured voice",
+        description: "Sets each beat's duration to the length its narration actually takes, so validate_beats' 2.3 to 2.9 " +
+            "words per second holds with a real voice. A voice reads plain prose at about 3 words per second and " +
+            "number-heavy lines at about 2.2, so beats sized from word counts overrun or sit half empty; this replaces the " +
+            "manual loop of reading generate_narration's spokenSeconds, computing new lengths and rewriting beats.json. " +
+            "Run generate_narration on provisional beats first. Each beat becomes the spoken length plus a pad (padSeconds, " +
+            "default 0.5), clamped into the pace window words/2.9 to words/2.3 and rounded to whole frames, and later " +
+            "beats' start frames move so the beats stay contiguous. The spoken length comes from spokenSeconds or " +
+            "generate_narration's result (narration), else the raw clips generate_narration keeps under " +
+            ".openvidstudio/narration/, else the fitted clips. Beats whose line cannot fit even at the clamp (the voice " +
+            "needs more than 2.3 words per second allows) are listed in unfittable with the number of words to cut or the " +
+            "frames to lengthen the beat to; they are set to the longest legal length meanwhile. Never changes vo. dryRun " +
+            "returns the proposed durations without writing beats.json. Re-runs validate_beats on the result and returns it as " +
+            "validation. After fitting, run generate_narration again (overwrite: true) so the clips are stretched to the new lengths.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            spokenSeconds: zod_1.z.record(zod_1.z.string(), zod_1.z.number().positive()).optional().describe("Beat id to the voice's spoken length in seconds."),
+            narration: zod_1.z
+                .object({ written: zod_1.z.array(zod_1.z.object({ beatId: zod_1.z.string(), spokenSeconds: zod_1.z.number().positive(), language: zod_1.z.string().optional() }).passthrough()).optional() })
+                .passthrough()
+                .optional()
+                .describe("generate_narration's result, instead of spokenSeconds."),
+            padSeconds: zod_1.z.number().min(0).optional().describe("Silence after the spoken line. Default 0.5."),
+            dryRun: zod_1.z.boolean().optional().describe("Return the proposed durations without writing beats.json."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("fit_beats", () => runFitBeats(input)));
+}