mulmocast 2.3.0 → 2.3.2

package/README.md

@@ -59,7 +59,7 @@ Here is the "Hello World" in MulmoScript.
 ```JSON
 {
   "$mulmocast": {
-    "version": "1.0"
+    "version": "1.1"
   },
   "beats": [
     { "text": "Hello World" }
@@ -247,6 +247,8 @@ Top-level keys are applied as **defaults** (script values take precedence). Use
 
 Priority chain: `config (defaults)` < `template/style` < `script` < `config.override` < `presentationStyle (-p)`
 
+> **Note**: `kind: "path"` entries in `mulmo.config.json` are resolved relative to the **script file directory**, not the config file location. This is consistent with all other path resolution in MulmoScript.
+
 Verify the merged result with:
 ```bash
 mulmo tool info merged --script <script.json>
@@ -499,8 +501,6 @@ https://github.com/receptron/mulmocast-cli/tree/main/scripts
 
 CLI Usage
 
-
-
 ```
 mulmo <command> [options]
 
@@ -511,6 +511,7 @@ Commands:
   mulmo movie <file>      Generate movie file
   mulmo pdf <file>        Generate PDF files
   mulmo markdown <file>   Generate markdown files
+  mulmo bundle <file>     Generate bundle files
   mulmo html <file>       Generate html files
   mulmo tool <command>    Generate Mulmo script and other tools
 
@@ -529,13 +530,19 @@ Positionals:
   file  Mulmo Script File                                    [string] [required]
 
 Options:
-      --version  Show version number                                   [boolean]
-  -v, --verbose  verbose log               [boolean] [required] [default: false]
-  -h, --help     Show help                                             [boolean]
-  -o, --outdir   output dir                                             [string]
-  -b, --basedir  base dir                                               [string]
-  -l, --lang     target language                  [string] [choices: "en", "ja"]
-  -f, --force    Force regenerate                     [boolean] [default: false]
+      --version            Show version number                         [boolean]
+  -v, --verbose            verbose log     [boolean] [required] [default: false]
+  -h, --help               Show help                                   [boolean]
+  -o, --outdir             output dir                                   [string]
+  -b, --basedir            base dir                                     [string]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
+  -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
+  -p, --presentationStyle  Presentation Style                           [string]
 ```
 
 ```
@@ -552,8 +559,13 @@ Options:
   -h, --help               Show help                                   [boolean]
   -o, --outdir             output dir                                   [string]
   -b, --basedir            base dir                                     [string]
-  -l, --lang               target language        [string] [choices: "en", "ja"]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
   -a, --audiodir           Audio output directory                       [string]
 ```
@@ -572,8 +584,13 @@ Options:
   -h, --help               Show help                                   [boolean]
   -o, --outdir             output dir                                   [string]
   -b, --basedir            base dir                                     [string]
-  -l, --lang               target language        [string] [choices: "en", "ja"]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
   -i, --imagedir           Image output directory                       [string]
 ```
@@ -592,12 +609,19 @@ Options:
   -h, --help               Show help                                   [boolean]
   -o, --outdir             output dir                                   [string]
   -b, --basedir            base dir                                     [string]
-  -l, --lang               target language        [string] [choices: "en", "ja"]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
   -a, --audiodir           Audio output directory                       [string]
   -i, --imagedir           Image output directory                       [string]
-  -c, --caption            Video captions         [string] [choices: "en", "ja"]
+  -c, --caption            Video captions
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
 ```
 
 ```
@@ -614,9 +638,13 @@ Options:
   -h, --help               Show help                                   [boolean]
   -o, --outdir             output dir                                   [string]
   -b, --basedir            base dir                                     [string]
-  -l, --lang               target language        [string] [choices: "en", "ja"]
+  -l, --lang               target language
+  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
+                                                               "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
-      --dryRun             Dry run                    [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
   -i, --imagedir           Image output directory                       [string]
       --pdf_mode           PDF mode
@@ -643,6 +671,9 @@ Options:
   [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                                "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
       --image_width        Image width (e.g., 400px, 50%, auto)         [string]
 ```
@@ -665,6 +696,9 @@ Options:
   [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                                "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
+      --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
       --image_width        Image width (e.g., 400px, 50%, auto)         [string]
 ```
@@ -687,6 +721,8 @@ Options:
   [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                                "pt", "ar", "hi"]
   -f, --force              Force regenerate           [boolean] [default: false]
+  -g, --grouped            Output all files under output/<basename>/ directory
+                                                      [boolean] [default: false]
       --backup             create backup media file   [boolean] [default: false]
   -p, --presentationStyle  Presentation Style                           [string]
 ```
@@ -697,11 +733,16 @@ mulmo tool <command>
 Generate Mulmo script and other tools
 
 Commands:
-  mulmo tool scripting       Generate mulmocast script
-  mulmo tool complete <file> Complete partial MulmoScript with defaults
-  mulmo tool prompt          Dump prompt from template
-  mulmo tool schema          Dump mulmocast schema
-  mulmo tool info [category] Show available options (styles, bgm, voices, etc.)
+  mulmo tool scripting               Generate mulmocast script
+  mulmo tool prompt                  Dump prompt from template
+  mulmo tool schema                  Dump mulmocast schema
+  mulmo tool story_to_script <file>  Generate Mulmo script from story
+  mulmo tool whisper <file>          Process file with whisper
+  mulmo tool complete <file>         Complete MulmoScript with schema defaults
+                                     and optional style
+  mulmo tool info [category]         Show available options (styles, bgm,
+                                     templates, voices, images, movies, llm,
+                                     themes, config, merged)
 
 Options:
       --version  Show version number                                   [boolean]
@@ -726,15 +767,15 @@ Options:
   -i, --interactive  Generate script in interactive mode with user prompts
                                                                        [boolean]
   -t, --template     Template name to use
-        [string] [choices: "akira_comic", "business", "children_book", "coding",
-           "comic_strips", "drslump_comic", "ghibli_comic", "ghibli_image_only",
-           "ghibli_shorts", "ghost_comic", "onepiece_comic", "podcast_standard",
-               "portrait_movie", "realistic_movie", "sensei_and_taro", "shorts",
-                                       "text_and_image", "text_only", "trailer"]
+              [string] [choices: "akira_comic", "ani", "business", "characters",
+      "children_book", "coding", "comic_strips", "documentary", "drslump_comic",
+   "ghibli_comic", "ghibli_comic_strips", "ghost_comic", "html", "image_prompt",
+                  "leda", "onepiece_comic", "portrait_movie", "realistic_movie",
+                 "sensei_and_taro", "shorts", "sifi_story", "trailer", "vision"]
   -c, --cache        cache dir                                          [string]
   -s, --script       script filename                [string] [default: "script"]
       --llm          llm
-                     [string] [choices: "openai", "anthropic", "gemini", "groq"]
+             [string] [choices: "openai", "anthropic", "gemini", "groq", "mock"]
       --llm_model    llm model                                          [string]
 ```
 
@@ -753,12 +794,15 @@ Options:
   -o, --outdir           output dir                                     [string]
   -b, --basedir          base dir                                       [string]
   -t, --template         Template name to use
-       [string] [choices: "business", "children_book", "coding", "comic_strips",
-                         "ghibli_strips", "podcast_standard", "sensei_and_taro"]
+              [string] [choices: "akira_comic", "ani", "business", "characters",
+      "children_book", "coding", "comic_strips", "documentary", "drslump_comic",
+   "ghibli_comic", "ghibli_comic_strips", "ghost_comic", "html", "image_prompt",
+                  "leda", "onepiece_comic", "portrait_movie", "realistic_movie",
+                 "sensei_and_taro", "shorts", "sifi_story", "trailer", "vision"]
   -s, --script           script filename            [string] [default: "script"]
       --beats_per_scene  beats per scene                   [number] [default: 3]
       --llm              llm
-                     [string] [choices: "openAI", "anthropic", "gemini", "groq"]
+             [string] [choices: "openai", "anthropic", "gemini", "groq", "mock"]
       --llm_model        llm model                                      [string]
       --mode             story to script generation mode
               [string] [choices: "step_wise", "one_step"] [default: "step_wise"]
@@ -774,8 +818,11 @@ Options:
   -v, --verbose   verbose log              [boolean] [required] [default: false]
   -h, --help      Show help                                            [boolean]
   -t, --template  Template name to use
-       [string] [choices: "business", "children_book", "coding", "comic_strips",
-                         "ghibli_strips", "podcast_standard", "sensei_and_taro"]
+              [string] [choices: "akira_comic", "ani", "business", "characters",
+      "children_book", "coding", "comic_strips", "documentary", "drslump_comic",
+   "ghibli_comic", "ghibli_comic_strips", "ghost_comic", "html", "image_prompt",
+                  "leda", "onepiece_comic", "portrait_movie", "realistic_movie",
+                 "sensei_and_taro", "shorts", "sifi_story", "trailer", "vision"]
 ```
 
 ```
@@ -792,18 +839,23 @@ Options:
 ```
 mulmo tool complete <file>
 
-Complete partial MulmoScript with schema defaults and optional style/template
+Complete MulmoScript with schema defaults and optional style
 
 Positionals:
-  file  Input beats file path (JSON)                             [string] [required]
+  file  Input beats file path (JSON)                         [string] [required]
 
 Options:
-      --version   Show version number                                    [boolean]
-  -v, --verbose   verbose log                [boolean] [required] [default: false]
-  -h, --help      Show help                                              [boolean]
-  -o, --output    Output file path (default: <file>_completed.json)       [string]
-  -t, --template  Template name to apply                                  [string]
-  -s, --style     Style name or file path (.json)                         [string]
+      --version   Show version number                                  [boolean]
+  -v, --verbose   verbose log              [boolean] [required] [default: false]
+  -h, --help      Show help                                            [boolean]
+  -o, --output    Output file path (default: <file>_completed.json)     [string]
+  -t, --template  Template name to apply
+              [string] [choices: "akira_comic", "ani", "business", "characters",
+      "children_book", "coding", "comic_strips", "documentary", "drslump_comic",
+   "ghibli_comic", "ghibli_comic_strips", "ghost_comic", "html", "image_prompt",
+                  "leda", "onepiece_comic", "portrait_movie", "realistic_movie",
+                 "sensei_and_taro", "shorts", "sifi_story", "trailer", "vision"]
+  -s, --style     Style name or file path (.json)                       [string]
 
 Examples:
   # Complete minimal script with schema defaults
@@ -822,17 +874,21 @@ Examples:
 ```
 mulmo tool info [category]
 
-Show available options for MulmoScript configuration
+Show available options (styles, bgm, templates, voices, images, movies, llm,
+themes, config, merged)
 
 Positionals:
   category  Category to show info for
-    [string] [choices: "styles", "bgm", "templates", "voices", "images", "movies", "llm"]
+  [string] [choices: "styles", "bgm", "templates", "voices", "images", "movies",
+                                            "llm", "themes", "config", "merged"]
 
 Options:
       --version  Show version number                                   [boolean]
   -v, --verbose  verbose log               [boolean] [required] [default: false]
   -h, --help     Show help                                             [boolean]
-  -F, --format   Output format      [string] [choices: "text", "json", "yaml"]
+  -F, --format   Output format
+                    [string] [choices: "text", "json", "yaml"] [default: "text"]
+  -S, --script   Script file path (required for 'merged' category)      [string]
 
 Examples:
   # Show all available categories

package/lib/actions/audio.js

@@ -5,7 +5,7 @@ import { fileWriteAgent } from "@graphai/vanilla_node_agents";
 import { ttsOpenaiAgent, ttsGoogleAgent, ttsGeminiAgent, ttsElevenlabsAgent, ttsKotodamaAgent, addBGMAgent, combineAudioFilesAgent, mediaMockAgent, } from "../agents/index.js";
 import { text2SpeechProviderSchema } from "../types/index.js";
 import { fileCacheAgentFilter } from "../utils/filters.js";
-import { getAudioArtifactFilePath, getAudioFilePath, getOutputStudioFilePath, resolveDirPath, defaultBGMPath, mkdir, writingMessage } from "../utils/file.js";
+import { getAudioArtifactFilePath, getAudioFilePath, getGroupedAudioFilePath, getOutputStudioFilePath, resolveDirPath, defaultBGMPath, mkdir, writingMessage, } from "../utils/file.js";
 import { localizedText, settings2GraphAIConfig } from "../utils/utils.js";
 import { text2hash } from "../utils/utils_node.js";
 import { provider2TTSAgent } from "../types/provider2agent.js";
@@ -43,7 +43,9 @@ export const getBeatAudioPathOrUrl = (text, context, beat, lang) => {
     ].join(":");
     GraphAILogger.log(`getBeatAudioPathOrUrl [${hash_string}]`);
     const audioFileName = `${context.studio.filename}_${text2hash(hash_string)}`;
-    const maybeAudioFile = getAudioFilePath(audioDirPath, context.studio.filename, audioFileName, lang);
+    const maybeAudioFile = context.fileDirs.grouped
+        ? getGroupedAudioFilePath(audioDirPath, audioFileName, lang)
+        : getAudioFilePath(audioDirPath, context.studio.filename, audioFileName, lang);
     return getAudioPathOrUrl(context, beat, maybeAudioFile);
 };
 // for lipSync
@@ -241,7 +243,7 @@ export const generateBeatAudio = async (index, context, args) => {
         const fileName = MulmoStudioContextMethods.getFileName(context);
         const audioDirPath = MulmoStudioContextMethods.getAudioDirPath(context);
         const outDirPath = MulmoStudioContextMethods.getOutDirPath(context);
-        const audioSegmentDirPath = resolveDirPath(audioDirPath, fileName);
+        const audioSegmentDirPath = context.fileDirs.grouped ? audioDirPath : resolveDirPath(audioDirPath, fileName);
         mkdir(outDirPath);
         mkdir(audioSegmentDirPath);
         const config = settings2GraphAIConfig(settings);
@@ -279,8 +281,10 @@ export const audio = async (context, args) => {
         const audioDirPath = MulmoStudioContextMethods.getAudioDirPath(context);
         const outDirPath = MulmoStudioContextMethods.getOutDirPath(context);
         const audioArtifactFilePath = getAudioArtifactFilePath(context);
-        const audioSegmentDirPath = resolveDirPath(audioDirPath, fileName);
-        const audioCombinedFilePath = getAudioFilePath(audioDirPath, fileName, fileName, context.lang);
+        const audioSegmentDirPath = context.fileDirs.grouped ? audioDirPath : resolveDirPath(audioDirPath, fileName);
+        const audioCombinedFilePath = context.fileDirs.grouped
+            ? getGroupedAudioFilePath(audioDirPath, fileName, context.lang)
+            : getAudioFilePath(audioDirPath, fileName, fileName, context.lang);
         const outputStudioFilePath = getOutputStudioFilePath(outDirPath, fileName);
         mkdir(outDirPath);
         mkdir(audioSegmentDirPath);

package/lib/actions/bundle.js

@@ -61,8 +61,8 @@ export const mulmoViewerBundle = async (context, options = {}) => {
     const baseDir = context.fileDirs.baseDirPath;
     const filename = context.studio.filename;
     mkdir(outDir);
-    // Bundle directory: output/<script_name>/
-    const bundleDir = path.resolve(outDir, filename);
+    // Bundle directory: when grouped, outDir is already output/<script_name>/
+    const bundleDir = context.fileDirs.grouped ? outDir : path.resolve(outDir, filename);
     mkdir(bundleDir);
     const zipper = skipZip ? undefined : new ZipBuilder(path.resolve(bundleDir, zipFileName));
     // text

package/lib/actions/image_agents.js

@@ -1,6 +1,6 @@
 import { GraphAILogger } from "graphai";
 import { MulmoPresentationStyleMethods, MulmoStudioContextMethods, MulmoBeatMethods, MulmoMediaSourceMethods } from "../methods/index.js";
-import { getBeatPngImagePath, getBeatMoviePaths, getAudioFilePath } from "../utils/file.js";
+import { getBeatPngImagePath, getBeatMoviePaths, getAudioFilePath, getGroupedAudioFilePath } from "../utils/file.js";
 import { imagePrompt, htmlImageSystemPrompt } from "../utils/prompt.js";
 import { renderHTMLToImage } from "../utils/html_render.js";
 import { beatId } from "../utils/utils.js";
@@ -54,8 +54,10 @@ export const imagePreprocessAgent = async (namedInputs) => {
             returnValue.bgmFile = MulmoMediaSourceMethods.resolve(context.studio.script.audioParams.bgm, context);
             const folderName = MulmoStudioContextMethods.getFileName(context);
             const audioDirPath = MulmoStudioContextMethods.getAudioDirPath(context);
-            const fileName = `${beatId(beat.id, index)}_trimmed.mp3`;
-            returnValue.audioFile = getAudioFilePath(audioDirPath, folderName, fileName);
+            const trimmedName = `${beatId(beat.id, index)}_trimmed`;
+            returnValue.audioFile = context.fileDirs.grouped
+                ? getGroupedAudioFilePath(audioDirPath, trimmedName)
+                : getAudioFilePath(audioDirPath, folderName, trimmedName);
         }
         else {
             // Audio file will be set from the beat's audio file when available

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

@@ -7,6 +7,8 @@ export declare const builder: (yargs: Argv) => Argv<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

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

@@ -7,6 +7,8 @@ export declare const builder: (yargs: Argv) => Argv<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

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

@@ -7,6 +7,8 @@ export declare const builder: (yargs: Argv) => Argv<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

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

@@ -7,6 +7,8 @@ export declare const builder: (yargs: Argv) => Argv<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

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

@@ -7,6 +7,8 @@ export declare const builder: (yargs: Argv) => Argv<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

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

@@ -7,6 +7,8 @@ export declare const builder: (yargs: Argv) => Argv<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

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

@@ -7,6 +7,8 @@ export declare const builder: (yargs: Argv) => Argv<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

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

@@ -7,6 +7,8 @@ export declare const builder: (yargs: Argv) => Argv<import("yargs").Omit<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

package/lib/cli/common.d.ts

@@ -7,6 +7,8 @@ export declare const commonOptions: (yargs: Argv) => Argv<{
     l: string | undefined;
 } & {
     f: boolean;
+} & {
+    g: boolean;
 } & {
     backup: boolean;
 } & {

package/lib/cli/common.js

@@ -25,6 +25,12 @@ export const commonOptions = (yargs) => {
         describe: "Force regenerate",
         type: "boolean",
         default: false,
+    })
+        .option("g", {
+        alias: "grouped",
+        describe: "Output all files under output/<basename>/ directory",
+        type: "boolean",
+        default: false,
     })
         .option("backup", {
         describe: "create backup media file",

package/lib/cli/helpers.d.ts

@@ -10,5 +10,6 @@ export declare const getFileObject: (args: {
     presentationStyle?: string;
     file: string;
     nodeModuleRootPath?: string;
+    grouped?: boolean;
 }) => FileObject;
 export declare const initializeContext: (argv: CliArgs<InitOptions>, raiseError?: boolean) => Promise<MulmoStudioContext | null>;

package/lib/cli/helpers.js

@@ -30,9 +30,9 @@ export const setGraphAILogger = (verbose, logValues) => {
     }
 };
 export const getFileObject = (args) => {
-    const { basedir, outdir, imagedir, audiodir, file, presentationStyle, nodeModuleRootPath } = args;
+    const { basedir, outdir, imagedir, audiodir, file, presentationStyle, nodeModuleRootPath, grouped = false } = args;
     const baseDirPath = getBaseDirPath(basedir);
-    const outDirPath = getFullPath(baseDirPath, outdir ?? outDirName);
+    const baseOutDirPath = getFullPath(baseDirPath, outdir ?? outDirName);
     const { fileOrUrl, fileName } = (() => {
         if (file === "__clipboard") {
             // We generate a new unique script file from clipboard text in the output directory
@@ -40,8 +40,8 @@ export const getFileObject = (args) => {
             const clipboardText = clipboardy.readSync();
             const json = JSON.parse(clipboardText);
             const formattedText = JSON.stringify(json, null, 2);
-            const resolvedFilePath = resolveDirPath(outDirPath, `${generatedFileName}.json`);
-            mkdir(outDirPath);
+            const resolvedFilePath = resolveDirPath(baseOutDirPath, `${generatedFileName}.json`);
+            mkdir(baseOutDirPath);
             fs.writeFileSync(resolvedFilePath, formattedText, "utf8");
             return { fileOrUrl: resolvedFilePath, fileName: generatedFileName };
         }
@@ -49,6 +49,7 @@ export const getFileObject = (args) => {
         const parsedFileName = path.parse(resolvedFileOrUrl).name;
         return { fileOrUrl: resolvedFileOrUrl, fileName: parsedFileName };
     })();
+    const outDirPath = grouped ? getFullPath(baseOutDirPath, fileName) : baseOutDirPath;
     const isHttpPath = isHttp(fileOrUrl);
     const mulmoFilePath = isHttpPath ? "" : getFullPath(baseDirPath, fileOrUrl);
     const mulmoFileDirPath = path.dirname(isHttpPath ? baseDirPath : mulmoFilePath);
@@ -71,6 +72,7 @@ export const getFileObject = (args) => {
         presentationStylePath,
         fileName,
         nodeModuleRootPath,
+        grouped,
     };
 };
 export const initializeContext = async (argv, raiseError = false) => {
@@ -81,6 +83,7 @@ export const initializeContext = async (argv, raiseError = false) => {
         audiodir: argv.a,
         presentationStyle: argv.p,
         file: argv.file ?? "",
+        grouped: Boolean(argv.g),
     });
     setGraphAILogger(Boolean(argv.v), { files });
     return await initializeContextFromFiles(files, raiseError, Boolean(argv.f), Boolean(argv.backup), argv.c, argv.l);

package/lib/methods/mulmo_studio_context.js

@@ -44,6 +44,9 @@ export const MulmoStudioContextMethods = {
     },
     getImageProjectDirPath(context) {
         const imageDirPath = MulmoStudioContextMethods.getImageDirPath(context);
+        if (context.fileDirs.grouped) {
+            return imageDirPath;
+        }
         return `${imageDirPath}/${context.studio.filename}`;
     },
     getOutDirPath(context) {

package/lib/types/type.d.ts

@@ -128,6 +128,7 @@ export interface FileObject {
     outputMultilingualFilePath: string;
     presentationStylePath: string | undefined;
     fileName: string;
+    grouped: boolean;
 }
 export type InitOptions = {
     b?: string;
@@ -138,6 +139,7 @@ export type InitOptions = {
     l?: string;
     c?: string;
     p?: string;
+    g?: boolean;
 };
 export type PublicAPIArgs = {
     settings?: Record<string, string>;

package/lib/utils/file.d.ts

@@ -20,7 +20,9 @@ export declare const fetchMulmoScriptFile: (url: string) => Promise<{
 export declare const getOutputStudioFilePath: (outDirPath: string, fileName: string) => string;
 export declare const getOutputMultilingualFilePath: (outDirPath: string, fileName: string) => string;
 export declare const resolveDirPath: (dirPath: string, studioFileName: string) => string;
+export declare const formatAudioFileName: (name: string, lang?: string) => string;
 export declare const getAudioFilePath: (audioDirPath: string, dirName: string, fileName: string, lang?: string) => string;
+export declare const getGroupedAudioFilePath: (audioDirPath: string, fileName: string, lang?: string) => string;
 export declare const getAudioArtifactFilePath: (context: MulmoStudioContext) => string;
 export declare const getOutputVideoFilePath: (outDirPath: string, fileName: string, lang?: string, caption?: string) => string;
 export declare const imageSuffix = "p";

package/lib/utils/file.js

@@ -68,11 +68,15 @@ export const resolveDirPath = (dirPath, studioFileName) => {
     return path.resolve(dirPath, studioFileName);
 };
 // audio
+export const formatAudioFileName = (name, lang) => {
+    const suffix = lang ? `_${lang}` : "";
+    return `${name}${suffix}.mp3`;
+};
 export const getAudioFilePath = (audioDirPath, dirName, fileName, lang) => {
-    if (lang) {
-        return path.resolve(audioDirPath, dirName, `${fileName}_${lang}.mp3`);
-    }
-    return path.resolve(audioDirPath, dirName, fileName + ".mp3");
+    return path.resolve(audioDirPath, dirName, formatAudioFileName(fileName, lang));
+};
+export const getGroupedAudioFilePath = (audioDirPath, fileName, lang) => {
+    return path.resolve(audioDirPath, formatAudioFileName(fileName, lang));
 };
 export const getAudioArtifactFilePath = (context) => {
     const suffix = context.lang ? `_${context.lang}` : "";

package/lib/utils/mulmo_config.d.ts

@@ -4,21 +4,21 @@ import { type PartialMulmoScript } from "../tools/complete_script.js";
  * 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)
+ *
+ * Note: kind:"path" entries are NOT resolved here.
+ * They remain as relative paths and are resolved at runtime
+ * relative to the script file directory (mulmoFileDirPath),
+ * consistent with all other path resolution in MulmoScript.
  */
 export declare const loadMulmoConfig: (baseDirPath: string) => MulmoConfigResult | null;
 /**

package/lib/utils/mulmo_config.js

@@ -3,7 +3,6 @@ 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.
@@ -18,48 +17,17 @@ export const findConfigFile = (baseDirPath) => {
     }
     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)
+ *
+ * Note: kind:"path" entries are NOT resolved here.
+ * They remain as relative paths and are resolved at runtime
+ * relative to the script file directory (mulmoFileDirPath),
+ * consistent with all other path resolution in MulmoScript.
  */
 export const loadMulmoConfig = (baseDirPath) => {
     const configPath = findConfigFile(baseDirPath);
@@ -69,10 +37,9 @@ export const loadMulmoConfig = (baseDirPath) => {
     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;
+        const defaults = rest;
+        const override = rawOverride ? rawOverride : null;
         return { defaults, override };
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",