mulmocast 2.6.23 → 2.7.1

package/lib/cli/commands/translate/handler.js

@@ -1,10 +1,14 @@
 import { translate } from "../../../actions/index.js";
-import { dumpUsageIfRequested, initializeContext } from "../../helpers.js";
+import { dumpUsageIfRequested, initializeContext, printUsageEstimate } from "../../helpers.js";
 export const handler = async (argv) => {
     const context = await initializeContext(argv);
     if (!context) {
         process.exit(1);
     }
+    if (argv.estimate) {
+        printUsageEstimate(context, "translate", argv.json);
+        return;
+    }
     await translate(context);
     dumpUsageIfRequested(context);
 };

package/lib/cli/common.d.ts

@@ -1,4 +1,9 @@
 import type { Argv } from "yargs";
+export declare const estimateOptions: (yargs: Argv) => Argv<{
+    estimate: boolean;
+} & {
+    json: boolean;
+}>;
 export declare const commonOptions: (yargs: Argv) => Argv<{
     o: string | undefined;
 } & {

package/lib/cli/common.js

@@ -1,4 +1,17 @@
 import { languages } from "../types/const.js";
+export const estimateOptions = (yargs) => {
+    return yargs
+        .option("estimate", {
+        describe: "Estimate API usage (tokens / characters / seconds / cost) and exit without generating",
+        type: "boolean",
+        default: false,
+    })
+        .option("json", {
+        describe: "With --estimate, print the raw JSON records instead of a table",
+        type: "boolean",
+        default: false,
+    });
+};
 export const commonOptions = (yargs) => {
     return yargs
         .option("o", {

package/lib/cli/helpers.d.ts

@@ -1,7 +1,9 @@
+import { type EstimateAction } from "../utils/estimate_usage.js";
 import type { CliArgs } from "../types/cli_types.js";
 import { FileObject, InitOptions, MulmoStudioContext } from "../types/index.js";
 export declare const runTranslateIfNeeded: (context: MulmoStudioContext, includeCaption?: boolean) => Promise<void>;
 export declare const dumpUsageIfRequested: (context: MulmoStudioContext) => void;
+export declare const printUsageEstimate: (context: MulmoStudioContext, action: EstimateAction, asJson?: boolean) => void;
 export declare const setGraphAILogger: (verbose: boolean | undefined, logValues?: Record<string, unknown>) => void;
 export declare const getFileObject: (args: {
     basedir?: string;

package/lib/cli/helpers.js

@@ -8,6 +8,8 @@ import { outDirName, imageDirName, audioDirName } from "../types/const.js";
 import { MulmoStudioContextMethods } from "../methods/mulmo_studio_context.js";
 import { translate } from "../actions/translate.js";
 import { initializeContextFromFiles } from "../utils/context.js";
+import { estimateUsage, actionEstimateProcesses } from "../utils/estimate_usage.js";
+import { formatUsageEstimates } from "../utils/estimate_usage_format.js";
 export const runTranslateIfNeeded = async (context, includeCaption = false) => {
     if (MulmoStudioContextMethods.needTranslate(context, includeCaption)) {
         GraphAILogger.log("run translate");
@@ -60,6 +62,23 @@ export const dumpUsageIfRequested = (context) => {
     fs.writeFileSync(setting, json, "utf-8");
     GraphAILogger.info(`usage written to ${setting}`);
 };
+// Pre-run estimate for --estimate: scoped to what the invoked action would consume,
+// resolved with the same context (script, presentation style, -l, caption lang) as a real run.
+export const printUsageEstimate = (context, action, asJson = false) => {
+    const script = context.studio.script;
+    const lang = context.lang;
+    // The caption language triggers translation only where the real run does:
+    // movie (runTranslateIfNeeded with includeCaption) and the translate action itself.
+    const captionLang = action === "movie" || action === "translate" ? script.captionParams?.lang : undefined;
+    const targetLangs = [...new Set([lang, captionLang].filter((l) => !!l))];
+    const records = estimateUsage(script, {
+        presentationStyle: context.presentationStyle,
+        langs: lang ? [lang] : undefined,
+        targetLangs,
+        processes: actionEstimateProcesses[action],
+    });
+    GraphAILogger.info(asJson ? JSON.stringify(records, null, 2) : formatUsageEstimates(records));
+};
 export const setGraphAILogger = (verbose, logValues) => {
     if (verbose) {
         if (logValues) {

package/lib/index.common.d.ts

@@ -5,6 +5,8 @@ export * from "./utils/string.js";
 export * from "./utils/utils.js";
 export * from "./utils/prompt.js";
 export * from "./utils/error_cause.js";
+export * from "./utils/estimate_usage.js";
+export * from "./utils/estimate_usage_format.js";
 export * from "./methods/mulmo_presentation_style.js";
 export * from "./methods/mulmo_script.js";
 export * from "./methods/mulmo_studio_context.js";

package/lib/index.common.js

@@ -6,6 +6,8 @@ export * from "./utils/string.js";
 export * from "./utils/utils.js";
 export * from "./utils/prompt.js";
 export * from "./utils/error_cause.js";
+export * from "./utils/estimate_usage.js";
+export * from "./utils/estimate_usage_format.js";
 export * from "./methods/mulmo_presentation_style.js";
 export * from "./methods/mulmo_script.js";
 export * from "./methods/mulmo_studio_context.js";

package/lib/methods/mulmo_media_source.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import { GraphAILogger, assert } from "graphai";
 import { getFullPath, getReferenceImagePath, resolveAssetPath } from "../utils/file.js";
+import { safeFetch, DEFAULT_FETCH_TIMEOUT_MS } from "../utils/fetch.js";
 import { downLoadReferenceImageError, getTextError, imageReferenceUnknownMediaError, downloadImagePluginError, imagePluginUnknownMediaError, mediaSourceToDataUrlError, mediaSourceFileNotFoundError, mediaSourceUnknownKindError, } from "../utils/error_cause.js";
 // for image reference
 export const getExtention = (contentType, url) => {
@@ -18,7 +19,7 @@ export const getExtention = (contentType, url) => {
     return "png"; // default
 };
 const downLoadReferenceImage = async (context, key, url) => {
-    const response = await fetch(url);
+    const response = await safeFetch(url);
     assert(response.ok, `Failed to download reference image: ${url}`, false, downLoadReferenceImageError(key, url));
     const buffer = Buffer.from(await response.arrayBuffer());
     // Detect file extension from Content-Type header or URL
@@ -38,26 +39,21 @@ function pluginSourceFixExtention(path, imageType) {
     return path;
 }
 // end of util
-const DEFAULT_FETCH_TIMEOUT_MS = 30000;
 // Convert URL to data URL (base64 encoded)
 const urlToDataUrl = async (url, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) => {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        const response = await fetch(url, { signal: controller.signal });
+        const response = await safeFetch(url, {}, timeoutMs);
         assert(response.ok, `Failed to fetch: ${url}`, false, mediaSourceToDataUrlError(url));
         const buffer = Buffer.from(await response.arrayBuffer());
         const contentType = response.headers.get("content-type") || "image/png";
         return `data:${contentType};base64,${buffer.toString("base64")}`;
     }
     catch (error) {
-        if (error instanceof Error && error.name === "AbortError") {
-            throw new Error(`Fetch timeout: ${url}`, { cause: mediaSourceToDataUrlError(url) });
+        // assert() failures already carry the structured cause — keep it as-is.
+        if (error instanceof Error && error.cause) {
+            throw error;
         }
-        throw new Error(`Fetch failed: ${url}`, { cause: mediaSourceToDataUrlError(url) });
-    }
-    finally {
-        clearTimeout(timeoutId);
+        throw new Error(`Fetch failed: ${url}: ${error instanceof Error ? error.message : String(error)}`, { cause: mediaSourceToDataUrlError(url) });
     }
 };
 /** Map file extension to MIME type for data URLs */
@@ -92,7 +88,7 @@ export const MulmoMediaSourceMethods = {
             return mediaSource.text;
         }
         if (mediaSource.kind === "url") {
-            const response = await fetch(mediaSource.url);
+            const response = await safeFetch(mediaSource.url);
             assert(response.ok, `Failed to download mermaid code text: ${mediaSource.url}`, false, getTextError(mediaSource.url)); // TODO: index
             return await response.text();
         }
@@ -126,7 +122,7 @@ export const MulmoMediaSourceMethods = {
     },
     async imagePluginSource(mediaSource, context, expectImagePath, imageType) {
         if (mediaSource.kind === "url") {
-            const response = await fetch(mediaSource.url);
+            const response = await safeFetch(mediaSource.url);
             assert(response.ok, `Failed to download image plugin: ${imageType} ${mediaSource.url}`, false, downloadImagePluginError(mediaSource.url, imageType)); // TODO: key, id, index
             const buffer = Buffer.from(await response.arrayBuffer());
             // Detect file extension from Content-Type header or URL

package/lib/methods/mulmo_presentation_style.d.ts

@@ -27,6 +27,7 @@ export declare const MulmoPresentationStyleMethods: {
      */
     getResolvedSlideTheme(presentationStyle: MulmoPresentationStyle, beat: MulmoBeat): SlideTheme;
     getDefaultSpeaker(presentationStyle: MulmoPresentationStyle): string;
+    getSpeakerData(presentationStyle: MulmoPresentationStyle, beat: MulmoBeat, lang: string | undefined): SpeakerData;
     getSpeaker(context: MulmoStudioContext, beat: MulmoBeat, targetLang: string | undefined): SpeakerData;
     getMovieTransition(context: MulmoStudioContext, beat: MulmoBeat): MulmoTransition | null;
     getText2ImageProvider(provider: Text2ImageProvider | undefined): Text2ImageProvider;
@@ -222,6 +223,7 @@ export declare const MulmoPresentationStyleMethods: {
             video?: string;
             audio: string;
             image?: string;
+            price_per_sec?: number;
         }>;
     };
     /** Concurrency for image/movie generation graph (uses min of imageParams/movieParams) */

package/lib/methods/mulmo_presentation_style.js

@@ -73,19 +73,22 @@ export const MulmoPresentationStyleMethods = {
         }
         return keys[0];
     },
-    getSpeaker(context, beat, targetLang) {
-        userAssert(!!context.presentationStyle?.speechParams?.speakers, "presentationStyle.speechParams.speakers is not set!!");
-        const speakerId = beat?.speaker ?? MulmoPresentationStyleMethods.getDefaultSpeaker(context.presentationStyle);
-        const speaker = context.presentationStyle.speechParams.speakers[speakerId];
+    getSpeakerData(presentationStyle, beat, lang) {
+        userAssert(!!presentationStyle?.speechParams?.speakers, "presentationStyle.speechParams.speakers is not set!!");
+        const speakerId = beat?.speaker ?? MulmoPresentationStyleMethods.getDefaultSpeaker(presentationStyle);
+        const speaker = presentationStyle.speechParams.speakers[speakerId];
         userAssert(!!speaker, `speaker is not set: speaker "${speakerId}"`);
         // Check if the speaker has a language-specific version.
-        // Normally, lang is determined by the context, but lang may be specified when using the API.
-        const lang = targetLang ?? context.lang ?? context?.studio?.script?.lang;
         if (speaker.lang && lang && speaker.lang[lang]) {
             return speaker.lang[lang];
         }
         return speaker;
     },
+    getSpeaker(context, beat, targetLang) {
+        // Normally, lang is determined by the context, but lang may be specified when using the API.
+        const lang = targetLang ?? context.lang ?? context?.studio?.script?.lang;
+        return MulmoPresentationStyleMethods.getSpeakerData(context.presentationStyle, beat, lang);
+    },
     getMovieTransition(context, beat) {
         const transitionData = beat.movieParams?.transition ?? context.presentationStyle.movieParams?.transition;
         if (!transitionData)

package/lib/types/index.d.ts

@@ -2,3 +2,4 @@ export * from "./type.js";
 export * from "./schema.js";
 export * from "./viewer.js";
 export * from "./usage.js";
+export * from "./provider2agent.js";

package/lib/types/index.js

@@ -2,3 +2,4 @@ export * from "./type.js";
 export * from "./schema.js";
 export * from "./viewer.js";
 export * from "./usage.js";
+export * from "./provider2agent.js";

package/lib/types/provider2agent.d.ts

@@ -158,6 +158,7 @@ export declare const provider2LipSyncAgent: {
             video?: string;
             audio: string;
             image?: string;
+            price_per_sec?: number;
         }>;
     };
 };
@@ -213,4 +214,20 @@ export declare const llm: (keyof typeof provider2LLMAgent)[];
 export type LLM = keyof typeof provider2LLMAgent;
 export declare const htmlLLMProvider: string[];
 export declare const getModelDuration: (provider: keyof typeof provider2MovieAgent, model: string, movieDuration?: number) => number | undefined;
+export type ModelPricing = {
+    unit: "tokens" | "chars" | "seconds" | "images";
+    inputPerMTokensUSD?: number;
+    outputPerMTokensUSD?: number;
+    perMCharsUSD?: number;
+    perSecUSD?: number;
+    perImageUSD?: number;
+    asOf: string;
+};
+export declare const gptImageOutputTokens: Record<string, {
+    low: number;
+    medium: number;
+    high: number;
+}>;
+export declare const modelPricing: Record<string, Record<string, ModelPricing>>;
+export declare const getModelPricing: (provider: string, model: string) => ModelPricing | undefined;
 export {};

package/lib/types/provider2agent.js

@@ -517,3 +517,82 @@ export const getModelDuration = (provider, model, movieDuration) => {
     }
     return durations?.[0];
 };
+// gpt-image-1 / gpt-image-1-mini emit a fixed number of image output tokens per size × quality.
+// Later gpt-image models (1.5 / 2) use variable resolutions, so this table is only an approximation for them.
+// Source: https://developers.openai.com/api/docs/guides/image-generation (verified 2026-07-03)
+export const gptImageOutputTokens = {
+    "1024x1024": { low: 272, medium: 1056, high: 4160 },
+    "1024x1536": { low: 408, medium: 1584, high: 6240 },
+    "1536x1024": { low: 400, medium: 1568, high: 6208 },
+};
+// Spot-checked against replicate.com model pages on this date (seedance-1-lite, kling-v2.1, omni-human).
+// Some replicate prices vary by resolution/variant; price_per_sec holds the rate for the typical configuration
+// (e.g. seedance-1-lite at 720p, kling-v2.1 standard).
+const REPLICATE_PRICING_AS_OF = "2026-07-03";
+const replicateMoviePricing = Object.fromEntries(Object.entries(provider2MovieAgent.replicate.modelParams).map(([model, params]) => [
+    model,
+    { unit: "seconds", perSecUSD: params.price_per_sec, asOf: REPLICATE_PRICING_AS_OF },
+]));
+const replicateLipSyncPricing = Object.fromEntries(Object.entries(provider2LipSyncAgent.replicate.modelParams)
+    .filter(([, params]) => params.price_per_sec !== undefined)
+    .map(([model, params]) => [model, { unit: "seconds", perSecUSD: params.price_per_sec, asOf: REPLICATE_PRICING_AS_OF }]));
+export const modelPricing = {
+    openai: {
+        // https://developers.openai.com/api/docs/models/gpt-4o-mini-tts
+        "gpt-4o-mini-tts": { unit: "tokens", inputPerMTokensUSD: 0.6, outputPerMTokensUSD: 12, asOf: "2026-07-03" },
+        "tts-1": { unit: "chars", perMCharsUSD: 15, asOf: "2026-07-03" },
+        "tts-1-hd": { unit: "chars", perMCharsUSD: 30, asOf: "2026-07-03" },
+        // https://developers.openai.com/api/docs/models/gpt-image-1 (image input tokens, $10/1M, are not modeled)
+        "gpt-image-1": { unit: "tokens", inputPerMTokensUSD: 5, outputPerMTokensUSD: 40, asOf: "2026-07-03" },
+        "gpt-image-1.5": { unit: "tokens", inputPerMTokensUSD: 5, outputPerMTokensUSD: 32, asOf: "2026-07-03" },
+        "gpt-image-2": { unit: "tokens", inputPerMTokensUSD: 5, outputPerMTokensUSD: 30, asOf: "2026-07-03" },
+        "gpt-image-1-mini": { unit: "tokens", inputPerMTokensUSD: 2, outputPerMTokensUSD: 8, asOf: "2026-07-03" },
+        // https://developers.openai.com/api/docs/models/gpt-5 etc.
+        "gpt-5": { unit: "tokens", inputPerMTokensUSD: 1.25, outputPerMTokensUSD: 10, asOf: "2026-07-03" },
+        "gpt-5-mini": { unit: "tokens", inputPerMTokensUSD: 0.25, outputPerMTokensUSD: 2, asOf: "2026-07-03" },
+        "gpt-4o": { unit: "tokens", inputPerMTokensUSD: 2.5, outputPerMTokensUSD: 10, asOf: "2026-07-03" },
+    },
+    gemini: {
+        // https://ai.google.dev/gemini-api/docs/pricing
+        "gemini-2.5-flash-preview-tts": { unit: "tokens", inputPerMTokensUSD: 0.5, outputPerMTokensUSD: 10, asOf: "2026-07-03" },
+        "gemini-2.5-pro-preview-tts": { unit: "tokens", inputPerMTokensUSD: 1, outputPerMTokensUSD: 20, asOf: "2026-07-03" },
+    },
+    google: {
+        // https://ai.google.dev/gemini-api/docs/pricing ($0.039/image ≒ 1290 output tokens at $30/1M)
+        "gemini-2.5-flash-image": { unit: "images", inputPerMTokensUSD: 0.3, perImageUSD: 0.039, asOf: "2026-07-03" },
+        // Veo per second of generated video (720p). veo-2.0-generate-001 and veo-3.0-generate-001
+        // were shut down on 2026-06-30, so they intentionally have no price.
+        "veo-3.1-generate-preview": { unit: "seconds", perSecUSD: 0.4, asOf: "2026-07-03" },
+        "veo-3.1-lite-generate-preview": { unit: "seconds", perSecUSD: 0.05, asOf: "2026-07-03" },
+        // Google Cloud Text-to-Speech per 1M characters, keyed by voice tier.
+        // https://cloud.google.com/text-to-speech/pricing
+        "tts-standard": { unit: "chars", perMCharsUSD: 4, asOf: "2026-07-03" },
+        "tts-wavenet": { unit: "chars", perMCharsUSD: 4, asOf: "2026-07-03" },
+        "tts-neural2": { unit: "chars", perMCharsUSD: 16, asOf: "2026-07-03" },
+        "tts-chirp3-hd": { unit: "chars", perMCharsUSD: 30, asOf: "2026-07-03" },
+        "tts-studio": { unit: "chars", perMCharsUSD: 160, asOf: "2026-07-03" },
+    },
+    anthropic: {
+        // https://platform.claude.com/docs/en/docs/about-claude/pricing
+        "claude-sonnet-4-5-20250929": { unit: "tokens", inputPerMTokensUSD: 3, outputPerMTokensUSD: 15, asOf: "2026-07-03" },
+    },
+    elevenlabs: {
+        // https://elevenlabs.io/pricing/api ($0.10 per 1k chars for multilingual/v3, $0.05 for flash/turbo)
+        eleven_v3: { unit: "chars", perMCharsUSD: 100, asOf: "2026-07-03" },
+        eleven_multilingual_v2: { unit: "chars", perMCharsUSD: 100, asOf: "2026-07-03" },
+        eleven_turbo_v2_5: { unit: "chars", perMCharsUSD: 50, asOf: "2026-07-03" },
+        eleven_turbo_v2: { unit: "chars", perMCharsUSD: 50, asOf: "2026-07-03" },
+        eleven_flash_v2_5: { unit: "chars", perMCharsUSD: 50, asOf: "2026-07-03" },
+        eleven_flash_v2: { unit: "chars", perMCharsUSD: 50, asOf: "2026-07-03" },
+    },
+    replicate: {
+        ...replicateMoviePricing,
+        ...replicateLipSyncPricing,
+        // https://replicate.com/bytedance/seedream-4 ($0.03 per output image)
+        // zsxkib/mmaudio is intentionally unpriced: it bills by GPU time (~$0.005 per run), not by clip duration.
+        "bytedance/seedream-4": { unit: "images", perImageUSD: 0.03, asOf: "2026-07-03" },
+    },
+};
+export const getModelPricing = (provider, model) => {
+    return modelPricing[provider]?.[model];
+};

package/lib/types/usage.d.ts

@@ -30,3 +30,24 @@ export type UsageCollectorAPI = {
     clear(): void;
     readonly size: number;
 };
+export type EstimatePrecision = "exact" | "estimated";
+export type EstimatedMetric = {
+    value: number;
+    precision: EstimatePrecision;
+};
+export type UsageEstimateProcess = "tts" | "image" | "htmlImage" | "movie" | "soundEffect" | "lipSync" | "translate" | "imageReference" | "movieReference";
+export type UsageEstimate = {
+    process: UsageEstimateProcess;
+    beatIndex?: number;
+    refKey?: string;
+    lang?: string;
+    provider: string;
+    model: string;
+    inputTokens?: EstimatedMetric;
+    outputTokens?: EstimatedMetric;
+    inputChars?: EstimatedMetric;
+    predictSec?: EstimatedMetric;
+    imageCount?: EstimatedMetric;
+    costUSD?: number;
+    pricingAsOf?: string;
+};

package/lib/utils/estimate_usage.d.ts

@@ -0,0 +1,11 @@
+import type { MulmoScript, MulmoPresentationStyle } from "../types/index.js";
+import type { UsageEstimate, UsageEstimateProcess } from "../types/usage.js";
+export type EstimateUsageOptions = {
+    langs?: string[];
+    targetLangs?: string[];
+    presentationStyle?: MulmoPresentationStyle;
+    processes?: UsageEstimateProcess[];
+};
+export type EstimateAction = "audio" | "images" | "pdf" | "movie" | "translate";
+export declare const actionEstimateProcesses: Record<EstimateAction, UsageEstimateProcess[]>;
+export declare const estimateUsage: (script: MulmoScript, options?: EstimateUsageOptions) => UsageEstimate[];