@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/stitchComposition.js

@@ -33,6 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFLIGHT_BENCHMARK_COMPOSITION_ID = exports.PREFLIGHT_BENCHMARK_VIDEO_NAME = void 0;
+exports.registryPath = registryPath;
+exports.readRegistry = readRegistry;
+exports.writeRegistry = writeRegistry;
+exports.renderRootTsx = renderRootTsx;
+exports.transitionHalfFrames = transitionHalfFrames;
+exports.readExistingMusicLayer = readExistingMusicLayer;
 exports.runStitchComposition = runStitchComposition;
 exports.registerStitchComposition = registerStitchComposition;
 const fs = __importStar(require("node:fs"));
@@ -41,6 +48,16 @@ const zod_1 = require("zod");
 const config_1 = require("../config");
 const util_1 = require("../util");
 const mcp_1 = require("./mcp");
+const facts_1 = require("../facts");
+/**
+ * The registry videoName init_project seeds preflight's benchmark composition under
+ * (preflight.ts) -- never a real video's name, so this entry survives every real video's
+ * stitch_composition call (whose registry filter is `entries.filter(e => e.videoName !==
+ * thisVideoName)`) untouched.
+ */
+exports.PREFLIGHT_BENCHMARK_VIDEO_NAME = "__preflight__";
+/** The registry entry's own composition id, what preflight's benchmark actually renders. */
+exports.PREFLIGHT_BENCHMARK_COMPOSITION_ID = "OvsPreflightBenchmark";
 /**
  * Registry of every video this project has stitched, one entry per stitch_composition
  * call, at src/videos/.registry.json. Root.tsx is fully regenerated from this file on
@@ -64,8 +81,14 @@ function writeRegistry(projectRoot, entries) {
     fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, JSON.stringify(entries, null, 2) + "\n", "utf8");
 }
-function renderRootTsx(entries) {
+function renderRootTsx(entries, hasBrand) {
     const imports = entries.map((e) => `import { ${e.componentName} } from "${e.importPath}";`).join("\n");
+    // Brand has to evaluate before any scene module, because applyBrand mutates the
+    // shared token objects rather than replacing them. Import order is evaluation order.
+    const brandImport = hasBrand
+        ? '// Brand first. applyBrand mutates the shared tokens, so this has to run\n' +
+            '// before any scene module reads them.\nimport "./brand";\n\n'
+        : "";
     const comps = entries
         .map((e) => `      <Composition\n        id="${e.id}"\n        component={${e.componentName}}\n` +
         `        durationInFrames={${e.durationInFrames}}\n        fps={${e.fps}}\n` +
@@ -76,7 +99,7 @@ function renderRootTsx(entries) {
 // next time stitch_composition runs for ANY video in this project, not just the one you
 // edited. Add a video by calling stitch_composition, not by editing this directly.
 
-import React from "react";
+${brandImport}import React from "react";
 import { Composition } from "remotion";
 ${imports}
 
@@ -89,64 +112,222 @@ ${comps}
 };
 `;
 }
+/**
+ * Import specifier for a beat's scene: its own `scene` override (extension stripped,
+ * a leading "./" added if it names a bare relative path) or the `./scenes/<PascalId>`
+ * convention scaffold_scene writes to. runStitchComposition validates `b.scene` stays
+ * inside the video directory before this ever sees it.
+ */
+function sceneImportPath(b) {
+    if (!b.scene)
+        return `./scenes/${(0, util_1.pascalCase)(b.id)}`;
+    const normalized = b.scene.replace(/\\/g, "/").replace(/\.(tsx|ts|jsx|js)$/, "");
+    return normalized.startsWith("./") || normalized.startsWith("../") ? normalized : `./${normalized}`;
+}
+/**
+ * Frames either side of a cut that a transition overlay covers: about 0.2s, so the whole
+ * overlay is 2 * this. Scaled with fps so the transition keeps its duration in seconds.
+ */
+function transitionHalfFrames(fps) {
+    return Math.max(2, Math.round((6 * fps) / 30));
+}
+/** True when some beat after the first asks for a transition other than a cut. */
+function hasTransitions(beats) {
+    return beats.some((b) => b.start > 0 && typeof b.transition === "string" && b.transition !== "cut");
+}
+const AUTO_MUSIC_BEDS = ["music-bed.mp3"];
+/**
+ * The music layer a previous stitch of this video wrote, if any. Re-stitching regenerates the
+ * whole composition file, so without this a hand-picked track or level silently reverts to the
+ * auto-detected bed. Matches only the exact shape renderDemoTsx emits.
+ */
+function readExistingMusicLayer(demoPath) {
+    let text;
+    try {
+        text = fs.readFileSync(demoPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const m = text.match(/<Audio src=\{staticFile\("audio\/([^"]+)"\)\} volume=\{([0-9.]+)\} loop \/>/);
+    if (!m)
+        return null;
+    const volume = Number(m[2]);
+    if (!Number.isFinite(volume))
+        return null;
+    const file = m[1];
+    // "pinned" = a person chose this layer, so a re-stitch must not replace it. Auto-detected
+    // beds are deliberately not pinned: a music-bed.mp3 that appears (or is replaced by
+    // compose_score) after the first stitch should be picked up on the next one.
+    const marker = text.match(/ovs-music-source: (\w+)/)?.[1];
+    const pinned = marker === "explicit" || marker === "preserved" || !AUTO_MUSIC_BEDS.includes(file);
+    return { file, volume, pinned };
+}
+/**
+ * The fields of public/audio/<stem>.cues.json that useMusicClock reads, or null when the bed
+ * has no cues file (or it does not parse, or carries no usable bpm). The first downbeat offset
+ * comes from the file's own beat list, so a found track whose first beat is not at 0:00 stays
+ * aligned; compose_score's tracks start on beat 0 and get an offset of 0.
+ */
+function readBedCues(projectRoot, bedFile) {
+    const stem = bedFile.replace(/\.[^.]+$/, "");
+    const cuesPath = path.join(projectRoot, "public", "audio", `${stem}.cues.json`);
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(cuesPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const bpm = raw.bpm;
+    if (typeof bpm !== "number" || !(bpm > 0))
+        return null;
+    const beats = Array.isArray(raw.beats) ? raw.beats : [];
+    const first = typeof beats[0] === "number" ? beats[0] : 0;
+    const out = { bpm, offsetSeconds: first };
+    if (typeof raw.track === "string")
+        out.track = raw.track;
+    if (Array.isArray(raw.sections)) {
+        out.sections = raw.sections
+            .filter((x) => typeof x.label === "string" && typeof x.startBar === "number" && typeof x.durationBars === "number")
+            .map((x) => ({ label: x.label, startBar: x.startBar, durationBars: x.durationBars }));
+    }
+    if (Array.isArray(raw.impacts)) {
+        out.impacts = raw.impacts
+            .filter((x) => typeof x.label === "string" && typeof x.atBar === "number")
+            .map((x) => ({ label: x.label, atBar: x.atBar, atBeat: typeof x.atBeat === "number" ? x.atBeat : 0 }));
+    }
+    return out;
+}
 function renderDemoTsx(opts) {
-    const { componentName, beats, voMap, musicBedFound } = opts;
+    const { componentName, beats, voByLanguage, baseLanguage, musicBedFile, musicBedVolume, musicBedSource, hasMusicCues, hasNarrationWords, hasOverrides, transitionHalf } = opts;
     const sceneImports = beats
-        .map((b) => `import { ${(0, util_1.pascalCase)(b.id)} } from "./scenes/${(0, util_1.pascalCase)(b.id)}";`)
+        .map((b) => `import { ${(0, util_1.pascalCase)(b.id)} } from "${sceneImportPath(b)}";`)
         .join("\n");
     const sceneMapLines = beats.map((b) => `  ${JSON.stringify(b.id)}: ${(0, util_1.pascalCase)(b.id)},`).join("\n");
-    const voLines = Object.entries(voMap)
-        .map(([id, rel]) => `  ${JSON.stringify(id)}: ${JSON.stringify(rel)},`)
+    const voBlocks = Object.entries(voByLanguage)
+        .map(([lang, map]) => {
+        const lines = Object.entries(map)
+            .map(([id, rel]) => `    ${JSON.stringify(id)}: ${JSON.stringify(rel)},`)
+            .join("\n");
+        return `  ${JSON.stringify(lang)}: {\n${lines}\n  },`;
+    })
         .join("\n");
-    const musicBedBlock = musicBedFound
-        ? `      <Sequence from={0} durationInFrames={DURATION_IN_FRAMES} layout="none">
-        <Audio src={staticFile("audio/music-bed.mp3")} volume={0.18} loop />
+    const musicBedBlock = musicBedFile
+        ? `      {/* ovs-music-source: ${musicBedSource} */}
+      <Sequence from={0} durationInFrames={DURATION_IN_FRAMES} layout="none">
+        <Audio src={staticFile(${JSON.stringify(`audio/${musicBedFile}`)})} volume={${musicBedVolume}} loop />
       </Sequence>
 `
         : "";
+    // overrides.tsx is a dev-authored extension point this tool only ever references, never
+    // writes: re-running stitch_composition regenerates everything above but always imports
+    // the same still-there file, so a hand-added layer survives a re-stitch instead of being
+    // clobbered by it.
+    const overridesImport = hasOverrides ? `import Overrides from "./overrides";\n` : "";
+    const overridesBlock = hasOverrides ? `      <Overrides />\n` : "";
+    // Emitted only when a beat asks for a transition, so a composition without one is
+    // byte-for-byte what it was before transitions existed.
+    const providerImports = hasNarrationWords ? "MusicClockProvider, NarrationWordsProvider" : "MusicClockProvider";
+    const coreImport = transitionHalf === null
+        ? `import { ${providerImports} } from "@openvidstudio/core";`
+        : `import { ${providerImports}, TransitionOverlay, type TransitionType } from "@openvidstudio/core";`;
+    const transitionConst = transitionHalf === null
+        ? ""
+        : `
+// Frames either side of a cut that a transition overlay covers (about 0.2s at any fps).
+// The overlay is drawn over the cut and never moves a beat boundary, so the Series, the VO
+// and the music all keep the timing beats.json gave them.
+const TRANSITION_HALF = ${transitionHalf};
+const transitionOf = (b: object): TransitionType | "cut" =>
+  ((b as Record<string, unknown>).transition as TransitionType | undefined) ?? "cut";
+`;
+    const transitionBlock = transitionHalf === null
+        ? ""
+        : `      {beats.beats
+        .filter((b) => b.start > 0 && transitionOf(b) !== "cut")
+        .map((b) => {
+          // Clamped so the overlay never starts before frame 0 or outlasts the beat it opens.
+          const half = Math.min(TRANSITION_HALF, b.start, b.duration);
+          return (
+            <Sequence key={\`transition-\${b.id}\`} from={b.start - half} durationInFrames={2 * half} layout="none">
+              <TransitionOverlay type={transitionOf(b)} length={2 * half} />
+            </Sequence>
+          );
+        })}
+`;
+    // One component per language, all wrapping the same inner one. The picture is identical
+    // across languages, so duplicating the scene tree per language would be a second copy of
+    // the thing most likely to be edited.
+    const languageComponents = Object.keys(voByLanguage)
+        .map((lang) => lang === baseLanguage
+        ? `export const ${componentName}: React.FC = () => <Narrated language=${JSON.stringify(lang)} />;`
+        : `export const ${componentName}${(0, util_1.pascalCase)(lang)}: React.FC = () => <Narrated language=${JSON.stringify(lang)} />;`)
+        .join("\n");
     return `// AUTO-GENERATED by openvidstudio's stitch_composition MCP tool from beats.json.
 // Re-run stitch_composition after editing beats.json rather than hand-editing this file;
 // it will be overwritten.
 
 import React from "react";
 import { AbsoluteFill, Audio, Sequence, Series, staticFile } from "remotion";
+${coreImport}
 import beats from "./beats.json";
-${sceneImports}
+${hasMusicCues ? `import musicCues from "./music.cues.json";
+` : ""}${hasNarrationWords ? `import narrationWords from "./narration.words.json";
+` : ""}${overridesImport}${sceneImports}
 
 const SCENES: Record<string, React.FC> = {
 ${sceneMapLines}
 };
 
-const VO_FILES: Record<string, string> = {
-${voLines}
+// Only the narration differs per language, so there is one scene tree and one audio map
+// per language over it.
+const VO_FILES: Record<string, Record<string, string>> = {
+${voBlocks}
 };
 
 const last = beats.beats[beats.beats.length - 1];
 export const DURATION_IN_FRAMES = last.start + last.duration;
-
-export const ${componentName}: React.FC = () => {
+${transitionConst}
+// The score's grid, handed to useMusicClock(beatId) in any scene. BEAT_STARTS turns the track's
+// bars into scene-local frames.
+const MUSIC_CUES = ${hasMusicCues ? "musicCues" : "null"};
+const BEAT_STARTS: Record<string, number> = Object.fromEntries(beats.beats.map((b) => [b.id, b.start]));
+${hasNarrationWords ? `
+// When each word of a beat's narration is said, per language, for useNarrationWords(beatId).
+type Words = { word: string; startMs: number; endMs: number }[];
+const NARRATION_WORDS = narrationWords as unknown as Record<string, Record<string, Words>>;
+` : ""}
+const Narrated: React.FC<{ language: string }> = ({ language }) => {
+  const vo = VO_FILES[language] ?? {};
   return (
     <AbsoluteFill>
-      <Series>
-        {beats.beats.map((b) => {
-          const Scene = SCENES[b.id];
-          return (
-            <Series.Sequence key={b.id} durationInFrames={b.duration} name={b.id}>
-              <Scene />
-            </Series.Sequence>
-          );
-        })}
-      </Series>
-      {beats.beats
-        .filter((b) => VO_FILES[b.id])
+${hasNarrationWords ? `      <NarrationWordsProvider words={NARRATION_WORDS[language] ?? {}}>
+` : ""}      <MusicClockProvider cues={MUSIC_CUES} beatStarts={BEAT_STARTS}>
+        <Series>
+          {beats.beats.map((b) => {
+            const Scene = SCENES[b.id];
+            return (
+              <Series.Sequence key={b.id} durationInFrames={b.duration} name={b.id}>
+                <Scene />
+              </Series.Sequence>
+            );
+          })}
+        </Series>
+      </MusicClockProvider>
+${hasNarrationWords ? `      </NarrationWordsProvider>
+` : ""}${transitionBlock}      {beats.beats
+        .filter((b) => vo[b.id])
         .map((b) => (
           <Sequence key={\`vo-\${b.id}\`} from={b.start} durationInFrames={b.duration} layout="none">
-            <Audio src={staticFile(VO_FILES[b.id])} volume={0.9} />
+            <Audio src={staticFile(vo[b.id])} volume={0.9} />
           </Sequence>
         ))}
-${musicBedBlock}    </AbsoluteFill>
+${musicBedBlock}${overridesBlock}    </AbsoluteFill>
   );
 };
+
+${languageComponents}
 `;
 }
 /**
@@ -157,7 +338,32 @@ ${musicBedBlock}    </AbsoluteFill>
  * public/audio/music-bed.mp3, included as a full-duration looping layer only if it
  * exists.
  */
+const LANGUAGE_TAG = /^[A-Za-z]{2,8}(-[A-Za-z0-9]{2,8})*$/;
+function sanitizeLanguage(tag) {
+    if (!LANGUAGE_TAG.test(tag)) {
+        throw new Error(`"${tag}" is not a BCP-47 language tag, and it is used as a directory name.`);
+    }
+    return tag;
+}
 function runStitchComposition(input) {
+    const result = stitchComposition(input);
+    (0, facts_1.writeFactRecord)((0, util_1.resolveProjectRoot)(input.projectRoot), {
+        tool: "stitch_composition",
+        videoName: (0, util_1.sanitizeSegment)(input.videoName, "videoName"),
+        facts: {
+            compositionId: result.compositionId,
+            durationInFrames: result.durationInFrames,
+            voBeatsFound: result.voBeatsFound,
+            voBeatsMissing: result.voBeatsMissing,
+            musicBedFound: result.musicBedFound,
+            musicBedFile: result.musicBedFile,
+            musicBedVolume: result.musicBedVolume,
+            warnings: result.warnings,
+        },
+    });
+    return result;
+}
+function stitchComposition(input) {
     const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
     const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
     const videoDir = path.join(projectRoot, "src", "videos", videoName);
@@ -170,36 +376,165 @@ function runStitchComposition(input) {
     if (!Array.isArray(beats) || beats.length === 0) {
         throw new Error(`${beatsPath} has no beats.`);
     }
+    for (const b of beats) {
+        if (b.scene)
+            (0, util_1.sanitizeRelativeOutPath)(videoDir, b.scene, `beat "${b.id}"'s scene`);
+    }
     const config = (0, config_1.loadConfig)(projectRoot);
     const fps = beatsData.fps ?? config.videoConfig.fps;
     const last = beats[beats.length - 1];
     const durationInFrames = last.start + last.duration;
-    const voMap = {};
-    for (const b of beats) {
-        const voFile = path.join(projectRoot, "public", "audio", "vo", `${b.id}.mp3`);
-        if (fs.existsSync(voFile)) {
-            voMap[b.id] = `audio/vo/${b.id}.mp3`;
+    const baseLanguage = sanitizeLanguage(input.baseLanguage ?? "en");
+    const languages = (input.languages?.length ? input.languages : [baseLanguage]).map(sanitizeLanguage);
+    if (!languages.includes(baseLanguage))
+        languages.unshift(baseLanguage);
+    const voByLanguage = {};
+    const warnings = [];
+    const languageReports = [];
+    /** language -> beatId -> [{ word, startMs, endMs }], for the beats that have word timings. */
+    const wordsByLanguage = {};
+    const componentName = `${(0, util_1.pascalCase)(videoName)}Demo`;
+    for (const language of languages) {
+        const isBase = language === baseLanguage;
+        // The base language keeps the original flat path, so nothing that already has
+        // narration has to move.
+        const publicRel = isBase ? "audio/vo" : `audio/vo/${language}`;
+        const map = {};
+        const words = {};
+        for (const b of beats) {
+            if (fs.existsSync(path.join(projectRoot, "public", ...publicRel.split("/"), `${b.id}.mp3`))) {
+                map[b.id] = `${publicRel}/${b.id}.mp3`;
+            }
+            // generate_narration's word timings, if this beat has them. Read here so they can be copied
+            // next to the composition: a scene bundle can import JSON from src/ but not from public/.
+            const wordsFile = path.join(projectRoot, "public", ...publicRel.split("/"), `${b.id}.words.json`);
+            if (fs.existsSync(wordsFile)) {
+                try {
+                    const parsed = JSON.parse(fs.readFileSync(wordsFile, "utf8"));
+                    if (Array.isArray(parsed) && parsed.length > 0)
+                        words[b.id] = parsed;
+                }
+                catch {
+                    warnings.push(`${path.relative(projectRoot, wordsFile)} is not valid JSON, so beat ${b.id} has no word timings. Re-run generate_narration with overwrite.`);
+                }
+            }
+        }
+        voByLanguage[language] = map;
+        if (Object.keys(words).length > 0)
+            wordsByLanguage[language] = words;
+        const missing = beats.map((b) => b.id).filter((id) => !(id in map));
+        // A video declared narration: "none" is silent on purpose. Warning that every beat has no voice
+        // contradicts the mode the beats file itself declares, and buries a real warning under eight
+        // that are not. requireNarration still means what it says, so it is not skipped.
+        const silentOnPurpose = beatsData.narration === "none" && input.requireNarration !== true;
+        if (missing.length > 0 && !silentOnPurpose) {
+            const detail = `${missing.length} of ${beats.length} beats have no ${language} narration file and will render ` +
+                `silent: ${missing.join(", ")}. Expected at public/${publicRel}/<beatId>.mp3. ` +
+                `Run generate_narration, or accept the silence deliberately.`;
+            // Per language, deliberately: a video that is fully narrated in English and half
+            // narrated in Hindi is a failure of the Hindi cut, and saying so once for the whole
+            // stitch would hide which cut is broken.
+            if (input.requireNarration === true) {
+                throw new Error(`Narration is required for this composition but ${detail}`);
+            }
+            warnings.push(detail);
         }
+        languageReports.push({
+            language,
+            compositionId: isBase ? componentName : `${componentName}${(0, util_1.pascalCase)(language)}`,
+            voBeatsFound: Object.keys(map),
+            voBeatsMissing: missing,
+        });
     }
-    const musicBedFound = fs.existsSync(path.join(projectRoot, "public", "audio", "music-bed.mp3"));
-    const componentName = `${(0, util_1.pascalCase)(videoName)}Demo`;
-    const demoTsx = renderDemoTsx({ componentName, beats, voMap, musicBedFound });
+    const voMap = voByLanguage[baseLanguage];
+    const voBeatsMissing = languageReports.find((r) => r.language === baseLanguage).voBeatsMissing;
     const demoPath = path.join(videoDir, `${componentName}.tsx`);
-    fs.writeFileSync(demoPath, demoTsx, "utf8");
-    const entries = readRegistry(projectRoot).filter((e) => e.videoName !== videoName);
-    entries.push({
-        id: componentName,
-        videoName,
+    const existingLayer = readExistingMusicLayer(demoPath);
+    const existingLayerUsable = existingLayer !== null &&
+        existingLayer.pinned &&
+        fs.existsSync(path.join(projectRoot, "public", "audio", existingLayer.file));
+    if (existingLayer?.pinned && !existingLayerUsable && !input.musicBed?.file) {
+        warnings.push(`The previous stitch used public/audio/${existingLayer.file} as the music bed, but that file is gone. ` +
+            `Falling back to auto-detection. Restore the file or pass musicBed to pick one explicitly.`);
+    }
+    let musicBedFile;
+    let musicBedSource;
+    if (input.musicBed?.file) {
+        const exists = fs.existsSync(path.join(projectRoot, "public", "audio", input.musicBed.file));
+        if (!exists) {
+            throw new Error(`musicBed.file "${input.musicBed.file}" does not exist at public/audio/${input.musicBed.file}`);
+        }
+        musicBedFile = input.musicBed.file;
+        musicBedSource = "explicit";
+    }
+    else if (existingLayer && existingLayerUsable) {
+        // A re-stitch must not undo a hand-picked track. Auto-detection only decides the first time.
+        musicBedFile = existingLayer.file;
+        musicBedSource = "preserved";
+    }
+    else {
+        const musicBedPresent = fs.existsSync(path.join(projectRoot, "public", "audio", "music-bed.mp3"));
+        musicBedFile = musicBedPresent ? "music-bed.mp3" : null;
+        musicBedSource = musicBedFile ? "auto" : "none";
+    }
+    const musicBedFound = musicBedFile !== null;
+    // No VO to duck under when narration is "none", so the bed defaults to full level instead
+    // of the 0.18 tuned for sitting quietly beneath narration. A preserved layer keeps the level
+    // it had, since that may have been tuned by hand.
+    const narrationMode = beatsData.narration === "none" ? "none" : "voice";
+    const musicBedVolume = input.musicBed?.volume ??
+        (musicBedSource === "preserved" && existingLayer ? existingLayer.volume : narrationMode === "none" ? 1.0 : 0.18);
+    const hasOverrides = fs.existsSync(path.join(videoDir, "overrides.tsx"));
+    // The bed's cue grid, copied next to the composition because a scene bundle can import JSON
+    // from src/ but not from public/. Trimmed to what useMusicClock reads.
+    const musicCuesAbs = path.join(videoDir, "music.cues.json");
+    const musicCues = musicBedFile ? readBedCues(projectRoot, musicBedFile) : null;
+    if (musicCues) {
+        fs.writeFileSync(musicCuesAbs, JSON.stringify(musicCues, null, 2) + "\n", "utf8");
+    }
+    else if (fs.existsSync(musicCuesAbs)) {
+        fs.rmSync(musicCuesAbs);
+    }
+    // The narration's word timings, copied next to the composition for the same reason as the cue grid.
+    // Written only when some beat has them, so a composition without them is exactly what it was before.
+    const narrationWordsAbs = path.join(videoDir, "narration.words.json");
+    const hasNarrationWords = Object.keys(wordsByLanguage).length > 0;
+    if (hasNarrationWords) {
+        fs.writeFileSync(narrationWordsAbs, JSON.stringify(wordsByLanguage, null, 2) + "\n", "utf8");
+    }
+    else if (fs.existsSync(narrationWordsAbs)) {
+        fs.rmSync(narrationWordsAbs);
+    }
+    const demoTsx = renderDemoTsx({
         componentName,
-        importPath: `./videos/${videoName}/${componentName}`,
-        durationInFrames,
-        fps,
-        width: config.videoConfig.width,
-        height: config.videoConfig.height,
+        beats,
+        voByLanguage,
+        baseLanguage,
+        musicBedFile,
+        musicBedVolume,
+        musicBedSource,
+        hasMusicCues: musicCues !== null,
+        hasNarrationWords,
+        hasOverrides,
+        transitionHalf: hasTransitions(beats) ? transitionHalfFrames(fps) : null,
     });
+    fs.writeFileSync(demoPath, demoTsx, "utf8");
+    const entries = readRegistry(projectRoot).filter((e) => e.videoName !== videoName);
+    for (const report of languageReports) {
+        entries.push({
+            id: report.compositionId,
+            videoName,
+            componentName: report.compositionId,
+            importPath: `./videos/${videoName}/${componentName}`,
+            durationInFrames,
+            fps,
+            width: config.videoConfig.width,
+            height: config.videoConfig.height,
+        });
+    }
     writeRegistry(projectRoot, entries);
     const rootPath = path.join(projectRoot, "src", "Root.tsx");
-    fs.writeFileSync(rootPath, renderRootTsx(entries), "utf8");
+    fs.writeFileSync(rootPath, renderRootTsx(entries, fs.existsSync(path.join(projectRoot, "src", "brand.ts"))), "utf8");
     return {
         written: true,
         compositionId: componentName,
@@ -207,7 +542,15 @@ function runStitchComposition(input) {
         rootPath,
         durationInFrames,
         voBeatsFound: Object.keys(voMap),
+        voBeatsMissing,
         musicBedFound,
+        musicBedFile,
+        musicBedVolume,
+        musicBedSource,
+        musicCuesPath: musicCues ? (0, facts_1.relToProject)(projectRoot, musicCuesAbs) : null,
+        overridesApplied: hasOverrides,
+        warnings,
+        languages: languageReports,
     };
 }
 function registerStitchComposition(server) {
@@ -216,15 +559,38 @@ function registerStitchComposition(server) {
         description: "Reads src/videos/<videoName>/beats.json and writes src/videos/<videoName>/<PascalName>Demo.tsx: a " +
             "SCENES map from beat id to its scaffold_scene component (imported from ./scenes/<BeatId>, the same " +
             "PascalCase convention scaffold_scene uses -- beats without a scaffolded scene file will fail to " +
-            "type-check, scaffold every beat first), a <Series> of <Series.Sequence> per beat, a VO Audio layer " +
+            "type-check, scaffold every beat first), a <Series> of <Series.Sequence> per beat (and, for each beat after the first whose transition is " +
+            "not \"cut\", a TransitionOverlay Sequence centred on the cut: drawn over it, so no beat start or " +
+            "duration moves; nothing is emitted when no beat has a transition), a VO Audio layer " +
             "per beat only where public/audio/vo/<beatId>.mp3 actually exists on disk, and a looping " +
-            "full-duration music bed layer if public/audio/music-bed.mp3 exists. Also (re)registers the " +
+            "full-duration music bed layer if public/audio/music-bed.mp3 exists. The scaffold ships an ambient " +
+            "music-bed.mp3 with no pulse to cut against; compose_score writes an original arc-matched score to the " +
+            "same name, with an exact cue grid next to it (plan_music_cues produces one for any other track), so " +
+            "scene cuts can land on a beat instead of an arbitrary second. Also (re)registers the " +
             "composition in src/Root.tsx (via an internal src/videos/.registry.json this tool owns), without " +
             "clobbering compositions a prior stitch_composition call registered for a different video in the " +
-            "same project.",
+            "same project. Pass languages to emit one composition per language: the picture is shared and only the "
+            + "narration layer differs, so the generated file carries one scene tree and one audio map per "
+            + "language, reading public/audio/vo/<lang>/<beatId>.mp3 for every language but the base, which "
+            + "keeps the original flat path. requireNarration is then enforced per language, because a video "
+            + "fully narrated in English and half narrated in Hindi is a failure of the Hindi cut and saying so "
+            + "once for the whole stitch would hide which cut is broken. Pass musicBed to override the "
+            + "auto-detected bed file and its mix level: file is a filename under public/audio/ (same convention "
+            + "as the auto-detected music-bed.mp3), volume defaults to 0.18 when beats.json's "
+            + "narration is \"voice\" or omitted (today's under-narration tuning) and 1.0 when narration is "
+            + "\"none\" (there is no VO to duck under). When musicBed is omitted and a previous stitch of this "
+            + "video already wrote a music layer whose file still exists, that track and level are preserved "
+            + "(musicBedSource: \"preserved\") instead of reverting to auto-detection. If src/videos/<videoName>/overrides.tsx exists, it is "
+            + "imported and rendered as an extra layer inside the composition on every stitch, a dev-authored "
+            + "extension point this tool only ever references and never writes, so it survives a re-stitch "
+            + "instead of being clobbered by one.",
         inputSchema: {
             projectRoot: zod_1.z.string().optional(),
             videoName: zod_1.z.string().min(1),
+            requireNarration: zod_1.z.boolean().optional(),
+            languages: zod_1.z.array(zod_1.z.string()).optional(),
+            baseLanguage: zod_1.z.string().optional(),
+            musicBed: zod_1.z.object({ file: zod_1.z.string().min(1), volume: zod_1.z.number().min(0).optional() }).optional(),
         },
     }, async (input) => (0, mcp_1.runTool)("stitch_composition", () => runStitchComposition(input)));
 }

package/dist/tools/validateBeats.d.ts

@@ -2,7 +2,28 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export interface ValidateBeatsResult {
     valid: boolean;
     errors: string[];
+    /**
+     * Things worth a second look that never make a draft invalid: write_beats_file still
+     * writes it. Empty when there is nothing to say.
+     */
+    warnings: string[];
 }
+export declare const MIN_PACE = 2.3;
+export declare const MAX_PACE = 2.9;
+/** SCRIPT.md's reading-time budget for onScreenText on a narration:"none" beat. */
+export declare const MAX_READING_WORDS_PER_SEC = 3.5;
+export declare const READING_OVERHEAD_SEC = 0.8;
+export declare function wordCount(text: string): number;
+/**
+ * SCRIPT.md's pacing rule for one spoken line: 2.3 to 2.9 words per second over the beat's length.
+ * `message` is the failure to report, or null when the line is inside the budget. validate_beats and
+ * check_script both read the budget from here, so there is one number.
+ */
+export declare function voPaceCheck(vo: string, seconds: number): {
+    words: number;
+    pace: number;
+    message: string | null;
+};
 /**
  * Mechanically enforces packages/docs/PLANNING.md §4 (captureMethod field spec) and
  * packages/docs/SCRIPT.md (VO pacing, no em dashes). Takes the drafted beats.json
@@ -11,4 +32,11 @@ export interface ValidateBeatsResult {
  * normal "no" answer, never a thrown exception.
  */
 export declare function validateBeatsLogic(beatsJson: unknown): ValidateBeatsResult;
+export interface ValidateBeatsInput {
+    beatsJson: unknown;
+    /** When set, the outcome is also kept as a run record for this video (see collect_facts). */
+    videoName?: string;
+    projectRoot?: string;
+}
+export declare function runValidateBeats(input: ValidateBeatsInput): ValidateBeatsResult;
 export declare function registerValidateBeats(server: McpServer): void;