@openvidstudio/mcp-server 1.3.1 → 1.4.0

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)));
+}

package/dist/tools/generateNarration.d.ts

@@ -116,6 +116,9 @@ export interface GenerateNarrationResult {
     /** Word timings for scenes that point at the word being spoken (useNarrationWords). See NARRATION.md. */
     wordTimings: WordTimingsReport;
 }
+/** Beyond this, a pitch-preserving stretch starts to sound processed. */
+export declare const TEMPO_FLOOR = 0.9;
+export declare const TEMPO_CEIL = 1.12;
 interface BeatLike {
     id: string;
     duration: number;
@@ -127,6 +130,22 @@ interface BeatLike {
 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 probeDuration(file: string): number;
+/** The last non-empty line of a process's stderr, trimmed to something a warning can carry. */
+export declare function lastErrorLine(stderr: string | undefined | null): string;
+export interface EdgeTtsProbe {
+    ok: boolean;
+    /** The installed version, when it could be read. */
+    version?: string;
+    /** Present when ok is false: the last stderr line from edge-tts. */
+    error?: string;
+}
+/**
+ * Asks edge-tts to speak one short word to a temp file. Microsoft's service refuses connections from
+ * some versions of the client (a 403 from speech.platform.bing.com), and the only symptom otherwise is a
+ * narration run that fails on every beat.
+ */
+export declare function probeEdgeTts(): EdgeTtsProbe;
 export declare function runGenerateNarration(input: GenerateNarrationInput): GenerateNarrationResult;
 export declare function registerGenerateNarration(server: McpServer): void;
 export {};

package/dist/tools/generateNarration.js

@@ -33,20 +33,25 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEMPO_CEIL = exports.TEMPO_FLOOR = void 0;
 exports.sanitizeLanguage = sanitizeLanguage;
 exports.lineFor = lineFor;
+exports.probeDuration = probeDuration;
+exports.lastErrorLine = lastErrorLine;
+exports.probeEdgeTts = probeEdgeTts;
 exports.runGenerateNarration = runGenerateNarration;
 exports.registerGenerateNarration = registerGenerateNarration;
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const zod_1 = require("zod");
 const util_1 = require("../util");
 const paths_1 = require("../paths");
 const mcp_1 = require("./mcp");
 /** Beyond this, a pitch-preserving stretch starts to sound processed. */
-const TEMPO_FLOOR = 0.9;
-const TEMPO_CEIL = 1.12;
+exports.TEMPO_FLOOR = 0.9;
+exports.TEMPO_CEIL = 1.12;
 const DEFAULT_VOICE = {
     "edge-tts": "en-US-AndrewNeural",
     say: "Alex",
@@ -111,7 +116,41 @@ function readWords(file) {
         return null;
     }
 }
+/** The last non-empty line of a process's stderr, trimmed to something a warning can carry. */
+function lastErrorLine(stderr) {
+    const lines = (stderr ?? "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    const line = lines[lines.length - 1] ?? "";
+    return line.length > 300 ? `${line.slice(0, 297)}...` : line;
+}
+/** Runs the edge-tts command, or its Python module when the command is not on PATH. */
+function runEdgeTts(args) {
+    const r = (0, node_child_process_1.spawnSync)("edge-tts", args, { encoding: "utf8" });
+    return r.error ? (0, node_child_process_1.spawnSync)("python", ["-m", "edge_tts", ...args], { encoding: "utf8" }) : r;
+}
+/**
+ * Asks edge-tts to speak one short word to a temp file. Microsoft's service refuses connections from
+ * some versions of the client (a 403 from speech.platform.bing.com), and the only symptom otherwise is a
+ * narration run that fails on every beat.
+ */
+function probeEdgeTts() {
+    const versionRun = runEdgeTts(["--version"]);
+    const version = versionRun.error || versionRun.status !== 0 ? undefined : (versionRun.stdout ?? "").trim().split(/\r?\n/)[0] || undefined;
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ovs-edge-probe-"));
+    const out = path.join(dir, "probe.mp3");
+    try {
+        const r = runEdgeTts(["--voice", "en-US-AndrewNeural", "--text", "Hello", "--write-media", out]);
+        const produced = fs.existsSync(out) && fs.statSync(out).size > 0;
+        if (!r.error && r.status === 0 && produced)
+            return { ok: true, version };
+        const error = r.error ? r.error.message : lastErrorLine(r.stderr) || `edge-tts exited with status ${r.status} and wrote no audio`;
+        return { ok: false, version, error };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
 function synthesize(engine, voice, text, out, omni = {}, wordsOut) {
+    let lastError = "";
     for (let attempt = 0; attempt < 3; attempt++) {
         fs.rmSync(out, { force: true });
         let r;
@@ -121,6 +160,7 @@ function synthesize(engine, voice, text, out, omni = {}, wordsOut) {
             if (!r.error && r.status === 0 && fs.existsSync(out) && probeDuration(out) > 0.3) {
                 return { ok: true, words: readWords(wordsOut) ?? undefined };
             }
+            lastError = lastErrorLine(r.stderr) || lastError;
             // fall through to the plain command line, which gives audio and no timings
         }
         if (engine === "edge-tts") {
@@ -160,8 +200,11 @@ function synthesize(engine, voice, text, out, omni = {}, wordsOut) {
         // be undecodable, so this validates by actually probing the file.
         if (!r.error && fs.existsSync(out) && probeDuration(out) > 0.3)
             return { ok: true };
+        lastError = (r.error ? r.error.message : lastErrorLine(r.stderr)) || lastError;
     }
-    return { ok: false, error: `no usable audio after 3 attempts` };
+    const cause = lastError ? ` (${lastError})` : "";
+    const hint = engine === "edge-tts" && lastError ? " Run preflight to check edge-tts; pip install -U edge-tts often fixes a refused connection." : "";
+    return { ok: false, error: `no usable audio after 3 attempts${cause}.${hint}` };
 }
 function runGenerateNarration(input) {
     const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
@@ -254,7 +297,7 @@ function runGenerateNarration(input) {
             const beatSeconds = beat.duration / fps;
             const target = beatSeconds - pad;
             const wanted = spoken / target;
-            const tempo = Math.min(TEMPO_CEIL, Math.max(TEMPO_FLOOR, wanted));
+            const tempo = Math.min(exports.TEMPO_CEIL, Math.max(exports.TEMPO_FLOOR, wanted));
             const r = (0, node_child_process_1.spawnSync)("ffmpeg", ["-v", "error", "-i", raw, "-filter:a", `atempo=${tempo.toFixed(4)}`,
                 "-c:a", "libmp3lame", "-q:a", "3", finalPath, "-y"], { encoding: "utf8" });
             if (r.status !== 0) {
@@ -280,7 +323,7 @@ function runGenerateNarration(input) {
                 // is a shorter translation, not a faster one.
                 clip.note =
                     `Runs ${(finalSeconds - beatSeconds).toFixed(2)}s past the beat. Shorten the line or ` +
-                        `lengthen the beat; stretching further would sound processed.`;
+                        `lengthen the beat (fit_beats sizes every beat from the measured voice); stretching further would sound processed.`;
                 warnings.push(`${beat.id}: narration overruns its beat by ${(finalSeconds - beatSeconds).toFixed(2)}s`);
             }
             else if (clip.needsAttention) {

package/dist/tools/index.js

@@ -41,6 +41,9 @@ const renderStills_1 = require("./renderStills");
 const collectFacts_1 = require("./collectFacts");
 const finalizeVideo_1 = require("./finalizeVideo");
 const checkScript_1 = require("./checkScript");
+const fitBeats_1 = require("./fitBeats");
+const renderCanvasExplainer_1 = require("./renderCanvasExplainer");
+const validateCanvasExplainer_1 = require("./validateCanvasExplainer");
 /**
  * Registers all of this package's tools. All but one need no server-startup config: each
  * resolves a project's own openvidstudio.config.json itself, per call, off projectRoot.
@@ -92,6 +95,9 @@ function registerTools(server, config) {
     (0, collectFacts_1.registerCollectFacts)(server);
     (0, finalizeVideo_1.registerFinalizeVideo)(server);
     (0, checkScript_1.registerCheckScript)(server);
+    (0, fitBeats_1.registerFitBeats)(server);
+    (0, renderCanvasExplainer_1.registerRenderCanvasExplainer)(server);
+    (0, validateCanvasExplainer_1.registerValidateCanvasExplainer)(server);
     if (config?.hasHiggsfield === true) {
         (0, importHiggsfieldClip_1.registerImportHiggsfieldClip)(server);
     }

package/dist/tools/initProject.js

@@ -45,6 +45,11 @@ const stitchComposition_1 = require("./stitchComposition");
 const mcp_1 = require("./mcp");
 const STEM_DIR = "openvidstudio-stem";
 const STEM_DEPENDENCY = "@openvidstudio/stem";
+/** output/ collects renders on the maintainer's machine; only its two tracked files belong in a new project. */
+const OUTPUT_FILES = new Set(["output/README.md", "output/.gitignore"]);
+function isStrayOutputFile(rel) {
+    return rel.startsWith("output/") && !OUTPUT_FILES.has(rel);
+}
 const SUPERNOVA_VIDEO_CONFIG = { fps: 30, width: 1080, height: 1920 };
 /** Adds or removes the stem dependency in the project's package.json, leaving the rest as it is. */
 function setStemDependency(projectRoot, present) {
@@ -100,7 +105,7 @@ function runInitProject(input) {
     const supernova = input.mode === "supernova";
     const configExisted = fs.existsSync((0, config_1.configPath)(projectRoot));
     // The vendored stem package is part of the bundled shell but belongs only to supernova projects.
-    (0, util_1.copyTemplateTree)(paths_1.TEMPLATE_DIR, projectRoot, supernova ? undefined : (rel) => rel === STEM_DIR);
+    (0, util_1.copyTemplateTree)(paths_1.TEMPLATE_DIR, projectRoot, (rel) => (!supernova && rel === STEM_DIR) || isStrayOutputFile(rel));
     if (supernova)
         installStem(projectRoot);
     else if (!alreadyScaffolded)

package/dist/tools/preflight.js

@@ -47,6 +47,7 @@ const zod_1 = require("zod");
 const capture_1 = require("@openvidstudio/capture");
 const util_1 = require("../util");
 const config_1 = require("../config");
+const generateNarration_1 = require("./generateNarration");
 const stitchComposition_1 = require("./stitchComposition");
 const mcp_1 = require("./mcp");
 function which(cmd) {
@@ -281,6 +282,21 @@ async function runPreflight(input) {
         fix: narration ? undefined : "pip install edge-tts",
         blocking: false,
     });
+    // Having edge-tts installed does not mean it can synthesize: Microsoft's service refuses some client
+    // versions with a 403, and the first symptom is a narration run that fails on every beat. So speak one
+    // word. Skipped for any other engine, and when the command is missing (the narration check above says so).
+    if (config.narration.engine === "edge-tts" && narration) {
+        const probe = (0, generateNarration_1.probeEdgeTts)();
+        checks.push({
+            name: "edge-tts",
+            ok: probe.ok,
+            detail: probe.ok
+                ? `edge-tts ${probe.version ?? "(version unknown)"} synthesized a test word`
+                : `edge-tts ${probe.version ?? "(version unknown)"} could not synthesize: ${probe.error}`,
+            fix: probe.ok ? undefined : "pip install -U edge-tts (Microsoft refuses some older versions with a 403; 7.3 or newer works)",
+            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
@@ -323,7 +339,10 @@ function registerPreflight(server) {
             "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, " +
+            "steps later, often after a long render has already started. When the narration engine is edge-tts, it " +
+            "also speaks one short word to a temp file (the edge-tts check), because Microsoft refuses some client " +
+            "versions with a 403 and the command existing proves nothing; a failure shows the installed version, " +
+            "the error line and pip install -U edge-tts. Narration is reported as non blocking, " +
             "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 " +

package/dist/tools/renderCanvasExplainer.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerRenderCanvasExplainer(server: McpServer): void;

package/dist/tools/renderCanvasExplainer.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRenderCanvasExplainer = registerRenderCanvasExplainer;
+const zod_1 = require("zod");
+const jobs_1 = require("../jobs");
+const canvasExplainer_1 = require("../canvasExplainer");
+const mcp_1 = require("./mcp");
+function registerRenderCanvasExplainer(server) {
+    server.registerTool("render_canvas_explainer", {
+        title: "Render an HTML canvas explainer to a video",
+        description: "Turns a canvas explainer into an mp4. An explainer is one self-contained HTML file with a canvas that exposes " +
+            "window.seek(t) (draw the frame at time t in seconds, a pure function of t), window.DURATION (seconds) and " +
+            "window.scoreSound(kit) (a Web Audio score), with window.SOUND.renderOffline(scoreSound, seconds, sampleRate, " +
+            "{ voiceover }) to render it; a file that does not expose these is refused with the missing ones named. Loads the file " +
+            "in headless Chromium, waits for fonts, walks every frame (round(DURATION * fps), 1280x720 at 30 fps by default, " +
+            "width 720 and height 1280 for a Reel, both even), pipes the canvas PNGs into ffmpeg (H.264, yuv420p), renders the score, " +
+            "and muxes the two. Pass videoName to use the project's beats: src/videos/<videoName>/beats.json becomes window.BEATS " +
+            "(an array of { id, start, end, text } in seconds, after fit_beats), DURATION becomes the last beat's end, " +
+            "public/audio/vo/<beatId>.mp3 is mixed in at each beat's start over the score rendered with voiceover: true and the score " +
+            "ducked at least 6 dB (audio.duckDb, default 9) under the voice, and the beats' text is burned in as captions broken at " +
+            "sentence ends inside the safe areas, through window.CAPTIONS.draw(ctx, t, opts) which the explainer can call to caption in its " +
+            "own style (the renderer draws them itself if it does not); narration: \"none\" renders silent narration with the full-mix " +
+            "sound. audio: false renders no sound. A pre-flight runs validate_canvas_explainer first and refuses to render on an error " +
+            "(validate: false skips it). Warns when the file calls Math.random. Returns the frame count, the SHA-256 of the first, middle " +
+            "and last frame (render twice and compare them to check the purity promise) and what was mixed. Pass async: true to return a " +
+            "jobId at once and poll job_status, as render_video does.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            htmlPath: zod_1.z.string().min(1).describe("The explainer, absolute or relative to the project root."),
+            outPath: zod_1.z.string().min(1).describe("The mp4 to write, relative to the project root or absolute."),
+            width: zod_1.z.number().int().positive().optional().describe("Default 1280. Use 720 with height 1280 for a Reel."),
+            height: zod_1.z.number().int().positive().optional().describe("Default 720."),
+            fps: zod_1.z.number().positive().optional().describe("Default 30."),
+            audio: zod_1.z
+                .union([zod_1.z.literal(false), zod_1.z.object({ voiceover: zod_1.z.boolean().optional(), sampleRate: zod_1.z.number().int().positive().optional(), duckDb: zod_1.z.number().min(6).optional() })])
+                .optional()
+                .describe("false for no sound, or { voiceover, sampleRate, duckDb }. Voiceover defaults to on when videoName has narration."),
+            videoName: zod_1.z.string().optional().describe("Use this project video's beats.json, narration clips and captions."),
+            captions: zod_1.z.boolean().optional().describe("Burn the beats' text in as captions. Default true when there is narration."),
+            validate: zod_1.z.boolean().optional().describe("Run the pre-flight first. Default true."),
+            async: zod_1.z.boolean().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("render_canvas_explainer", async () => {
+        const args = { projectRoot: input.projectRoot, htmlPath: input.htmlPath, outPath: input.outPath, width: input.width, height: input.height, fps: input.fps, audio: input.audio, videoName: input.videoName, captions: input.captions, validate: input.validate };
+        if (input.async === true) {
+            // Checked now, so a bad call never "succeeds" with a jobId that immediately errors.
+            (0, canvasExplainer_1.resolveCanvasInput)(args);
+            const job = (0, jobs_1.createJob)("render_canvas_explainer", 0);
+            (0, canvasExplainer_1.runCanvasExplainer)(args, { onProgress: (p) => (0, jobs_1.updateJobProgress)(job.id, p) })
+                .then((result) => (0, jobs_1.completeJob)(job.id, result))
+                .catch((err) => (0, jobs_1.failJob)(job.id, err instanceof Error ? err.message : String(err)));
+            return { jobId: job.id };
+        }
+        return (0, canvasExplainer_1.runCanvasExplainer)(args);
+    }));
+}

package/dist/tools/renderVideo.d.ts

@@ -62,6 +62,8 @@ export interface RenderVideoResult {
     stderr: string;
     /** True when src/brand.ts existed at render time (whether from this call's skipBrandLock or a real extract_brand run). */
     brandLocked: boolean;
+    /** Set when the brand-lock gate was skipped on purpose: a Supernova lesson has no brand to extract. */
+    brandLockSkipReason?: string;
     /** Incremental renders only: beats whose cached segment was reused untouched. */
     reusedBeats?: string[];
     /** Incremental renders only: beats that were actually re-rendered. */
@@ -91,6 +93,7 @@ export interface PreparedRenderVideo {
     compositionId: string;
     outPathRel: string;
     brandLocked: boolean;
+    brandLockSkipReason?: string;
 }
 /**
  * The synchronous half of render_video: validate input and the brand-lock gate, throwing