mulmocast 2.6.23 → 2.7.1

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/actions/bundle.js

@@ -7,8 +7,9 @@ import { ZipBuilder } from "../utils/zip.js";
 import { bundleTargetLang } from "../types/const.js";
 import { createSilentAudio } from "../utils/ffmpeg_utils.js";
 import { silentMp3 } from "../utils/context.js";
+import { safeFetch, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 const downloadFile = async (url, destPath) => {
-    const response = await fetch(url);
+    const response = await safeFetch(url, {}, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS);
     if (!response.ok) {
         throw new Error(`Failed to download file from ${url}: ${response.statusText}`);
     }

package/lib/actions/pdf.js

@@ -6,6 +6,7 @@ import { MulmoPresentationStyleMethods } from "../methods/index.js";
 import { localizedText, isHttp } from "../utils/utils.js";
 import { getOutputPdfFilePath, writingMessage, getHTMLFile, mulmoCreditPath } from "../utils/file.js";
 import { interpolate } from "../utils/html_render.js";
+import { safeFetch, FETCH_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 import { MulmoStudioContextMethods } from "../methods/mulmo_studio_context.js";
 const isCI = process.env.CI === "true";
 const getPdfSize = (pdfSize) => {
@@ -13,7 +14,9 @@ const getPdfSize = (pdfSize) => {
 };
 const loadImage = async (imagePath, index) => {
     try {
-        const imageData = isHttp(imagePath) ? Buffer.from(await (await fetch(imagePath)).arrayBuffer()) : fs.readFileSync(imagePath);
+        const imageData = isHttp(imagePath)
+            ? Buffer.from(await (await safeFetch(imagePath, {}, FETCH_DOWNLOAD_TIMEOUT_MS)).arrayBuffer())
+            : fs.readFileSync(imagePath);
         const ext = path.extname(imagePath).toLowerCase().replace(".", "");
         const mimeType = ext === "jpg" ? "jpeg" : ext;
         return `data:image/${mimeType};base64,${imageData.toString("base64")}`;

package/lib/agents/image_genai_agent.js

@@ -5,6 +5,9 @@ import { apiKeyMissingError, agentIncorrectAPIKeyError, agentGenerationError, ag
 import { getAspectRatio } from "../utils/utils.js";
 import { ASPECT_RATIOS, PRO_ASPECT_RATIOS } from "../types/const.js";
 import { GoogleGenAI, PersonGeneration } from "@google/genai";
+// Per-request timeout so a stalled GenAI image call rejects (and GraphAI retry
+// can recover) instead of hanging. Generous vs. normal generation time.
+const GENAI_REQUEST_TIMEOUT_MS = 120_000;
 const isDeprecatedGoogleImageModel = (model) => model in deprecatedGoogleImageModelHints;
 export const buildDeprecatedGoogleImageModelMessage = (model) => {
     if (!isDeprecatedGoogleImageModel(model))
@@ -86,7 +89,7 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
             if (vertexAIGlobalOnlyImageModels.has(model) && location !== "global") {
                 GraphAILogger.warn(`imageGenAIAgent: model "${model}" on Vertex AI is only available in location "global", but got "${location}". Set imageParams.vertexai_location to "global".`);
             }
-            return new GoogleGenAI({ vertexai: true, project: params.vertexai_project, location });
+            return new GoogleGenAI({ vertexai: true, project: params.vertexai_project, location, httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS } });
         })()
         : (() => {
             if (!apiKey) {
@@ -94,7 +97,7 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
                     cause: apiKeyMissingError("imageGenAIAgent", imageAction, "GEMINI_API_KEY"),
                 });
             }
-            return new GoogleGenAI({ apiKey });
+            return new GoogleGenAI({ apiKey, httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS } });
         })();
     if (model === "gemini-2.5-flash-image" || model === "gemini-3.1-flash-image-preview" || model === "gemini-3-pro-image-preview") {
         const contentParams = (() => {

package/lib/agents/image_openai_agent.js

@@ -3,6 +3,7 @@ import path from "path";
 import { GraphAILogger } from "graphai";
 import { toFile, AuthenticationError, RateLimitError, APIError } from "openai";
 import { createOpenAIClient } from "../utils/openai_client.js";
+import { safeFetch, FETCH_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 import { provider2ImageAgent, gptImages, deprecatedOpenAIImageModelHints } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentGenerationError, openAIAgentGenerationError, agentIncorrectAPIKeyError, agentAPIRateLimitError, agentInvalidResponseError, imageAction, imageFileTarget, unsupportedModelTarget, } from "../utils/error_cause.js";
 const isDeprecatedOpenAIImageModel = (model) => model in deprecatedOpenAIImageModelHints;
@@ -142,7 +143,7 @@ export const imageOpenaiAgent = async ({ namedInputs, params, config, }) => {
         return { buffer: Buffer.from(image_base64, "base64"), usage };
     }
     // URL response handling (legacy OpenAI image API response format)
-    const res = await fetch(url);
+    const res = await safeFetch(url, {}, FETCH_DOWNLOAD_TIMEOUT_MS);
     if (!res.ok) {
         throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`, {
             cause: agentGenerationError("imageOpenaiAgent", imageAction, imageFileTarget),

package/lib/agents/image_replicate_agent.js

@@ -5,6 +5,7 @@ import { getAspectRatio } from "./movie_replicate_agent.js";
 import { apiKeyMissingError, agentIncorrectAPIKeyError, agentGenerationError, agentInvalidResponseError, imageAction, imageFileTarget, hasCause, } from "../utils/error_cause.js";
 import { provider2ImageAgent } from "../types/provider2agent.js";
 import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
+import { safeFetch, FETCH_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 // Replicate image models return one of: FileOutput (object with url() method),
 // Array<FileOutput>, string URL, or { url: string }. Normalize to URL string/URL.
 const extractImageUrl = (output) => {
@@ -52,7 +53,7 @@ export const imageReplicateAgent = async ({ namedInputs, params, config, }) => {
                 cause: agentInvalidResponseError("imageReplicateAgent", imageAction, imageFileTarget),
             });
         }
-        const imageResponse = await fetch(imageUrl);
+        const imageResponse = await safeFetch(imageUrl, {}, FETCH_DOWNLOAD_TIMEOUT_MS);
         if (!imageResponse.ok) {
             throw new Error(`Error downloading image: ${imageResponse.status} - ${imageResponse.statusText}`, {
                 cause: agentGenerationError("imageReplicateAgent", imageAction, imageFileTarget),

package/lib/agents/lipsync_replicate_agent.js

@@ -4,6 +4,7 @@ import Replicate from "replicate";
 import { provider2LipSyncAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentGenerationError, agentFileNotExistError, imageAction, movieFileTarget, audioFileTarget, hasCause, } from "../utils/error_cause.js";
 import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
+import { safeFetch, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) => {
     const { movieFile, audioFile, imageFile } = namedInputs;
     const apiKey = config?.apiKey;
@@ -64,7 +65,7 @@ export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) =>
         const { output, predictSec } = await runReplicateWithMetrics(replicate, model_identifier, input);
         if (output && typeof output === "object" && "url" in output) {
             const videoUrl = output.url();
-            const videoResponse = await fetch(videoUrl);
+            const videoResponse = await safeFetch(videoUrl, {}, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS);
             if (!videoResponse.ok) {
                 throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
                     cause: agentGenerationError("lipSyncReplicateAgent", imageAction, movieFileTarget),

package/lib/agents/media_mock_agent.js

@@ -1,6 +1,7 @@
 import { GraphAILogger } from "graphai";
 import fs from "fs";
 import { silent60secPath, mulmoCreditPath } from "../utils/file.js";
+import { safeFetch, FETCH_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 export const mediaMockAgent = async ({ namedInputs }) => {
     if (namedInputs.media === "audio") {
         const buffer = fs.readFileSync(silent60secPath());
@@ -12,7 +13,7 @@ export const mediaMockAgent = async ({ namedInputs }) => {
     }
     if (namedInputs.media === "movie") {
         const url = "https://github.com/receptron/mulmocast-media/raw/refs/heads/main/test/pingpong.mov";
-        const res = await fetch(url);
+        const res = await safeFetch(url, {}, FETCH_DOWNLOAD_TIMEOUT_MS);
         if (!res.ok) {
             throw new Error(`Failed to fetch: ${res.status} ${res.statusText}`);
         }

package/lib/agents/movie_genai_agent.js

@@ -6,9 +6,19 @@ import { getAspectRatio } from "../utils/utils.js";
 import { ffmpegGetMediaDuration } from "../utils/ffmpeg_utils.js";
 import { ASPECT_RATIOS } from "../types/const.js";
 import { getModelDuration, provider2MovieAgent, AUDIO_MODE_NEVER, AUDIO_MODE_ALWAYS } from "../types/provider2agent.js";
+// Per-request timeout so a stalled GenAI video API call rejects instead of hanging.
+const GENAI_REQUEST_TIMEOUT_MS = 120_000;
+// Wall-clock cap on the long-running video operation poll loop (Veo runs minutes).
+const VIDEO_POLL_TIMEOUT_MS = 1_200_000;
 const pollUntilDone = async (ai, operation) => {
     const response = { operation };
+    const deadline = Date.now() + VIDEO_POLL_TIMEOUT_MS;
     while (!response.operation.done) {
+        if (Date.now() > deadline) {
+            throw new Error(`Video generation did not complete within ${VIDEO_POLL_TIMEOUT_MS}ms`, {
+                cause: agentGenerationError("movieGenAIAgent", imageAction, movieFileTarget),
+            });
+        }
         await sleep(5000);
         response.operation = await ai.operations.getVideosOperation(response);
     }
@@ -190,6 +200,7 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
                 vertexai: true,
                 project: params.vertexai_project,
                 location: params.vertexai_location ?? "us-central1",
+                httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS },
             })
             : (() => {
                 if (!apiKey) {
@@ -197,7 +208,7 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
                         cause: apiKeyMissingError("movieGenAIAgent", imageAction, "GEMINI_API_KEY"),
                     });
                 }
-                return new GoogleGenAI({ apiKey });
+                return new GoogleGenAI({ apiKey, httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS } });
             })();
         // Veo 3.1: Video extension mode for videos longer than 8s
         if (model === "veo-3.1-generate-preview" && requestedDuration > 8 && params.canvasSize) {
@@ -207,11 +218,14 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
         return generateStandardVideo(ai, model, prompt, aspectRatio, imagePath, lastFrameImagePath, referenceImages, duration, movieFile, isVertexAI);
     }
     catch (error) {
-        GraphAILogger.info("Failed to generate movie:", error.message);
         if (hasCause(error) && error.cause) {
             throw error;
         }
-        throw new Error("Failed to generate movie with Google GenAI", {
+        GraphAILogger.info("Failed to generate movie:", error.message);
+        // Preserve the underlying message (e.g. a timeout/abort deadline) instead of
+        // collapsing every failure to a static label. (Same template as #1452.)
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to generate movie with Google GenAI: ${detail}`, {
             cause: agentGenerationError("movieGenAIAgent", imageAction, movieFileTarget),
         });
     }

package/lib/agents/movie_replicate_agent.js

@@ -4,6 +4,7 @@ import Replicate from "replicate";
 import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, hasCause, imageAction, movieFileTarget, videoDurationTarget, unsupportedModelTarget, } from "../utils/error_cause.js";
 import { provider2MovieAgent, getModelDuration, AUDIO_MODE_OPTIONAL, AUDIO_MODE_NEVER, AUDIO_MODE_ALWAYS } from "../types/provider2agent.js";
 import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
+import { safeFetch, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 function replicate_get_videoUrl(output) {
     if (typeof output === "string")
         return output;
@@ -99,7 +100,7 @@ async function generateMovie(model, apiKey, prompt, imagePath, lastFrameImagePat
         // Some models return a FileOutput object with a url() method; others return a plain string URL.
         const videoUrl = replicate_get_videoUrl(output);
         if (videoUrl) {
-            const videoResponse = await fetch(videoUrl);
+            const videoResponse = await safeFetch(videoUrl, {}, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS);
             if (!videoResponse.ok) {
                 throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
                     cause: agentGenerationError("movieReplicateAgent", imageAction, movieFileTarget),

package/lib/agents/sound_effect_replicate_agent.js

@@ -4,6 +4,7 @@ import Replicate from "replicate";
 import { provider2SoundEffectAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentGenerationError, imageAction, movieFileTarget, hasCause } from "../utils/error_cause.js";
 import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
+import { safeFetch, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 export const soundEffectReplicateAgent = async ({ namedInputs, params, config }) => {
     const { prompt, movieFile } = namedInputs;
     const apiKey = config?.apiKey;
@@ -32,7 +33,7 @@ export const soundEffectReplicateAgent = async ({ namedInputs, params, config })
         const { output, predictSec } = await runReplicateWithMetrics(replicate, model_identifier, input);
         if (output && typeof output === "object" && "url" in output) {
             const videoUrl = output.url();
-            const videoResponse = await fetch(videoUrl);
+            const videoResponse = await safeFetch(videoUrl, {}, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS);
             if (!videoResponse.ok) {
                 throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
                     cause: agentGenerationError("soundEffectReplicateAgent", imageAction, movieFileTarget),
@@ -49,7 +50,10 @@ export const soundEffectReplicateAgent = async ({ namedInputs, params, config })
         if (hasCause(error) && error.cause) {
             throw error;
         }
-        throw new Error("Failed to generate sound effect with Replicate", {
+        // Preserve the underlying message (e.g. a safeFetch timeout) rather than
+        // collapsing every failure to a static label. (Same template as #1452.)
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to generate sound effect with Replicate: ${detail}`, {
             cause: agentGenerationError("soundEffectReplicateAgent", imageAction, movieFileTarget),
         });
     }

package/lib/agents/tts_elevenlabs_agent.js

@@ -1,6 +1,7 @@
 import { GraphAILogger } from "graphai";
 import { provider2TTSAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentVoiceLimitReachedError, agentIncorrectAPIKeyError, agentGenerationError, audioAction, audioFileTarget, } from "../utils/error_cause.js";
+import { safeFetch, FETCH_API_TIMEOUT_MS } from "../utils/fetch.js";
 export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
     const { text } = namedInputs;
     const { voice, model, stability, similarityBoost, speed, suppressError } = params;
@@ -27,7 +28,7 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
     GraphAILogger.log("ElevenLabs TTS options", requestBody);
     const response = await (async () => {
         try {
-            return await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voice}`, {
+            return await safeFetch(`https://api.elevenlabs.io/v1/text-to-speech/${voice}`, {
                 method: "POST",
                 headers: {
                     Accept: "audio/mpeg",
@@ -35,7 +36,7 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
                     "xi-api-key": apiKey,
                 },
                 body: JSON.stringify(requestBody),
-            });
+            }, FETCH_API_TIMEOUT_MS);
         }
         catch (e) {
             if (suppressError) {
@@ -64,7 +65,7 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
             });
         }
         const errorDetail = await response.json();
-        if (errorDetail.detail.status === "voice_limit_reached") {
+        if (errorDetail.detail?.status === "voice_limit_reached") {
             throw new Error("Failed to generate audio: 400 You have reached your maximum amount of custom voices with ElevenLabs", {
                 cause: agentVoiceLimitReachedError("ttsElevenlabsAgent", audioAction, audioFileTarget),
             });

package/lib/agents/tts_gemini_agent.js

@@ -3,6 +3,9 @@ import { GoogleGenAI } from "@google/genai";
 import { provider2TTSAgent } from "../types/provider2agent.js";
 import { agentIncorrectAPIKeyError, apiKeyMissingError, agentGenerationError, audioAction, audioFileTarget, getGenAIErrorReason, } from "../utils/error_cause.js";
 import { pcmToMp3 } from "../utils/ffmpeg_utils.js";
+// Per-request timeout so a stalled GenAI TTS call rejects (and GraphAI retry can
+// recover) instead of hanging. Generous vs. normal generation time.
+const GENAI_REQUEST_TIMEOUT_MS = 120_000;
 const getPrompt = (text, instructions) => {
     // https://ai.google.dev/gemini-api/docs/speech-generation?hl=ja#controllable
     if (instructions) {
@@ -21,7 +24,7 @@ export const ttsGeminiAgent = async ({ namedInputs, params, config, }) => {
     }
     const geminiResult = await (async () => {
         try {
-            const ai = new GoogleGenAI({ apiKey });
+            const ai = new GoogleGenAI({ apiKey, httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS } });
             const response = await ai.models.generateContent({
                 model: model ?? provider2TTSAgent.gemini.defaultModel,
                 contents: [{ parts: [{ text: getPrompt(text, instructions) }] }],

package/lib/agents/tts_kotodama_agent.js

@@ -1,6 +1,7 @@
 import { GraphAILogger } from "graphai";
 import { provider2TTSAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentIncorrectAPIKeyError, agentGenerationError, audioAction, audioFileTarget } from "../utils/error_cause.js";
+import { safeFetch, FETCH_API_TIMEOUT_MS } from "../utils/fetch.js";
 export const ttsKotodamaAgent = async ({ namedInputs, params, config, }) => {
     const { text } = namedInputs;
     const { voice, decoration, suppressError } = params;
@@ -18,14 +19,14 @@ export const ttsKotodamaAgent = async ({ namedInputs, params, config, }) => {
         audio_format: "mp3",
     };
     try {
-        const response = await fetch(url, {
+        const response = await safeFetch(url, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
                 "X-API-Key": apiKey,
             },
             body: JSON.stringify(body),
-        });
+        }, FETCH_API_TIMEOUT_MS);
         if (!response.ok) {
             if (response.status === 401) {
                 throw new Error("Failed to generate audio: 401 Incorrect API key provided with Kotodama", {
@@ -64,7 +65,10 @@ export const ttsKotodamaAgent = async ({ namedInputs, params, config, }) => {
         if (error && typeof error === "object" && "cause" in error) {
             throw error;
         }
-        throw new Error("TTS Kotodama Error", {
+        // Preserve the underlying message (e.g. a safeFetch timeout) rather than
+        // collapsing every failure to a static label. (Same template as #1452.)
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`TTS Kotodama Error: ${detail}`, {
             cause: agentGenerationError("ttsKotodamaAgent", 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>;