@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/exportRendition.d.ts

@@ -0,0 +1,283 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Other renderers over the same beats.
+ *
+ * The capture engine and the manifest do not care that the output is a video. Video is one
+ * consumer of them, and it is not always the one a project needs: the most requested
+ * artefact in open source is a README GIF, docs want a numbered screenshot set that stays
+ * current, and an app listing wants frames at dimensions the store will actually accept.
+ * Each of those is a different renderer over the work already done, not a second pipeline.
+ *
+ * All three read the finished render plus beats.json rather than re-capturing, so the
+ * screenshots in the docs are frames of the same footage the video shows. That is what
+ * keeps them honest: a screenshot set assembled separately drifts from the video within a
+ * release or two, which is the whole problem with hand-made docs images.
+ */
+export type Rendition = "gif" | "screenshots" | "store-frames" | "poster" | "share" | "reels";
+export interface RenditionBeat {
+    id: string;
+    start: number;
+    duration: number;
+    vo?: string;
+    visual?: {
+        caption?: string;
+        captureMethod?: string;
+    };
+}
+export interface ExportRenditionInput {
+    projectRoot?: string;
+    videoName: string;
+    format: Rendition;
+    inPath?: string;
+    outDir?: string;
+    outPath?: string;
+    /** gif only. 12fps and 720px wide keeps a README GIF under a few megabytes. */
+    fps?: number;
+    width?: number;
+    /** store-frames only. */
+    device?: StoreDevice;
+    /** store-frames only: beats to export. Defaults to every beat. */
+    beatIds?: string[];
+    /** poster only. Which beat's midpoint to use as the poster frame. Defaults to the last beat. */
+    posterBeatId?: string;
+    /** poster only. Exact timestamp in seconds, overriding posterBeatId. */
+    posterAt?: number;
+    /**
+     * poster only, when neither posterAt nor posterBeatId is given. "auto" (the default) scores
+     * every beat's midpoint frame and takes the one that looks most like a representative
+     * picture: not blank, not flat, not near-black or blown out. See scoreFrameStats for exactly
+     * what is measured. "last" takes the last beat's midpoint instead (what this tool always did
+     * before auto scoring existed); pass it explicitly to keep that behavior.
+     */
+    posterPick?: "last" | "auto";
+    /** share only. The file size cap in megabytes (1MB = 1,000,000 bytes). Defaults to 10. */
+    maxMB?: number;
+    /** share only. Audio bitrate in kbps when the render has audio. Defaults to 96. */
+    audioKbps?: number;
+    /**
+     * poster only. Also write a copy of the render with the poster baked in as the file's
+     * embedded thumbnail (an attached_pic stream, the same mechanism a podcast mp3's cover
+     * art uses), so players and file browsers show it instead of a black or mid-motion first
+     * frame. Defaults to true. The picture itself is untouched frame-for-frame; only a
+     * thumbnail stream is added.
+     */
+    bake?: boolean;
+}
+export interface ExportRenditionResult {
+    format: Rendition;
+    files: string[];
+    indexPath?: string;
+    /** poster only, when bake was not disabled: the render with the poster baked in as its thumbnail. */
+    bakedPath?: string;
+    /** poster only, when posterPick was "auto": what was scored and which beat won. */
+    posterPick?: {
+        beatId: string;
+        seconds: number;
+        scores: {
+            beatId: string;
+            score: number;
+        }[];
+    };
+    /** share only: what was actually produced, measured from the file on disk. */
+    share?: ShareResult;
+    /** reels only: what was actually produced, measured from the file on disk. */
+    reels?: ReelsResult;
+    notes: string[];
+}
+export interface ReelsResult {
+    path: string;
+    bytes: number;
+    width: number;
+    height: number;
+    fps: number;
+    durationSec: number;
+    videoCodec: string;
+    /** Null when the source had no audio: none is made up. */
+    audioCodec: string | null;
+    /** False means the video stream was copied byte for byte and only the container was rewritten. */
+    videoReencoded: boolean;
+    audioReencoded: boolean;
+}
+export interface ShareResult {
+    path: string;
+    bytes: number;
+    maxBytes: number;
+    withinCap: boolean;
+    width: number;
+    height: number;
+    videoKbps: number;
+    audioKbps: number;
+    /** Encode attempts it took to land under the cap (1 means the first try fit). */
+    attempts: number;
+}
+/**
+ * Exact pixel dimensions each store demands. These are the sizes the review process
+ * rejects a submission over, which is precisely why doing this by hand is tedious and
+ * doing it from a capture pipeline is nearly free.
+ */
+export declare const STORE_DEVICES: {
+    readonly "iphone-6.9": {
+        readonly width: 1290;
+        readonly height: 2796;
+        readonly label: "App Store, 6.9 inch iPhone";
+    };
+    readonly "iphone-6.5": {
+        readonly width: 1242;
+        readonly height: 2688;
+        readonly label: "App Store, 6.5 inch iPhone";
+    };
+    readonly "ipad-13": {
+        readonly width: 2064;
+        readonly height: 2752;
+        readonly label: "App Store, 13 inch iPad";
+    };
+    readonly "android-phone": {
+        readonly width: 1080;
+        readonly height: 1920;
+        readonly label: "Play Store, phone";
+    };
+    readonly "android-tablet": {
+        readonly width: 1600;
+        readonly height: 2560;
+        readonly label: "Play Store, 10 inch tablet";
+    };
+};
+export type StoreDevice = keyof typeof STORE_DEVICES;
+/** Mid-beat, in seconds. The midpoint is past any transition in and before any transition out. */
+export declare function beatMidpointSeconds(beat: RenditionBeat, fps: number): number;
+/**
+ * Two-pass GIF, because the one-pass version is why most README GIFs look like that.
+ *
+ * A GIF is limited to 256 colours. Without a generated palette ffmpeg falls back to a
+ * fixed web-safe one and everything banding-dithers into mud, which is the difference
+ * between a GIF that sells the product and one that makes it look like a 2003 screencast.
+ */
+export declare function buildPaletteArgs(inPath: string, palettePath: string, fps: number, width: number): string[];
+export declare function buildGifArgs(inPath: string, palettePath: string, outPath: string, fps: number, width: number): string[];
+export declare function buildFrameArgs(inPath: string, seconds: number, outPath: string): string[];
+/**
+ * One store frame: the shot fitted inside the device's exact canvas, with a dark surround
+ * standing in for device chrome.
+ *
+ * Fitted rather than filled. A store frame that crops the product to fill the canvas
+ * removes exactly the UI the screenshot existed to show.
+ */
+export declare function buildStoreFrameArgs(inPath: string, seconds: number, outPath: string, device: {
+    width: number;
+    height: number;
+}, bezel: number): string[];
+/**
+ * Attaches a still image to a video as its embedded thumbnail, the mechanism a podcast
+ * mp3's cover art uses (an `attached_pic`-disposed stream), rather than by re-encoding the
+ * first frame. `-c copy` on the picture stream means the original video and audio are
+ * copied byte-for-byte, not re-encoded, so a poster bake never touches the render's actual
+ * quality: only a thumbnail stream is added.
+ */
+export declare function buildAttachPosterArgs(inPath: string, posterPath: string, outPath: string): string[];
+/** The docs index. Pairs every shot with what the video says over it, which is already written. */
+export declare function buildScreenshotIndex(videoName: string, entries: {
+    file: string;
+    beat: RenditionBeat;
+}[]): string;
+export interface FrameStats {
+    /** Mean luma, 0 to 255. */
+    mean: number;
+    /** Standard deviation of luma, 0 to 255: how much contrast the frame has. */
+    stdev: number;
+    /** Shannon entropy of the luma histogram, 0 to 8 bits: how much is going on in it. */
+    entropy: number;
+}
+/**
+ * Scores one frame as a poster candidate. A good poster is a picture with something in it, so
+ * the score is the frame's luma entropy (a flat or empty frame has little, a UI full of text and
+ * panels has a lot), scaled down when the frame has almost no contrast (stdev under 40) and cut
+ * to 30% when it is near-black or blown out (mean outside 30..225), which is what a fade or a
+ * transition frame looks like. It is a heuristic for "not a dud frame", not a taste judgement:
+ * pass posterBeatId or posterAt when a specific frame is wanted.
+ */
+export declare function scoreFrameStats(stats: FrameStats): number;
+/** The highest score wins; a tie goes to the earlier beat, since an opening frame is the safer poster. */
+export declare function pickBestScore(scores: {
+    beatId: string;
+    score: number;
+}[]): string;
+export interface SharePlan {
+    width: number;
+    height: number;
+    videoKbps: number;
+    audioKbps: number;
+    fps: number;
+    /** True when even the smallest rung falls under SHARE_MIN_BPP: the cap is tight for this duration. */
+    tight: boolean;
+}
+/**
+ * Turns a size cap into an encode: the bitrate that fits (cap, minus the audio, over the
+ * duration) and the largest resolution that bitrate can still carry without blocking. A fixed
+ * preset cannot do this; it either blows a short clip's budget on nothing or starves a long
+ * one. Pure, so the arithmetic is testable without encoding anything.
+ */
+export declare function planShareEncode(opts: {
+    maxBytes: number;
+    durationSec: number;
+    srcWidth: number;
+    srcHeight: number;
+    fps: number;
+    hasAudio: boolean;
+    audioKbps?: number;
+    /** Scales the video bitrate down on a retry after the first attempt landed over the cap. */
+    bitrateScale?: number;
+}): SharePlan;
+export declare function buildSharePassArgs(opts: {
+    inPath: string;
+    outPath: string;
+    plan: SharePlan;
+    pass: 1 | 2;
+    passLog: string;
+    hasAudio: boolean;
+}): string[];
+export interface ProbeInfo {
+    width: number;
+    height: number;
+    fps: number;
+    durationSec: number;
+    hasAudio: boolean;
+}
+export declare function probeMedia(inPath: string, cwd: string): Promise<ProbeInfo>;
+export interface ReelsSource {
+    width: number;
+    height: number;
+    fps: number;
+    videoCodec: string;
+    pixFmt: string;
+    audioCodec: string | null;
+}
+export type ReelsPlan = {
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    videoReencode: boolean;
+    audioReencode: boolean;
+    scale: boolean;
+    retime: boolean;
+};
+/**
+ * Decides what a source needs to become a Reels file, and nothing more. A 9:16 source that is
+ * already 1080x1920 H.264 yuv420p at 30fps keeps its video stream byte for byte, and AAC audio is
+ * copied too; only the container is rewritten so the moov atom leads. A source that is not 9:16 is
+ * refused: turning a 16:9 render into a vertical one means cropping or letterboxing it, which
+ * cuts diagrams off or shrinks them to a strip, and that is a choice for reformat_vertical or a
+ * native render, not something an export step should make silently. Pure, so the rules are
+ * testable without encoding anything.
+ */
+export declare function planReelsExport(src: ReelsSource): ReelsPlan;
+export declare function buildReelsArgs(opts: {
+    inPath: string;
+    outPath: string;
+    plan: Extract<ReelsPlan, {
+        ok: true;
+    }>;
+    hasAudio: boolean;
+}): string[];
+export declare function runExportRendition(input: ExportRenditionInput): Promise<ExportRenditionResult>;
+export declare function registerExportRendition(server: McpServer): void;