@openvidstudio/mcp-server 0.1.0 → 1.3.1

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/generateNarration.d.ts

@@ -17,8 +17,17 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * **Silence.** stitch_composition skips a missing clip with no error, so a half
  * generated narration renders successfully and plays silent in those beats. This
  * reports exactly which beats have audio and which do not.
+ *
+ * **Languages.** One manifest can ship the video in as many languages as it carries
+ * lines for. The translated lines live in the beat, as `voTranslations`, because this
+ * server does not call an LLM and does not draft content: a translation is content, it
+ * goes through the same agent and the same human approval as the original script did.
+ * The base language keeps writing to public/audio/vo/<beatId>.mp3 so nothing that
+ * existed before changes; every other language gets its own subdirectory. With the
+ * omnivoice engine and a reference clip, all of them are the same cloned voice, which
+ * is the difference between a translated video and a dubbed one.
  */
-export type NarrationEngine = "edge-tts" | "say" | "espeak";
+export type NarrationEngine = "edge-tts" | "say" | "espeak" | "omnivoice";
 export interface GenerateNarrationInput {
     projectRoot?: string;
     videoName: string;
@@ -30,9 +39,30 @@ export interface GenerateNarrationInput {
     overwrite?: boolean;
     /** Only these beat ids. */
     beatIds?: string[];
+    /**
+     * Every language to produce. Defaults to the base language alone, which is what every
+     * existing project gets without changing anything.
+     */
+    languages?: string[];
+    /** The language `vo` is written in. Everything else comes from `voTranslations`. */
+    baseLanguage?: string;
+    /** Per-language voice override, for engines whose voices are language-specific. */
+    voices?: Record<string, string>;
+    /**
+     * Fail rather than quietly producing a video that is narrated in one language and silent
+     * in another. A half-translated video is worse than an untranslated one: it looks broken
+     * to exactly the audience it was made for.
+     */
+    requireTranslations?: boolean;
+    /** omnivoice only: a reference clip to clone, so every language is the same voice. */
+    refAudio?: string;
+    refText?: string;
+    /** omnivoice only: voice design, when there is no clip to clone. */
+    instruct?: string;
 }
 export interface NarrationClip {
     beatId: string;
+    language: string;
     path: string;
     beatSeconds: number;
     spokenSeconds: number;
@@ -41,14 +71,62 @@ export interface NarrationClip {
     /** True when the clip could not be fitted inside its beat without an audible stretch. */
     needsAttention: boolean;
     note?: string;
+    /** Where the word timings were written (public/audio/vo/<beatId>.words.json), when the engine gave any. */
+    wordsPath?: string;
+    wordCount?: number;
+}
+/** One spoken word and when it is said, in milliseconds from the start of the clip as written. */
+export interface NarrationWord {
+    word: string;
+    startMs: number;
+    endMs: number;
+}
+/**
+ * What happened about word timings, said plainly rather than left for the caller to discover: only
+ * edge-tts gives word boundaries, and nothing is invented for an engine that does not.
+ */
+export interface WordTimingsReport {
+    /** True when the engine produces word boundaries (edge-tts, through the edge_tts Python module). */
+    supported: boolean;
+    /** The .words.json files written. */
+    written: string[];
+    note?: string;
+}
+export interface LanguageReport {
+    language: string;
+    voice: string;
+    /** Where this language's clips live, relative to the project root. */
+    dir: string;
+    written: NarrationClip[];
+    skipped: string[];
+    missing: string[];
+    warnings: string[];
 }
 export interface GenerateNarrationResult {
     engine: NarrationEngine;
+    /** The base language's voice. Per-language voices are on each language report. */
     voice: string;
+    /** The base language's clips, unchanged in meaning from before languages existed. */
     written: NarrationClip[];
     skipped: string[];
     missing: string[];
     warnings: string[];
+    /** Every language produced, including the base. */
+    languages: LanguageReport[];
+    /** Word timings for scenes that point at the word being spoken (useNarrationWords). See NARRATION.md. */
+    wordTimings: WordTimingsReport;
+}
+interface BeatLike {
+    id: string;
+    duration: number;
+    vo?: string;
+    /** Translated lines, keyed by language tag. Drafted by the agent, approved like any script. */
+    voTranslations?: Record<string, string>;
 }
+/** A language tag becomes a directory name, so it is checked before it is joined into a path. */
+export declare function sanitizeLanguage(tag: string): string;
+/** The line for one language: the original for the base, a translation for anything else. */
+export declare function lineFor(beat: BeatLike, language: string, baseLanguage: string): string | undefined;
 export declare function runGenerateNarration(input: GenerateNarrationInput): GenerateNarrationResult;
 export declare function registerGenerateNarration(server: McpServer): void;
+export {};