@openvidstudio/mcp-server 1.3.1 → 1.4.0

package/dist/canvasExplainer.d.ts

@@ -0,0 +1,198 @@
+import type { Browser, Page } from "playwright";
+import type { SceneFinding } from "./tools/validateScenes";
+/**
+ * Turns a canvas explainer into a video. A canvas explainer is one self-contained HTML file with a canvas
+ * and three promises: `window.seek(t)` draws the frame at time `t` (seconds) as a pure function of `t`,
+ * `window.DURATION` is its length in seconds, and `window.scoreSound(kit)` is its Web Audio score, rendered
+ * offline through `window.SOUND.renderOffline(scoreSound, seconds, sampleRate, { voiceover })`.
+ *
+ * The renderer loads the file in headless Chromium, walks the frames, pipes the canvas PNGs into ffmpeg,
+ * renders the score, optionally mixes the narration clips of a project over it, and muxes the two. It can run
+ * from the MCP tool (tools/renderCanvasExplainer.ts) or standalone:
+ *
+ *   node dist/canvasExplainer.js --html explainer.html --out out.mp4 [--width 1280 --height 720 --fps 30 --video name]
+ */
+export declare const DEFAULT_CANVAS_WIDTH = 1280;
+export declare const DEFAULT_CANVAS_HEIGHT = 720;
+export declare const DEFAULT_CANVAS_FPS = 30;
+export declare const AUDIO_SAMPLE_RATE = 48000;
+/** How far the score sits under a narration clip while it plays, in dB. At least 6 is promised. */
+export declare const DEFAULT_DUCK_DB = 9;
+/** Seconds a caption stays after its last word is said, if the next one has not started. */
+export declare const CAPTION_HOLD_SECONDS = 0.3;
+/** One beat as the explainer sees it in `window.BEATS`: seconds, and the line spoken in it. */
+export interface CanvasBeat {
+    id: string;
+    start: number;
+    end: number;
+    text: string;
+}
+export interface CanvasAudioOptions {
+    /** Drop beds and music and lower effects in the sound kit. Default: on when a project's beats are used with narration. */
+    voiceover?: boolean;
+    sampleRate?: number;
+    /** dB the score ducks under a narration clip. Default 9. */
+    duckDb?: number;
+}
+export interface CanvasExplainerInput {
+    projectRoot?: string;
+    /** The explainer, absolute or relative to the project root. */
+    htmlPath: string;
+    /** The mp4 to write, relative to the project root (or absolute). */
+    outPath: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    /** false for a silent video, or the sound options. */
+    audio?: false | CanvasAudioOptions;
+    /** A video of the project: its beats.json becomes `window.BEATS`, and its narration clips are mixed in. */
+    videoName?: string;
+    /** Burn the beats' text in as captions. Default true when there is narration. */
+    captions?: boolean;
+    /** Run validate_canvas_explainer first and refuse to render on an error. Default true. */
+    validate?: boolean;
+}
+export interface CanvasRenderProgress {
+    framesRendered: number;
+    totalFrames: number;
+}
+export interface CanvasExplainerResult {
+    success: true;
+    outPath: string;
+    width: number;
+    height: number;
+    fps: number;
+    durationSeconds: number;
+    frames: number;
+    /** SHA-256 of the PNG the page produced for the first, middle and last frame: the purity promise, as numbers. */
+    frameHashes: {
+        first: string;
+        middle: string;
+        last: string;
+    };
+    audio: {
+        included: boolean;
+        sampleRate: number | null;
+        voiceover: boolean;
+        /** The narration clips mixed in, with the sample the voice starts at. */
+        voiceClips: {
+            beatId: string;
+            startSeconds: number;
+            startSample: number;
+            durationSeconds: number;
+        }[];
+        duckDb: number | null;
+    };
+    captions: {
+        burned: boolean;
+        chunks: number;
+    };
+    warnings: string[];
+    /** The pre-flight's findings (warnings and notes; an error would have stopped the render). */
+    findings: SceneFinding[];
+}
+/** The caption chunks of a project, with the seconds each one is on screen. */
+export interface CaptionChunk {
+    beatId: string;
+    from: number;
+    to: number;
+    text: string;
+}
+export interface CanvasProject {
+    beats: CanvasBeat[];
+    /** "none" for a silent lesson: no clips, no captions. */
+    narration: "voice" | "none";
+    clips: {
+        beatId: string;
+        start: number;
+        file: string;
+    }[];
+    chunks: CaptionChunk[];
+}
+/** Sentence-end and comma rules of LessonCaptions (packages/stem), so a canvas lesson captions the same way. */
+export declare function captionChunks(words: string[], maxWords?: number): [number, number][];
+/** Pure: the caption chunks of one beat, timed from word times when they are known and evenly by length when not. */
+export declare function chunksForBeat(beat: CanvasBeat, spokenSeconds: number, words?: {
+    startMs: number;
+    endMs: number;
+}[]): CaptionChunk[];
+/** Reads a project's beats.json into what a canvas explainer needs. */
+export declare function readCanvasProject(projectRoot: string, videoName: string): CanvasProject;
+/** Runs before the explainer's own scripts: the size, the beats, the captions helper. */
+export declare function bootScript(cfg: {
+    width: number;
+    height: number;
+    fps: number;
+    voiceover: boolean;
+    beats: CanvasBeat[] | null;
+    chunks: CaptionChunk[];
+    probes: boolean;
+}): string;
+export interface OpenedExplainer {
+    page: Page;
+    durationSeconds: number;
+    width: number;
+    height: number;
+    /** Set when the canvas was not the size asked for and was resized. */
+    resized: boolean;
+    /** The DURATION the file itself declared, before a beats file's last end replaced it. */
+    ownDuration: number;
+    errors: string[];
+}
+/** Loads the file and checks it keeps its three promises. */
+export declare function openExplainer(browser: Browser, htmlPath: string, cfg: {
+    width: number;
+    height: number;
+    fps: number;
+    voiceover: boolean;
+    project: CanvasProject | null;
+    probes: boolean;
+    requireScore: boolean;
+}): Promise<OpenedExplainer>;
+/** Seeks to `t` and returns the canvas as PNG bytes. An explainer that did not draw captions gets them from the renderer. */
+export declare function captureFrame(page: Page, t: number): Promise<Buffer>;
+export interface PcmAudio {
+    sampleRate: number;
+    channels: number;
+    /** Interleaved. */
+    data: Float32Array;
+}
+/** Renders the explainer's score through its sound kit. */
+export declare function renderScore(page: Page, durationSeconds: number, sampleRate: number, voiceover: boolean): Promise<PcmAudio>;
+/** Pure: `audio` as stereo, so mixing and writing deal with one shape. */
+export declare function toStereo(audio: PcmAudio): PcmAudio;
+export interface MixResult {
+    audio: PcmAudio;
+    clips: {
+        beatId: string;
+        startSeconds: number;
+        startSample: number;
+        durationSeconds: number;
+    }[];
+}
+/**
+ * Mixes narration clips over a score. Each clip starts at its beat's start (to the sample), and the score is
+ * ducked by `duckDb` while any clip plays: eased down over 40 ms and back up over 250 ms, so it does not pump.
+ */
+export declare function mixVoice(score: PcmAudio, clips: {
+    beatId: string;
+    start: number;
+    file: string;
+}[], duckDb: number): MixResult;
+/** A 32-bit float WAV, which ffmpeg reads directly. */
+export declare function wavBytes(audio: PcmAudio): Buffer;
+/** The warnings that need only the source. */
+export declare function sourceWarnings(html: string, file: string): string[];
+interface Resolved {
+    projectRoot: string;
+    htmlPath: string;
+    outPath: string;
+    width: number;
+    height: number;
+    fps: number;
+}
+export declare function resolveCanvasInput(input: CanvasExplainerInput): Resolved;
+export declare function runCanvasExplainer(input: CanvasExplainerInput, opts?: {
+    onProgress?: (p: CanvasRenderProgress) => void;
+}): Promise<CanvasExplainerResult>;
+export {};