mulmocast 2.6.22 → 2.7.0

package/README.md

@@ -419,6 +419,30 @@ Payload shape:
 
 `byModel` groups by `provider:model` (different models have different rate cards, so summing across them isn't meaningful). The full per-call snapshot is also included so a billing layer can apply its own grouping. See [docs/api.md § Usage tracking](./docs/api.md#usage-tracking) for the per-agent field-population matrix and the programmatic (library) API.
 
+### Usage estimation (before running anything)
+
+Every generation command accepts `--estimate`: it prints what the command would consume — scoped to that command's pipeline — and exits without generating:
+
+```bash
+mulmo movie script.json --estimate         # table per provider:model + total cost
+mulmo audio script.json --estimate --json  # raw UsageEstimate[] records (pipe-friendly)
+```
+
+`mulmo audio --estimate` covers TTS (plus translation when `-l` differs from the script language); `mulmo images` / `mulmo pdf` cover image, htmlImage, movie, sound-effect, lip-sync and reference-media generation; `mulmo movie` covers everything; `mulmo translate` only translation. Values marked `~` are heuristic estimates; unmarked values are exact for the given script.
+
+The library API can estimate the same thing — per beat, per process — without calling any API:
+
+```typescript
+import { estimateUsage } from "mulmocast";
+
+const estimates = estimateUsage(script, { targetLangs: ["ja"] });
+// [{ process: "tts", beatIndex: 0, provider: "openai", model: "gpt-4o-mini-tts",
+//    inputChars: { value: 50, precision: "exact" }, outputTokens: { value: 150, precision: "estimated" },
+//    costUSD: 0.0019, pricingAsOf: "2026-07-03" }, ...]
+```
+
+Each metric carries a `precision` flag: `"exact"` for values that are deterministic from the script (TTS character counts, tokenized OpenAI prompts, fixed image-output token tables) and `"estimated"` for heuristics (LLM output length, speech duration derived from text). `costUSD` appears when pricing data exists in `modelPricing` (`src/types/provider2agent.ts`), where every price records the date it was last verified. See [docs/api.md § Pre-run estimation](./docs/api.md#pre-run-estimation-estimateusage).
+
 ## Cache and Re-run
 When running the same `mulmo` command multiple times, previously generated files are treated as cache. For example, audio or image files will not be regenerated if they already exist.
 

package/lib/agents/tts_elevenlabs_agent.js

@@ -44,7 +44,12 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
                 };
             }
             GraphAILogger.info(e);
-            throw new Error("TTS Eleven Labs Error", {
+            // Include the underlying message so fetch failures (DNS / TLS /
+            // ETIMEDOUT / ECONNRESET) are diagnosable from the thrown error
+            // — previously every such case collapsed to the static label.
+            // Same template as #1452 / #1453 / #1454 / #1455 / #1456 / #1457.
+            const detail = e instanceof Error ? e.message : String(e);
+            throw new Error(`TTS Eleven Labs Error: ${detail}`, {
                 cause: agentGenerationError("ttsElevenlabsAgent", audioAction, audioFileTarget),
             });
         }

package/lib/cli/commands/audio/builder.d.ts

@@ -1,20 +1,8 @@
 import type { Argv } from "yargs";
 export declare const builder: (yargs: Argv) => Argv<{
-    o: string | undefined;
+    estimate: boolean;
 } & {
-    b: string | undefined;
-} & {
-    l: string | undefined;
-} & {
-    f: boolean;
-} & {
-    g: boolean;
-} & {
-    backup: boolean;
-} & {
-    p: string | undefined;
-} & {
-    file: string | undefined;
+    json: boolean;
 } & {
     a: string | undefined;
 }>;

package/lib/cli/commands/audio/builder.js

@@ -1,5 +1,5 @@
-import { commonOptions } from "../../common.js";
-export const builder = (yargs) => commonOptions(yargs).option("a", {
+import { commonOptions, estimateOptions } from "../../common.js";
+export const builder = (yargs) => estimateOptions(commonOptions(yargs)).option("a", {
     alias: "audiodir",
     describe: "Audio output directory",
     type: "string",

package/lib/cli/commands/audio/handler.d.ts

@@ -1,4 +1,6 @@
 import { CliArgs } from "../../../types/cli_types.js";
 export declare const handler: (argv: CliArgs<{
+    estimate?: boolean;
+    json?: boolean;
     a?: string;
 }>) => Promise<void>;

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

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

package/lib/cli/commands/image/builder.d.ts

@@ -1,20 +1,8 @@
 import type { Argv } from "yargs";
 export declare const builder: (yargs: Argv) => Argv<{
-    o: string | undefined;
+    estimate: boolean;
 } & {
-    b: string | undefined;
-} & {
-    l: string | undefined;
-} & {
-    f: boolean;
-} & {
-    g: boolean;
-} & {
-    backup: boolean;
-} & {
-    p: string | undefined;
-} & {
-    file: string | undefined;
+    json: boolean;
 } & {
     i: string | undefined;
 }>;

package/lib/cli/commands/image/builder.js

@@ -1,5 +1,5 @@
-import { commonOptions } from "../../common.js";
-export const builder = (yargs) => commonOptions(yargs).option("i", {
+import { commonOptions, estimateOptions } from "../../common.js";
+export const builder = (yargs) => estimateOptions(commonOptions(yargs)).option("i", {
     alias: "imagedir",
     describe: "Image output directory",
     type: "string",

package/lib/cli/commands/image/handler.d.ts

@@ -1,4 +1,6 @@
 import { CliArgs } from "../../../types/cli_types.js";
 export declare const handler: (argv: CliArgs<{
+    estimate?: boolean;
+    json?: boolean;
     i?: string;
 }>) => Promise<void>;

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

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

package/lib/cli/commands/movie/builder.d.ts

@@ -1,20 +1,8 @@
 import type { Argv } from "yargs";
 export declare const builder: (yargs: Argv) => Argv<{
-    o: string | undefined;
+    estimate: boolean;
 } & {
-    b: string | undefined;
-} & {
-    l: string | undefined;
-} & {
-    f: boolean;
-} & {
-    g: boolean;
-} & {
-    backup: boolean;
-} & {
-    p: string | undefined;
-} & {
-    file: string | undefined;
+    json: boolean;
 } & {
     a: string | undefined;
 } & {

package/lib/cli/commands/movie/builder.js

@@ -1,6 +1,6 @@
-import { commonOptions } from "../../common.js";
+import { commonOptions, estimateOptions } from "../../common.js";
 import { languages } from "../../../types/const.js";
-export const builder = (yargs) => commonOptions(yargs)
+export const builder = (yargs) => estimateOptions(commonOptions(yargs))
     .option("a", {
     alias: "audiodir",
     describe: "Audio output directory",

package/lib/cli/commands/movie/handler.d.ts

@@ -1,5 +1,7 @@
 import { CliArgs } from "../../../types/cli_types.js";
 export declare const handler: (argv: CliArgs<{
+    estimate?: boolean;
+    json?: boolean;
     a?: string;
     i?: string;
     c?: string;

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

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

package/lib/cli/commands/pdf/builder.d.ts

@@ -1,20 +1,8 @@
 import type { Argv } from "yargs";
 export declare const builder: (yargs: Argv) => Argv<{
-    o: string | undefined;
+    estimate: boolean;
 } & {
-    b: string | undefined;
-} & {
-    l: string | undefined;
-} & {
-    f: boolean;
-} & {
-    g: boolean;
-} & {
-    backup: boolean;
-} & {
-    p: string | undefined;
-} & {
-    file: string | undefined;
+    json: boolean;
 } & {
     i: string | undefined;
 } & {

package/lib/cli/commands/pdf/builder.js

@@ -1,6 +1,6 @@
-import { commonOptions } from "../../common.js";
+import { commonOptions, estimateOptions } from "../../common.js";
 import { pdf_modes, pdf_sizes } from "../../../types/const.js";
-export const builder = (yargs) => commonOptions(yargs)
+export const builder = (yargs) => estimateOptions(commonOptions(yargs))
     .option("i", {
     alias: "imagedir",
     describe: "Image output directory",

package/lib/cli/commands/pdf/handler.d.ts

@@ -1,5 +1,7 @@
 import { CliArgs } from "../../../types/cli_types.js";
 export declare const handler: (argv: CliArgs<{
+    estimate?: boolean;
+    json?: boolean;
     i?: string;
     pdf_mode: string;
     pdf_size: string;

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

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

package/lib/cli/commands/translate/builder.d.ts

@@ -1,20 +1,8 @@
 import type { Argv } from "yargs";
-export declare const builder: (yargs: Argv) => Argv<import("yargs").Omit<{
-    o: string | undefined;
+export declare const builder: (yargs: Argv) => Argv<{
+    estimate: boolean;
 } & {
-    b: string | undefined;
+    json: boolean;
 } & {
-    l: string | undefined;
-} & {
-    f: boolean;
-} & {
-    g: boolean;
-} & {
-    backup: boolean;
-} & {
-    p: string | undefined;
-} & {
-    file: string | undefined;
-}, "file"> & {
     file: string | undefined;
 }>;

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

@@ -1,5 +1,5 @@
-import { commonOptions } from "../../common.js";
-export const builder = (yargs) => commonOptions(yargs).positional("file", {
+import { commonOptions, estimateOptions } from "../../common.js";
+export const builder = (yargs) => estimateOptions(commonOptions(yargs)).positional("file", {
     describe: "Mulmo Script File",
     type: "string",
 });

package/lib/cli/commands/translate/handler.d.ts

@@ -1,4 +1,6 @@
 import { CliArgs } from "../../../types/cli_types.js";
 export declare const handler: (argv: CliArgs<{
+    estimate?: boolean;
+    json?: boolean;
     i?: string;
 }>) => Promise<void>;

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_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[];

package/lib/utils/estimate_usage.js

@@ -0,0 +1,332 @@
+// Pre-run usage estimator: walks a MulmoScript and returns, per beat and per
+// process, the API usage a full generation run would consume. Pure and
+// browser-compatible (js-tiktoken is pure JS). No cache awareness: estimates
+// assume every asset is generated fresh.
+import { Tiktoken } from "js-tiktoken/lite";
+import o200k_base from "js-tiktoken/ranks/o200k_base";
+import { provider2TTSAgent, provider2MovieAgent, gptImageOutputTokens, getModelDuration, getModelPricing, defaultProviders, } from "../types/provider2agent.js";
+import { text2SpeechProviderSchema, text2MovieProviderSchema } from "../types/schema.js";
+import { MulmoPresentationStyleMethods } from "../methods/mulmo_presentation_style.js";
+import { MulmoBeatMethods } from "../methods/mulmo_beat.js";
+import { imagePrompt, htmlImageSystemPrompt, translateSystemPrompt, translatePrompts } from "./prompt.js";
+const MILLION = 1_000_000;
+const LATIN_CHARS_PER_TOKEN = 4;
+const CJK_CHARS_PER_SEC = 6;
+const LATIN_CHARS_PER_SEC = 15;
+// Measured ≈50 audio output tokens per second (docs/api.md § Known gaps, probed in PR #1439).
+const OPENAI_TTS_AUDIO_TOKENS_PER_SEC = 50;
+// Documented: Gemini TTS audio tokens = 25 per second of audio.
+const GEMINI_TTS_AUDIO_TOKENS_PER_SEC = 25;
+// gpt-5 completion_tokens include reasoning tokens; a simple slide measured ≈4.4k (probe 2026-07-03).
+const HTML_OUTPUT_TOKENS_GUESS = 4000;
+const TRANSLATE_OUTPUT_FACTOR = 1.2;
+// The translate action doesn't set a model, so @graphai/openai_agent's default applies.
+const TRANSLATE_DEFAULT_MODEL = "gpt-4o";
+const DEFAULT_MOVIE_DURATION_SEC = 8;
+const GPT_IMAGE_FIXED_TOKEN_MODELS = ["gpt-image-1", "gpt-image-1-mini"];
+// Fixed request framing the API adds on top of the tokenized prompt text. Both values
+// reproduced the billed prompt_tokens exactly, per record, in the 2026-07-03 probes
+// (scripts/probe/probe_estimate_vs_actual.ts): chat completions (system + user) +10,
+// image generation +6.
+const OPENAI_CHAT_INPUT_OVERHEAD_TOKENS = 10;
+const GPT_IMAGE_INPUT_OVERHEAD_TOKENS = 6;
+// What each CLI action actually consumes. translate is part of every generation scope
+// because the CLI runs it implicitly when the target/caption language differs from the
+// script language; the estimator emits zero translate records otherwise.
+const VISUAL_PROCESSES = ["image", "htmlImage", "movie", "soundEffect", "lipSync", "imageReference", "movieReference"];
+export const actionEstimateProcesses = {
+    audio: ["tts", "translate"],
+    images: [...VISUAL_PROCESSES, "translate"],
+    pdf: [...VISUAL_PROCESSES, "translate"],
+    movie: ["tts", ...VISUAL_PROCESSES, "translate"],
+    translate: ["translate"],
+};
+const isDefined = (value) => value !== undefined;
+const isKeyOf = (obj, key) => key in obj;
+let openAITokenizer;
+const countOpenAITokens = (text) => {
+    // Lazy: building the o200k_base BPE table is expensive and most importers never estimate.
+    openAITokenizer = openAITokenizer ?? new Tiktoken(o200k_base);
+    return openAITokenizer.encode(text).length;
+};
+const cjkPattern = /[⺀-鿿가-힯豈-﫿ｦ-ﾟ]/g;
+const countCjkChars = (text) => (text.match(cjkPattern) ?? []).length;
+const countHeuristicTokens = (text) => {
+    const cjkChars = countCjkChars(text);
+    return cjkChars + Math.ceil((text.length - cjkChars) / LATIN_CHARS_PER_TOKEN);
+};
+const estimateSpeechSec = (text) => {
+    const cjkChars = countCjkChars(text);
+    const latinChars = text.length - cjkChars;
+    return Math.max(1, Math.round(cjkChars / CJK_CHARS_PER_SEC + latinChars / LATIN_CHARS_PER_SEC));
+};
+const exact = (value) => ({ value, precision: "exact" });
+const estimated = (value) => ({ value, precision: "estimated" });
+const metric = (value, isExact) => ({ value, precision: isExact ? "exact" : "estimated" });
+const computeCostUSD = (pricing, record) => {
+    const tokenValue = (m, rate) => (m && rate ? (m.value * rate) / MILLION : 0);
+    const total = tokenValue(record.inputTokens, pricing.inputPerMTokensUSD) +
+        tokenValue(record.outputTokens, pricing.outputPerMTokensUSD) +
+        tokenValue(record.inputChars, pricing.perMCharsUSD) +
+        (record.predictSec && pricing.perSecUSD ? record.predictSec.value * pricing.perSecUSD : 0) +
+        (record.imageCount && pricing.perImageUSD ? record.imageCount.value * pricing.perImageUSD : 0);
+    return total > 0 ? total : undefined;
+};
+const attachCost = (record, pricingKey) => {
+    const pricing = getModelPricing(record.provider, pricingKey ?? record.model);
+    if (!pricing) {
+        return record;
+    }
+    const costUSD = computeCostUSD(pricing, record);
+    return costUSD !== undefined ? { ...record, costUSD, pricingAsOf: pricing.asOf } : record;
+};
+const buildOpenAITts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
+    const model = speaker.model ?? provider2TTSAgent.openai.defaultModel;
+    // gpt-* TTS models are token-billed; legacy tts-1 models are character-billed.
+    const tokenMetrics = model.startsWith("gpt-")
+        ? {
+            inputTokens: metric(countOpenAITokens(text), textIsFinal),
+            outputTokens: estimated(estimateSpeechSec(text) * OPENAI_TTS_AUDIO_TOKENS_PER_SEC),
+        }
+        : {};
+    return { process: "tts", beatIndex, lang, provider: "openai", model, inputChars: metric(text.length, textIsFinal), ...tokenMetrics };
+};
+const buildGeminiTts = ({ speaker, speechOptions, text, beatIndex, lang }) => {
+    // The gemini TTS agent wraps the transcript in a "Director's Notes" prompt when an instruction is set.
+    const prompt = speechOptions?.instruction ? `### DIRECTOR'S NOTES\n${speechOptions.instruction}\n\n#### TRANSCRIPT\n${text}` : text;
+    return {
+        process: "tts",
+        beatIndex,
+        lang,
+        provider: "gemini",
+        model: speaker.model ?? provider2TTSAgent.gemini.defaultModel,
+        inputTokens: estimated(countHeuristicTokens(prompt)),
+        outputTokens: estimated(estimateSpeechSec(text) * GEMINI_TTS_AUDIO_TOKENS_PER_SEC),
+    };
+};
+const buildGoogleTts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
+    // Mirrors the runtime usage record: model falls back to the voice name; billing is per character.
+    const model = speaker.model ?? speaker.voiceId;
+    return { process: "tts", beatIndex, lang, provider: "google", model, inputChars: metric(text.length, textIsFinal) };
+};
+const buildElevenLabsTts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
+    const model = speaker.model ?? provider2TTSAgent.elevenlabs.defaultModel;
+    return { process: "tts", beatIndex, lang, provider: "elevenlabs", model, inputChars: metric(text.length, textIsFinal) };
+};
+const buildKotodamaTts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
+    // Mirrors the runtime usage record: the kotodama agent reports the speaker id as the model.
+    return { process: "tts", beatIndex, lang, provider: "kotodama", model: speaker.voiceId, inputChars: metric(text.length, textIsFinal) };
+};
+const ttsRecordBuilders = {
+    openai: buildOpenAITts,
+    gemini: buildGeminiTts,
+    google: buildGoogleTts,
+    elevenlabs: buildElevenLabsTts,
+    kotodama: buildKotodamaTts,
+};
+const googleTtsPricingKey = (voiceId) => {
+    const tiers = {
+        neural2: "tts-neural2",
+        wavenet: "tts-wavenet",
+        studio: "tts-studio",
+        chirp: "tts-chirp3-hd",
+        standard: "tts-standard",
+    };
+    const lower = voiceId.toLowerCase();
+    const tier = Object.keys(tiers).find((key) => lower.includes(key));
+    return tier ? tiers[tier] : undefined;
+};
+const estimateBeatTts = (script, style, beat, beatIndex, lang) => {
+    if (beat.audio || !beat.text || script.audioParams?.suppressSpeech || !style.speechParams?.speakers) {
+        return undefined;
+    }
+    const speaker = MulmoPresentationStyleMethods.getSpeakerData(style, beat, lang);
+    const provider = text2SpeechProviderSchema.parse(speaker.provider);
+    const builder = ttsRecordBuilders[provider];
+    if (!builder) {
+        return undefined; // mock
+    }
+    // For non-default languages the TTS input is a translation that doesn't exist yet.
+    const textIsFinal = lang === (script.lang ?? "en");
+    const speechOptions = { ...speaker.speechOptions, ...beat.speechOptions };
+    const record = builder({ speaker, speechOptions, text: beat.text, textIsFinal, beatIndex, lang });
+    return attachCost(record, provider === "google" ? googleTtsPricingKey(speaker.voiceId) : undefined);
+};
+// ---- Images / movies / sound effects / lip sync ----
+const gptImageSize = (canvasSize) => {
+    if (canvasSize.width > canvasSize.height) {
+        return "1536x1024";
+    }
+    return canvasSize.width < canvasSize.height ? "1024x1536" : "1024x1024";
+};
+const gptImageOutputMetric = (model, canvasSize, quality) => {
+    const table = gptImageOutputTokens[gptImageSize(canvasSize)];
+    const knownQuality = quality === "low" || quality === "medium" || quality === "high" ? quality : undefined;
+    // Unspecified quality means API "auto"; assume "high" as the conservative upper bound.
+    const tokens = table[knownQuality ?? "high"];
+    return metric(tokens, GPT_IMAGE_FIXED_TOKEN_MODELS.includes(model) && knownQuality !== undefined);
+};
+const buildImageRecord = ({ process, provider, model, prompt, canvasSize, quality, beatIndex, refKey }) => {
+    const base = { process, beatIndex, refKey, provider, model };
+    if (provider === "openai") {
+        return {
+            ...base,
+            inputTokens: exact(countOpenAITokens(prompt) + GPT_IMAGE_INPUT_OVERHEAD_TOKENS),
+            outputTokens: gptImageOutputMetric(model, canvasSize, quality),
+        };
+    }
+    if (provider === "google") {
+        return { ...base, inputTokens: estimated(countHeuristicTokens(prompt)), imageCount: exact(1) };
+    }
+    return { ...base, imageCount: exact(1) }; // replicate bills per image
+};
+const isMovieBeat = (beat) => Boolean(beat.moviePrompt || beat.image?.type === "movie");
+// Mirrors imagePreprocessAgent: no AI image when a plugin renders the beat or the beat is movie-only.
+const needsImageGeneration = (beat) => !beat.image && !(beat.moviePrompt && !beat.imagePrompt);
+const estimateImageGeneration = (style, beat, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getImageAgentInfo(style, beat);
+    const { provider, model, quality } = info.imageParams;
+    if (!provider || provider === "mock" || !model) {
+        return undefined;
+    }
+    const prompt = imagePrompt(beat, info.imageParams.style);
+    const canvasSize = MulmoPresentationStyleMethods.getCanvasSize(style);
+    return attachCost(buildImageRecord({ process: "image", provider, model, prompt, canvasSize, quality, beatIndex }));
+};
+const estimateHtmlImage = (style, beat, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getHtmlImageAgentInfo(style);
+    if (info.provider === "mock") {
+        return undefined;
+    }
+    const fullPrompt = htmlImageSystemPrompt(MulmoPresentationStyleMethods.getCanvasSize(style)) + "\n" + (MulmoBeatMethods.getHtmlPrompt(beat) ?? "");
+    const inputTokens = info.provider === "openai"
+        ? exact(countOpenAITokens(fullPrompt) + OPENAI_CHAT_INPUT_OVERHEAD_TOKENS)
+        : estimated(countHeuristicTokens(fullPrompt) + OPENAI_CHAT_INPUT_OVERHEAD_TOKENS);
+    return attachCost({
+        process: "htmlImage",
+        beatIndex,
+        provider: info.provider,
+        model: info.model,
+        inputTokens,
+        outputTokens: estimated(HTML_OUTPUT_TOKENS_GUESS),
+    });
+};
+const beatDurationMetric = (beat) => {
+    if (beat.duration !== undefined) {
+        return exact(beat.duration);
+    }
+    return estimated(beat.text ? estimateSpeechSec(beat.text) : DEFAULT_MOVIE_DURATION_SEC);
+};
+const snapMovieDuration = (provider, model, duration) => {
+    if (!isKeyOf(provider2MovieAgent[provider].modelParams, model)) {
+        return duration;
+    }
+    const snapped = getModelDuration(provider, model, duration.value);
+    return snapped !== undefined ? metric(snapped, duration.precision === "exact") : duration;
+};
+const estimateMovieGeneration = (style, beat, beatIndex, refKey) => {
+    const info = MulmoPresentationStyleMethods.getMovieAgentInfo(style, beat);
+    const provider = text2MovieProviderSchema.parse(info.movieParams?.provider ?? defaultProviders.text2movie);
+    if (!isKeyOf(provider2MovieAgent, provider) || provider === "mock") {
+        return undefined;
+    }
+    const model = info.movieParams?.model ?? provider2MovieAgent[provider].defaultModel;
+    const duration = beat ? beatDurationMetric(beat) : estimated(DEFAULT_MOVIE_DURATION_SEC);
+    const predictSec = snapMovieDuration(provider, model, duration);
+    return attachCost({ process: refKey === undefined ? "movie" : "movieReference", beatIndex, refKey, provider, model, predictSec });
+};
+const estimateSoundEffect = (style, beat, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getSoundEffectAgentInfo(style, beat);
+    const model = beat.soundEffectParams?.model ?? style.soundEffectParams?.model ?? info.defaultModel;
+    const provider = beat.soundEffectParams?.provider ?? style.soundEffectParams?.provider ?? defaultProviders.soundEffect;
+    // Replicate bills sound effects by GPU prediction time, which differs from clip duration.
+    const predictSec = estimated(beatDurationMetric(beat).value);
+    return attachCost({ process: "soundEffect", beatIndex, provider, model, predictSec });
+};
+const estimateLipSync = (style, beat, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getLipSyncAgentInfo(style, beat);
+    const model = beat.lipSyncParams?.model ?? style.lipSyncParams?.model ?? info.defaultModel;
+    const provider = beat.lipSyncParams?.provider ?? style.lipSyncParams?.provider ?? defaultProviders.lipSync;
+    return attachCost({ process: "lipSync", beatIndex, provider, model, predictSec: beatDurationMetric(beat) });
+};
+const estimateBeatVisuals = (style, beat, beatIndex) => {
+    if (beat.htmlPrompt) {
+        // The image preprocessor returns early for htmlPrompt beats; no other generation runs.
+        return [estimateHtmlImage(style, beat, beatIndex)].filter(isDefined);
+    }
+    return [
+        needsImageGeneration(beat) ? estimateImageGeneration(style, beat, beatIndex) : undefined,
+        beat.moviePrompt ? estimateMovieGeneration(style, beat, beatIndex) : undefined,
+        beat.soundEffectPrompt && isMovieBeat(beat) ? estimateSoundEffect(style, beat, beatIndex) : undefined,
+        beat.enableLipSync ? estimateLipSync(style, beat, beatIndex) : undefined,
+    ].filter(isDefined);
+};
+// ---- Reference images / movies (imageParams.images and beat.images) ----
+const estimateReferenceImage = (style, prompt, canvasSize, refKey, beatIndex) => {
+    const info = MulmoPresentationStyleMethods.getImageAgentInfo(style);
+    const { provider, model, quality } = info.imageParams;
+    if (!provider || provider === "mock" || !model) {
+        return undefined;
+    }
+    // Mirrors generateReferenceImage: the style is appended to the reference prompt.
+    const fullPrompt = `${prompt}\n${info.imageParams.style || ""}`;
+    const size = canvasSize ?? MulmoPresentationStyleMethods.getCanvasSize(style);
+    return attachCost(buildImageRecord({ process: "imageReference", provider, model, prompt: fullPrompt, canvasSize: size, quality, refKey, beatIndex }));
+};
+const estimateMediaReferences = (style, images, beatIndex) => {
+    return Object.entries(images ?? {})
+        .map(([refKey, media]) => {
+        if (media.type === "imagePrompt") {
+            return estimateReferenceImage(style, media.prompt, media.canvasSize, refKey, beatIndex);
+        }
+        if (media.type === "moviePrompt") {
+            return estimateMovieGeneration(style, undefined, beatIndex, refKey);
+        }
+        return undefined;
+    })
+        .filter(isDefined);
+};
+// ---- Translate ----
+const buildTranslateInput = (defaultLang, text, targetLang) => {
+    const substitutions = { ":lang": defaultLang, ":beat.text": text, ":targetLang": targetLang };
+    const prompt = translatePrompts.map((line) => substitutions[line] ?? line).join("\n");
+    return translateSystemPrompt + "\n" + prompt;
+};
+const buildTranslateRecord = (defaultLang, text, targetLang, beatIndex) => {
+    const input = buildTranslateInput(defaultLang, text, targetLang);
+    return attachCost({
+        process: "translate",
+        beatIndex,
+        lang: targetLang,
+        provider: "openai",
+        model: TRANSLATE_DEFAULT_MODEL,
+        inputTokens: exact(countOpenAITokens(input) + OPENAI_CHAT_INPUT_OVERHEAD_TOKENS),
+        outputTokens: estimated(Math.ceil(countOpenAITokens(text) * TRANSLATE_OUTPUT_FACTOR)),
+    });
+};
+const estimateTranslate = (script, targetLangs) => {
+    const defaultLang = script.lang ?? "en";
+    return targetLangs
+        .filter((targetLang) => targetLang !== defaultLang)
+        .flatMap((targetLang) => script.beats.map((beat, beatIndex) => (beat.text ? buildTranslateRecord(defaultLang, beat.text, targetLang, beatIndex) : undefined)).filter(isDefined));
+};
+// ---- Entry point ----
+const defaultTargetLangs = (style, langs, defaultLang) => {
+    // Mirrors the translate action's default: the requested languages plus the caption language.
+    const candidates = [...langs, style.captionParams?.lang];
+    return [...new Set(candidates.filter((lang) => !!lang && lang !== defaultLang))];
+};
+export const estimateUsage = (script, options) => {
+    const style = options?.presentationStyle ?? script;
+    const defaultLang = script.lang ?? "en";
+    const langs = options?.langs ?? [defaultLang];
+    const targetLangs = options?.targetLangs ?? defaultTargetLangs(style, langs, defaultLang);
+    const beatRecords = script.beats.flatMap((beat, beatIndex) => [
+        ...langs.map((lang) => estimateBeatTts(script, style, beat, beatIndex, lang)).filter(isDefined),
+        ...estimateBeatVisuals(style, beat, beatIndex),
+        ...estimateMediaReferences(style, beat.images, beatIndex),
+    ]);
+    const records = [...estimateMediaReferences(style, style.imageParams?.images), ...beatRecords, ...estimateTranslate(script, targetLangs)];
+    const processes = options?.processes;
+    return processes ? records.filter((record) => processes.includes(record.process)) : records;
+};

package/lib/utils/estimate_usage_format.d.ts

@@ -0,0 +1,2 @@
+import type { UsageEstimate } from "../types/usage.js";
+export declare const formatUsageEstimates: (records: UsageEstimate[]) => string;

package/lib/utils/estimate_usage_format.js

@@ -0,0 +1,64 @@
+const METRIC_KEYS = ["inputTokens", "outputTokens", "inputChars", "predictSec", "imageCount"];
+const emptyGroup = (process, model) => ({
+    process,
+    model,
+    metrics: Object.fromEntries(METRIC_KEYS.map((key) => [key, { value: 0, estimated: false, present: false }])),
+    costUSD: 0,
+    unpricedRecords: 0,
+    records: 0,
+});
+const addMetric = (sum, metric) => {
+    if (!metric) {
+        return;
+    }
+    sum.value += metric.value;
+    sum.estimated = sum.estimated || metric.precision === "estimated";
+    sum.present = true;
+};
+const buildGroups = (records) => {
+    const groups = new Map();
+    records.forEach((record) => {
+        const key = `${record.process}|${record.provider}:${record.model}`;
+        const group = groups.get(key) ?? emptyGroup(record.process, `${record.provider}:${record.model}`);
+        METRIC_KEYS.forEach((metricKey) => addMetric(group.metrics[metricKey], record[metricKey]));
+        group.costUSD += record.costUSD ?? 0;
+        group.unpricedRecords += record.costUSD === undefined ? 1 : 0;
+        group.records += 1;
+        groups.set(key, group);
+    });
+    return [...groups.values()];
+};
+const metricCell = (sum) => {
+    if (!sum.present) {
+        return "";
+    }
+    const marker = sum.estimated ? "~" : "";
+    return `${marker}${Math.round(sum.value * 100) / 100}`;
+};
+const groupRow = (group) => {
+    const cells = [group.process, group.model, ...METRIC_KEYS.map((key) => metricCell(group.metrics[key])), group.costUSD > 0 ? group.costUSD.toFixed(4) : ""];
+    return `| ${cells.join(" | ")} |`;
+};
+const totalLine = (groups, records) => {
+    const totalCost = groups.reduce((sum, group) => sum + group.costUSD, 0);
+    const unpriced = groups.reduce((sum, group) => sum + group.unpricedRecords, 0);
+    const asOf = [...new Set(records.map((record) => record.pricingAsOf).filter((date) => !!date))].sort()[0];
+    const parts = [`Total estimated cost: ≈ $${totalCost.toFixed(4)}`];
+    if (unpriced > 0) {
+        parts.push(`(${unpriced} record(s) without pricing data)`);
+    }
+    if (asOf) {
+        parts.push(`(prices as of ${asOf})`);
+    }
+    return parts.join(" ");
+};
+export const formatUsageEstimates = (records) => {
+    if (records.length === 0) {
+        return "No billable API usage estimated.";
+    }
+    const groups = buildGroups(records);
+    const header = "| process | provider:model | input tokens | output tokens | input chars | predict sec | images | cost (USD) |";
+    const separator = "|---|---|---|---|---|---|---|---|";
+    const note = "~ marks heuristic estimates; unmarked values are exact for the given script.";
+    return [header, separator, ...groups.map(groupRow), "", totalLine(groups, records), note].join("\n");
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.6.22",
+  "version": "2.7.0",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",
@@ -25,8 +25,8 @@
   },
   "resolutions": {
     "minimatch": "^10.2.5",
-    "tar": "7.5.16",
-    "yauzl": "^3.3.1"
+    "tar": "7.5.19",
+    "yauzl": "^3.4.0"
   },
   "bin": {
     "mulmo": "lib/cli/bin.js",
@@ -89,9 +89,9 @@
   "homepage": "https://github.com/receptron/mulmocast-cli#readme",
   "dependencies": {
     "@google-cloud/text-to-speech": "^6.4.1",
-    "@google/genai": "^2.7.0",
+    "@google/genai": "^2.10.0",
     "@graphai/anthropic_agent": "^2.0.12",
-    "@graphai/browserless_agent": "^2.0.2",
+    "@graphai/browserless_agent": "^2.0.3",
     "@graphai/gemini_agent": "^2.0.5",
     "@graphai/groq_agent": "^2.0.2",
     "@graphai/input_agents": "^1.0.2",
@@ -99,22 +99,23 @@
     "@graphai/stream_agent_filter": "^2.0.3",
     "@graphai/vanilla": "^2.0.12",
     "@graphai/vanilla_node_agents": "^2.0.4",
-    "@inquirer/input": "^5.0.13",
-    "@inquirer/select": "^5.1.5",
+    "@inquirer/input": "^5.1.2",
+    "@inquirer/select": "^5.2.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@modernized/fluent-ffmpeg": "^1.0.1",
     "@mozilla/readability": "^0.6.0",
     "@mulmocast/deck": "^1.1.0",
-    "@tavily/core": "^0.7.3",
+    "@tavily/core": "^0.7.6",
     "archiver": "^7.0.1",
     "clipboardy": "^5.3.1",
     "dotenv": "^17.4.2",
     "graphai": "^2.0.18",
+    "js-tiktoken": "^1.0.21",
     "jsdom": "^29.1.1",
     "marked": "^18.0.5",
-    "mulmocast-vision": "^1.0.10",
-    "ora": "^9.4.0",
-    "puppeteer": "^25.1.0",
+    "mulmocast-vision": "^1.0.11",
+    "ora": "^9.4.1",
+    "puppeteer": "^25.3.0",
     "replicate": "^1.4.0",
     "yaml": "^2.9.0",
     "yargs": "^18.0.0",
@@ -127,16 +128,16 @@
     "@types/jsdom": "^28.0.3",
     "@types/yargs": "^17.0.35",
     "cross-env": "^10.1.0",
-    "eslint": "^10.5.0",
+    "eslint": "^10.6.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.6",
-    "eslint-plugin-sonarjs": "^4.0.3",
-    "globals": "^17.6.0",
-    "prettier": "^3.8.4",
+    "eslint-plugin-sonarjs": "^4.1.0",
+    "globals": "^17.7.0",
+    "prettier": "^3.9.4",
     "tsx": "^4.22.4",
     "typescript": "6.0.3",
-    "typescript-eslint": "^8.61.1"
+    "typescript-eslint": "^8.62.1"
   },
   "engines": {
     "node": ">=22.0.0"