mulmocast 2.2.6 → 2.3.0

package/README.md

@@ -207,6 +207,51 @@ MulmoScript configuration (same as OpenAI):
 
 For detailed setup and region availability, see [Azure OpenAI Usage Guide](./docs/azure_openai_usage.md).
 
+### mulmo.config.json
+
+Create a `mulmo.config.json` file to set project-wide defaults. The CLI searches for it in **CWD** first, then **home directory (`~/`)**.
+
+```json
+{
+  "speechParams": {
+    "provider": "elevenlabs"
+  },
+  "imageParams": {
+    "provider": "google"
+  },
+  "audioParams": {
+    "bgm": { "kind": "path", "path": "assets/bgm.mp3" },
+    "bgmVolume": 0.15
+  }
+}
+```
+
+Top-level keys are applied as **defaults** (script values take precedence). Use the `override` key to **force** values over scripts — useful for enterprise branding or TTS provider enforcement:
+
+```json
+{
+  "speechParams": {
+    "provider": "elevenlabs"
+  },
+  "override": {
+    "speechParams": {
+      "provider": "elevenlabs",
+      "model": "eleven_multilingual_v2",
+      "speakers": {
+        "Presenter": { "provider": "elevenlabs", "voiceId": "Rachel" }
+      }
+    }
+  }
+}
+```
+
+Priority chain: `config (defaults)` < `template/style` < `script` < `config.override` < `presentationStyle (-p)`
+
+Verify the merged result with:
+```bash
+mulmo tool info merged --script <script.json>
+```
+
 ## Workflow
 
 1. Create a MulmoScript JSON file with `mulmo tool scripting`

package/lib/cli/commands/tool/info/builder.d.ts

@@ -3,4 +3,6 @@ export declare const builder: (yargs: Argv) => Argv<{
     category: string | undefined;
 } & {
     format: string;
+} & {
+    script: string | undefined;
 }>;

package/lib/cli/commands/tool/info/builder.js

@@ -2,7 +2,7 @@ export const builder = (yargs) => yargs
     .positional("category", {
     describe: "Category to show info for",
     type: "string",
-    choices: ["styles", "bgm", "templates", "voices", "images", "movies", "llm", "themes"],
+    choices: ["styles", "bgm", "templates", "voices", "images", "movies", "llm", "themes", "config", "merged"],
 })
     .option("format", {
     alias: "F",
@@ -10,4 +10,9 @@ export const builder = (yargs) => yargs
     type: "string",
     choices: ["text", "json", "yaml"],
     default: "text",
+})
+    .option("script", {
+    alias: "S",
+    describe: "Script file path (required for 'merged' category)",
+    type: "string",
 });

package/lib/cli/commands/tool/info/handler.d.ts

@@ -1,6 +1,7 @@
 interface InfoCliArgs {
     category?: string;
     format: string;
+    script?: string;
 }
 export declare const handler: (argv: InfoCliArgs) => void;
 export {};

package/lib/cli/commands/tool/info/handler.js

@@ -1,9 +1,12 @@
 /* eslint-disable no-console */
+import path from "path";
 import { getMarkdownStyleNames, getMarkdownCategories, getMarkdownStylesByCategory } from "../../../../data/markdownStyles.js";
 import { bgmAssets } from "../../../../data/bgmAssets.js";
 import { templateDataSet } from "../../../../data/templateDataSet.js";
 import { slideThemes } from "../../../../data/slideThemes.js";
 import { provider2TTSAgent, provider2ImageAgent, provider2MovieAgent, provider2LLMAgent } from "../../../../types/provider2agent.js";
+import { findConfigFile, loadMulmoConfig, mergeConfigWithScript } from "../../../../utils/mulmo_config.js";
+import { readMulmoScriptFile } from "../../../../utils/file.js";
 import YAML from "yaml";
 const formatOutput = (data, format) => {
     if (format === "json") {
@@ -170,6 +173,78 @@ const printThemesText = () => {
     }
     console.log("");
 };
+const getConfigInfo = () => {
+    const baseDirPath = process.cwd();
+    const configPath = findConfigFile(baseDirPath);
+    if (!configPath) {
+        return { configFile: null, config: null };
+    }
+    const config = loadMulmoConfig(baseDirPath);
+    return { configFile: configPath, config };
+};
+const printConfigText = () => {
+    const baseDirPath = process.cwd();
+    const configPath = findConfigFile(baseDirPath);
+    console.log("\n📄 mulmo.config.json\n");
+    if (!configPath) {
+        console.log("  No mulmo.config.json found.");
+        console.log("  Searched: CWD → ~\n");
+        return;
+    }
+    console.log(`  Active config: ${configPath}\n`);
+    const config = loadMulmoConfig(baseDirPath);
+    if (config) {
+        console.log(JSON.stringify(config, null, 2));
+    }
+    console.log("");
+};
+const readScriptFile = (scriptPath) => {
+    const result = readMulmoScriptFile(scriptPath, `Error: File not found: ${scriptPath}`);
+    if (!result) {
+        console.error(`Error: Could not read script file: ${scriptPath}`);
+        process.exit(1);
+    }
+    return result.mulmoData;
+};
+const getMergedInfo = (scriptPath) => {
+    if (!scriptPath) {
+        console.error("Error: --script <file> is required for 'merged' category");
+        process.exit(1);
+    }
+    const baseDirPath = process.cwd();
+    const configResult = loadMulmoConfig(baseDirPath);
+    const script = readScriptFile(scriptPath);
+    if (!configResult) {
+        return { configFile: null, merged: script };
+    }
+    const configPath = findConfigFile(baseDirPath);
+    const merged = mergeConfigWithScript(configResult, script);
+    return { configFile: configPath, defaults: configResult.defaults, override: configResult.override, merged };
+};
+const printMergedText = (scriptPath) => {
+    if (!scriptPath) {
+        console.error("Error: --script <file> is required for 'merged' category");
+        console.error("Usage: mulmo tool info merged --script <script.json>");
+        process.exit(1);
+    }
+    const baseDirPath = process.cwd();
+    const configResult = loadMulmoConfig(baseDirPath);
+    const script = readScriptFile(scriptPath);
+    console.log("\n📋 Merged Script Result\n");
+    console.log(`  Script: ${path.resolve(scriptPath)}`);
+    if (!configResult) {
+        console.log("  Config: (none)\n");
+        console.log(JSON.stringify(script, null, 2));
+        console.log("");
+        return;
+    }
+    const configPath = findConfigFile(baseDirPath);
+    console.log(`  Config: ${configPath}`);
+    console.log(`  Override: ${configResult.override ? "yes" : "no"}\n`);
+    const merged = mergeConfigWithScript(configResult, script);
+    console.log(JSON.stringify(merged, null, 2));
+    console.log("");
+};
 const printAllCategories = () => {
     console.log("\n📚 Available Info Categories\n");
     console.log("  Usage: mulmo tool info <category> [--format json|yaml]\n");
@@ -181,14 +256,16 @@ const printAllCategories = () => {
     console.log("    images     - Image generation providers and models");
     console.log("    movies     - Movie generation providers and models");
     console.log("    llm        - LLM providers and models");
-    console.log("    themes     - Slide themes and color palettes\n");
+    console.log("    themes     - Slide themes and color palettes");
+    console.log("    config     - Active mulmo.config.json location and contents");
+    console.log("    merged     - Show script merged with mulmo.config.json (--script <file>)\n");
 };
-const validCategories = ["styles", "bgm", "templates", "voices", "images", "movies", "llm", "themes"];
+const validCategories = ["styles", "bgm", "templates", "voices", "images", "movies", "llm", "themes", "config", "merged"];
 const isValidCategory = (category) => {
     return validCategories.includes(category);
 };
 export const handler = (argv) => {
-    const { category, format = "text" } = argv;
+    const { category, format = "text", script: scriptPath } = argv;
     if (!category) {
         if (format === "text") {
             printAllCategories();
@@ -216,6 +293,8 @@ export const handler = (argv) => {
         movies: getMoviesInfo,
         llm: getLlmInfo,
         themes: getThemesInfo,
+        config: getConfigInfo,
+        merged: () => getMergedInfo(scriptPath),
     };
     const textPrinters = {
         styles: printStylesText,
@@ -226,6 +305,8 @@ export const handler = (argv) => {
         movies: printMoviesText,
         llm: printLlmText,
         themes: printThemesText,
+        config: printConfigText,
+        merged: () => printMergedText(scriptPath),
     };
     if (format === "text") {
         textPrinters[category]();

package/lib/cli/commands/tool/info/index.d.ts

@@ -1,4 +1,4 @@
 export declare const command = "info [category]";
-export declare const desc = "Show available options (styles, bgm, templates, voices, images, movies, llm, themes)";
+export declare const desc = "Show available options (styles, bgm, templates, voices, images, movies, llm, themes, config, merged)";
 export { builder } from "./builder.js";
 export { handler } from "./handler.js";

package/lib/cli/commands/tool/info/index.js

@@ -1,4 +1,4 @@
 export const command = "info [category]";
-export const desc = "Show available options (styles, bgm, templates, voices, images, movies, llm, themes)";
+export const desc = "Show available options (styles, bgm, templates, voices, images, movies, llm, themes, config, merged)";
 export { builder } from "./builder.js";
 export { handler } from "./handler.js";

package/lib/tools/complete_script.d.ts

@@ -1,6 +1,6 @@
 import { type ZodSafeParseResult } from "zod";
 import type { MulmoScript } from "../types/type.js";
-type PartialMulmoScript = Record<string, unknown>;
+export type PartialMulmoScript = Record<string, unknown>;
 /**
  * Add $mulmocast version if not present
  */
@@ -17,6 +17,7 @@ export type CompleteScriptResult = ZodSafeParseResult<MulmoScript>;
 type CompleteScriptOptions = {
     templateName?: string;
     styleName?: string;
+    baseDirPath?: string;
 };
 /**
  * Complete a partial MulmoScript with schema defaults, optional style or template

package/lib/tools/complete_script.js

@@ -4,6 +4,7 @@ import { mulmoScriptSchema } from "../types/schema.js";
 import { getScriptFromPromptTemplate } from "../utils/file.js";
 import { currentMulmoScriptVersion } from "../types/const.js";
 import { promptTemplates } from "../data/index.js";
+import { loadMulmoConfig } from "../utils/mulmo_config.js";
 /**
  * Add $mulmocast version if not present
  */
@@ -16,7 +17,7 @@ export const addMulmocastVersion = (data) => {
         $mulmocast: { version: currentMulmoScriptVersion },
     };
 };
-const deepMergeKeys = ["speechParams", "imageParams", "movieParams", "audioParams"];
+const deepMergeKeys = ["speechParams", "imageParams", "movieParams", "audioParams", "slideParams"];
 /**
  * Merge base with override (override takes precedence)
  */
@@ -82,11 +83,13 @@ export const getStyle = (style) => {
  * completeScript(data, { styleName: "./my-style.json" })
  */
 export const completeScript = (data, options = {}) => {
-    const { templateName, styleName } = options;
+    const { templateName, styleName, baseDirPath } = options;
     // template and style are mutually exclusive
     if (templateName && styleName) {
         throw new Error("Cannot specify both templateName and styleName. They are mutually exclusive.");
     }
+    // Load mulmo.config.json
+    const configResult = baseDirPath ? loadMulmoConfig(baseDirPath) : null;
     // Get base config from template or style
     const getBase = () => {
         if (templateName) {
@@ -97,9 +100,12 @@ export const completeScript = (data, options = {}) => {
         }
         return undefined;
     };
-    const base = getBase();
-    // Merge base with input data (input data has highest precedence)
-    const merged = base ? mergeScripts(base, data) : data;
+    const templateOrStyle = getBase();
+    // Merge chain: config.defaults < template/style < input data < config.override
+    const defaults = configResult?.defaults;
+    const withDefaults = defaults && templateOrStyle ? mergeScripts(defaults, templateOrStyle) : (templateOrStyle ?? defaults);
+    const withData = withDefaults ? mergeScripts(withDefaults, data) : data;
+    const merged = configResult?.override ? mergeScripts(withData, configResult.override) : withData;
     // Add version if not present
     const withVersion = addMulmocastVersion(merged);
     return mulmoScriptSchema.safeParse(withVersion);

package/lib/utils/context.js

@@ -3,6 +3,7 @@ import { readMulmoScriptFile, fetchMulmoScriptFile, isFile } from "./file.js";
 import { beatId, multiLingualObjectToArray } from "./utils.js";
 import { mulmoStudioSchema, mulmoCaptionParamsSchema, mulmoPresentationStyleSchema } from "../types/schema.js";
 import { MulmoPresentationStyleMethods, MulmoScriptMethods, MulmoStudioMultiLingualMethod } from "../methods/index.js";
+import { loadMulmoConfig, mergeConfigWithScript } from "./mulmo_config.js";
 export const silentMp3 = "https://github.com/receptron/mulmocast-cli/raw/refs/heads/main/assets/audio/silent300.mp3";
 const mulmoCredit = (speaker, isPortrait) => {
     return {
@@ -117,10 +118,13 @@ export const getPresentationStyle = (presentationStylePath) => {
 };
 export const initializeContextFromFiles = async (files, raiseError, force, withBackup, captionLang, targetLang, index) => {
     const { fileName, isHttpPath, fileOrUrl, mulmoFilePath, presentationStylePath, outputMultilingualFilePath } = files;
-    const mulmoScript = await fetchScript(isHttpPath, mulmoFilePath, fileOrUrl);
-    if (!mulmoScript) {
+    const rawScript = await fetchScript(isHttpPath, mulmoFilePath, fileOrUrl);
+    if (!rawScript) {
         return null;
     }
+    // Load and merge mulmo.config.json (defaults < script < override)
+    const config = loadMulmoConfig(files.baseDirPath);
+    const mulmoScript = config ? mergeConfigWithScript(config, rawScript) : rawScript;
     // The index param is used when you want to process only a specific beat in an app, etc. This is to avoid parser errors.
     if (!isNull(index) && mulmoScript.beats[index]) {
         mulmoScript.beats = [mulmoScript.beats[index]];

package/lib/utils/image_plugins/slide.js

@@ -1,6 +1,7 @@
 import nodePath from "node:path";
 import { pathToFileURL } from "node:url";
 import { generateSlideHTML } from "../../slide/index.js";
+import { slideThemes } from "../../data/slideThemes.js";
 import { renderHTMLToImage } from "../html_render.js";
 import { parrotingImagePath } from "./utils.js";
 import { pathToDataUrl } from "../../methods/mulmo_media_source.js";
@@ -95,10 +96,7 @@ const resolveTheme = (params) => {
         throw new Error("resolveTheme called on non-slide beat");
     }
     const defaultTheme = context.presentationStyle.slideParams?.theme;
-    const theme = beat.image.theme ?? defaultTheme;
-    if (!theme) {
-        throw new Error("Slide theme is required: set slideParams.theme or beat.image.theme");
-    }
+    const theme = beat.image.theme ?? defaultTheme ?? slideThemes.corporate;
     return theme;
 };
 const resolveSlide = (params, converter = pathToDataUrl) => {

package/lib/utils/mulmo_config.d.ts

@@ -0,0 +1,28 @@
+import { type PartialMulmoScript } from "../tools/complete_script.js";
+/**
+ * Search for mulmo.config.json in CWD → ~ order.
+ * Returns the first found path, or null if not found.
+ */
+export declare const findConfigFile: (baseDirPath: string) => string | null;
+/**
+ * Resolve all kind:"path" references in config relative to the config file directory.
+ */
+export declare const resolveConfigPaths: (config: PartialMulmoScript, configDirPath: string) => PartialMulmoScript;
+export type MulmoConfigResult = {
+    defaults: PartialMulmoScript;
+    override: PartialMulmoScript | null;
+};
+/**
+ * Load mulmo.config.json from baseDirPath or home directory.
+ * Resolves kind:"path" entries relative to the config file location.
+ * Returns { defaults, override } or null if no config file is found.
+ *
+ * - defaults: applied as low-priority base (script wins)
+ * - override: applied after script merge (wins over script)
+ */
+export declare const loadMulmoConfig: (baseDirPath: string) => MulmoConfigResult | null;
+/**
+ * Merge mulmo.config.json with a MulmoScript.
+ * defaults < script < override
+ */
+export declare const mergeConfigWithScript: (configResult: MulmoConfigResult, script: PartialMulmoScript) => PartialMulmoScript;

package/lib/utils/mulmo_config.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import os from "os";
+import { GraphAILogger } from "graphai";
+import { mergeScripts } from "../tools/complete_script.js";
+import { getFullPath } from "./file.js";
+const CONFIG_FILE_NAME = "mulmo.config.json";
+/**
+ * Search for mulmo.config.json in CWD → ~ order.
+ * Returns the first found path, or null if not found.
+ */
+export const findConfigFile = (baseDirPath) => {
+    const candidates = [path.resolve(baseDirPath, CONFIG_FILE_NAME), path.resolve(os.homedir(), CONFIG_FILE_NAME)];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+};
+/**
+ * Resolve kind:"path" entries in config to absolute paths relative to config file location.
+ */
+const resolveMediaSourcePath = (source, configDirPath) => {
+    if (source.kind === "path" && typeof source.path === "string") {
+        return { ...source, path: getFullPath(configDirPath, source.path) };
+    }
+    return source;
+};
+/**
+ * Immutably resolve a nested kind:"path" source at the given key path.
+ * e.g. ["audioParams", "bgm"] resolves config.audioParams.bgm
+ */
+const resolveNestedPath = (obj, keys, configDirPath) => {
+    const [head, ...tail] = keys;
+    const child = obj[head];
+    if (!child || typeof child !== "object") {
+        return obj;
+    }
+    const childObj = child;
+    const resolved = tail.length === 0 ? resolveMediaSourcePath(childObj, configDirPath) : resolveNestedPath(childObj, tail, configDirPath);
+    return resolved === child ? obj : { ...obj, [head]: resolved };
+};
+/** Key paths to kind:"path" sources that need resolution */
+const MEDIA_SOURCE_PATHS = [
+    ["audioParams", "bgm"],
+    ["slideParams", "branding", "logo", "source"],
+    ["slideParams", "branding", "backgroundImage", "source"],
+];
+/**
+ * Resolve all kind:"path" references in config relative to the config file directory.
+ */
+export const resolveConfigPaths = (config, configDirPath) => {
+    return MEDIA_SOURCE_PATHS.reduce((acc, keys) => resolveNestedPath(acc, keys, configDirPath), config);
+};
+/**
+ * Load mulmo.config.json from baseDirPath or home directory.
+ * Resolves kind:"path" entries relative to the config file location.
+ * Returns { defaults, override } or null if no config file is found.
+ *
+ * - defaults: applied as low-priority base (script wins)
+ * - override: applied after script merge (wins over script)
+ */
+export const loadMulmoConfig = (baseDirPath) => {
+    const configPath = findConfigFile(baseDirPath);
+    if (!configPath) {
+        return null;
+    }
+    try {
+        const content = readFileSync(configPath, "utf-8");
+        const raw = JSON.parse(content);
+        const configDirPath = path.dirname(configPath);
+        const { override: rawOverride, ...rest } = raw;
+        const defaults = resolveConfigPaths(rest, configDirPath);
+        const override = rawOverride ? resolveConfigPaths(rawOverride, configDirPath) : null;
+        return { defaults, override };
+    }
+    catch (error) {
+        GraphAILogger.error(`Error loading ${configPath}: ${error.message}`);
+        throw error;
+    }
+};
+/**
+ * Merge mulmo.config.json with a MulmoScript.
+ * defaults < script < override
+ */
+export const mergeConfigWithScript = (configResult, script) => {
+    const withDefaults = mergeScripts(configResult.defaults, script);
+    return configResult.override ? mergeScripts(withDefaults, configResult.override) : withDefaults;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.2.6",
+  "version": "2.3.0",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",
@@ -24,7 +24,7 @@
     }
   },
   "resolutions": {
-    "minimatch": "^10.2.2"
+    "minimatch": "^10.2.3"
   },
   "bin": {
     "mulmo": "lib/cli/bin.js",
@@ -87,7 +87,7 @@
   "homepage": "https://github.com/receptron/mulmocast-cli#readme",
   "dependencies": {
     "@google-cloud/text-to-speech": "^6.4.0",
-    "@google/genai": "^1.41.0",
+    "@google/genai": "^1.42.0",
     "@graphai/anthropic_agent": "^2.0.12",
     "@graphai/browserless_agent": "^2.0.2",
     "@graphai/gemini_agent": "^2.0.5",
@@ -97,13 +97,13 @@
     "@graphai/stream_agent_filter": "^2.0.3",
     "@graphai/vanilla": "^2.0.12",
     "@graphai/vanilla_node_agents": "^2.0.4",
-    "@inquirer/input": "^5.0.7",
-    "@inquirer/select": "^5.0.7",
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@inquirer/input": "^5.0.8",
+    "@inquirer/select": "^5.1.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@mozilla/readability": "^0.6.0",
     "@tavily/core": "^0.5.11",
     "archiver": "^7.0.1",
-    "clipboardy": "^5.3.0",
+    "clipboardy": "^5.3.1",
     "dotenv": "^17.3.1",
     "fluent-ffmpeg": "^2.1.3",
     "graphai": "^2.0.16",
@@ -122,10 +122,10 @@
     "@receptron/test_utils": "^2.0.3",
     "@types/archiver": "^7.0.0",
     "@types/fluent-ffmpeg": "^2.1.28",
-    "@types/jsdom": "^27.0.0",
+    "@types/jsdom": "^28.0.0",
     "@types/yargs": "^17.0.35",
     "cross-env": "^10.1.0",
-    "eslint": "^10.0.1",
+    "eslint": "^10.0.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-sonarjs": "^4.0.0",
@@ -133,7 +133,7 @@
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.0"
+    "typescript-eslint": "^8.56.1"
   },
   "engines": {
     "node": ">=22.0.0"

package/scripts/test/test_media.json

@@ -273,6 +273,23 @@
         "type": "beat",
         "id": "pingpongmov"
       }
+    },
+    {
+      "speaker": "Presenter",
+      "text": "This is a slide with table layout.",
+      "image": {
+        "type": "slide",
+        "slide": {
+          "layout": "table",
+          "title": "Feature Comparison",
+          "headers": ["Feature", "Free", "Pro"],
+          "rows": [
+            ["Audio", "OpenAI", "ElevenLabs"],
+            ["Images", "DALL-E", "Imagen 3"],
+            ["Video", "-", "Veo"]
+          ]
+        }
+      }
     }
   ]
 }