mulmocast 0.0.1 → 0.0.3

package/README.md

@@ -1,11 +1,19 @@
-# mulmo
+# mulmocast
 
-A CLI tool for generating podcast and video content from script files. Automates the process of creating audio, images, and video from structured script files.
+A CLI tool for generating podcast and video content from script files (MulmoScript). Automates the process of creating audio, images, and video from structured MulmoScript files.
+
+## What is MulmoScript?
+
+**MulmoScript** is a simple JSON/YAML format for describing multi-modal content.  
+You can define speakers, text, images, and layout — all in one script.
+
+A Hello World script is available in [./docs/scripts](./docs/scripts).   
+See [MulmoScript Format](#mulmoscript-format) for details on the structure.
 
 ## Installation
 
 ```bash
-npm install -g mulmo
+npm install -g mulmocast
 ```
 
 You'll also need to install ffmpeg:
@@ -21,11 +29,16 @@ brew install ffmpeg
 
 Create a `.env` file in your project directory with the following API keys:
 
-```
+### Required
+```bash
 OPENAI_API_KEY=your_openai_api_key
-GOOGLE_PROJECT_ID=your_google_project_id # optional for movie, image generation
-NIJIVOICE_API_KEY=your_nijivoice_api_key # optional for movie, audio generation
-BROWSERLESS_API_TOKEN=your_browserless_api_token # optional for scripting from web content
+```
+### Optional
+```bash
+DEFAULT_OPENAI_IMAGE_MODEL=gpt-image-1 # for the advanced image generation model
+GOOGLE_PROJECT_ID=your_google_project_id # for Google's image generation model
+NIJIVOICE_API_KEY=your_nijivoice_api_key # for Nijivoice's TTS model
+BROWSERLESS_API_TOKEN=your_browserless_api_token # to access web in mulmo-tool
 ```
 
 ## Workflow
@@ -35,14 +48,28 @@ BROWSERLESS_API_TOKEN=your_browserless_api_token # optional for scripting from w
 3. Generate images with `mulmo images` 
 4. Create final video with `mulmo movie`
 
+## Quick Start
+
+```bash
+# Generate script with interactive mode
+mulmo-tool scripting -i -t children_book -o ./ -s story
+```
+After running this command, you'll create a story script through an interactive conversation with the AI.
+
+```bash
+# Generate both audio and images, then combine into video
+mulmo movie {generated_script_file}
+```
+Replace `{generated_script_file}` with the output file from the previous command, such as `story-1746600802426.json`.
+
 ## Generate MulmoScript
 
 ```bash
-# Generate script from web content
-mulmo-tool scripting -u https://example.com -t seed_materials
+# Generate script from web content (requires Browserless API KEY)
+mulmo-tool scripting -u https://example.com
 
 # Generate script with interactive mode
-mulmo-tool scripting -i -t seed_interactive
+mulmo-tool scripting -i
 ```
 
 ## Generate content from MulmoScript
@@ -51,24 +78,111 @@ Mulmo provides several commands to handle different aspects of content creation:
 
 ```bash
 # Generate audio from script
-mulmo audio -f script.json
+mulmo audio script.json
 
 # Generate images for script
-mulmo images -f script.json
+mulmo images script.json
 
 # Generate both audio and images, then combine into video
-mulmo movie -f script.json
+mulmo movie script.json
 
 # Translate script to Japanese
-mulmo translate -f script.json
+mulmo translate script.json
 ```
 
+## 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.
+
+To force regeneration, delete the old files — including temporary files — under the output directory before re-running the command or use -f (force) option.
+
+If you modify the text or instruction fields in a MulmoScript, mulmo will automatically detect the changes and regenerate the corresponding audio content upon re-run.
+
 ## MulmoScript Format
 
 MulmoScript is a JSON format to define podcast or video scripts:
-schema: [./src/types/schema.ts](./src/types/schema.ts)
+Schema definition: [schema.ts](./src/types/schema.ts)
+
+## Sample MulmoScript
+
+https://github.com/receptron/mulmocast-cli/tree/main/scripts
+
+## Directory Structure
+
+| Directory         | Description                                                                 |
+|-------------------|-----------------------------------------------------------------------------|
+| `output/`         | Artifacts generated by commands — e.g., `.json`, audio, and video files    |
+| `output/audio/`   | Temporary audio fragments used in the final audio assembly                  |
+| `output/images/`  | Image files generated by the `images` command                               |
+| `output/cache/`   | Internal cache files for various processing steps                           |
+
+> These directories are automatically created as needed by the `mulmo` commands.
+
+## Help
+
+CLI Usage
+
+### `mulmo -h` Output
+Use this command to generate content (audio, images, movie) from an existing MulmoScript.
+
+```bash
+mulmo -h
+```
+```bash
+mulmo <action> <file>
+
+Run mulmocast
+
+Positionals:
+  action  action to perform
+       [string] [choices: "translate", "audio", "images", "movie", "preprocess"]
+  file    Mulmo Script File                                             [string]
+
+Options:
+      --version   Show version number                                  [boolean]
+  -v, --verbose   verbose log              [boolean] [required] [default: false]
+  -o, --outdir    output dir                                            [string]
+  -b, --basedir   base dir                                              [string]
+  -a, --audiodir  audio dir                                             [string]
+  -i, --imagedir  image dir                                             [string]
+  -f, --force     force generate                      [boolean] [default: false]
+      --help      Show help                                            [boolean]
+
+```
+
+### `mulmo-tool -h` Output
+Use this command to generate a new MulmoScript from a URL or interactively.
+
+```bash
+mulmo-tool -h
+```
+
+```bash
+mulmo-tool <action>
+
+Run mulmocast tool
+
+Positionals:
+  action  action to perform            [string] [choices: "scripting", "prompt"]
+
+Options:
+      --version      Show version number                               [boolean]
+  -v, --verbose      verbose log           [boolean] [required] [default: false]
+  -o, --outdir       output dir                                         [string]
+  -b, --basedir      base dir                                           [string]
+  -u, --url          URLs to reference (required when not in interactive mode)
+                                                           [array] [default: []]
+  -i, --interactive  Generate script in interactive mode with user prompts
+                                                                       [boolean]
+  -t, --template     Template name to use
+   [string] [choices: "business", "children_book", "coding", "podcast_standard",
+                                                              "sensei_and_taro"]
+  -c, --cache        cache dir                                          [string]
+  -s, --script       script filename                [string] [default: "script"]
+      --help         Show help                                         [boolean]
+```
 
 
 ## Contributing
 
 For developers interested in contributing to this project, please see [CONTRIBUTING.md](./CONTRIBUTING.md).
+

package/assets/html/chart.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Simple Chart.js Bar Chart</title>
+    <style>
+        ${style}
+        .chart-container {
+            width: ${width}px;
+            margin: 0 auto;
+        }
+    </style>
+    <!-- Include Chart.js from CDN -->
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+</head>
+<body>
+    <h1>${title}</h1>
+    <div class="chart-container">
+        <canvas id="myChart"></canvas>
+    </div>
+
+    <!-- Plain JavaScript instead of TypeScript -->
+    <script>
+        // Wait for DOM to be fully loaded
+        document.addEventListener('DOMContentLoaded', function() {
+            // Get the canvas element
+            const ctx = document.getElementById('myChart');
+            
+            // Create the data object (no TypeScript interfaces)
+            const chartData = ${chart_data};
+
+            // Initialize the chart
+            new Chart(ctx, chartData);
+        });
+    </script>
+</body>
+</html>

package/assets/html/mermaid.html

@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Mermaid Diagram</title>
+    <style>
+        ${style}
+        .container {
+            height: 100%;
+            display: flex;
+            flex-direction: column;
+        }
+        .mermaid {
+            width: 100%;
+            height: 100%;
+            margin: 0 auto;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            flex-grow: 1;
+            overflow: auto;
+        }
+        .mermaid svg {
+            max-width: 100%;
+            max-height: 100%;
+            height: auto;
+            width: auto;
+        }
+    </style>
+    <!-- Include Mermaid from CDN -->
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <script>
+        mermaid.initialize({
+            startOnLoad: true,
+            theme: 'default',
+            flowchart: {
+                useMaxWidth: true
+            }
+        });
+    </script>
+</head>
+<body>
+    <div class="container">
+        <h1>${title}</h1>
+        <div class="mermaid">
+            ${diagram_code}
+        </div>
+    </div>
+</body>
+</html> 

package/assets/templates/business.json

@@ -1,22 +1,13 @@
 {
   "title": "Business presentation",
-  "description": "Template for children book.",
-  "systemPrompt": "Generate a script for a business presentation of the given topic. Use textSlides or markdown to show slides or use imagePrompt to generate an appropriate image for that page. Use the JSON below as a template",
+  "description": "Template for business presentation.",
+  "systemPrompt": "Generate a script for a business presentation of the given topic. Use textSlides, markdown, mermaid, or chart to show slides. Extract image links in the article to reuse them in the presentation. Use the JSON below as a template. chartData is the data for Chart.js",
   "script": {
     "$mulmocast": {
       "version": "1.0",
       "credit": "closing"
     },
     "title": "Sample Title",
-    "canvasSize": {
-      "width": 1536,
-      "height": 1024
-    },
-    "imageParams": {
-      "style": "Style appropriate for business environment.",
-      "model": "gpt-image-1",
-      "size": "1536x1024"
-    },
     "speechParams": {
       "speakers": {
         "Presenter": {
@@ -41,7 +32,7 @@
           }
         },
         "textSlideParams": {
-          "cssStyles": ["h1 { margin-top: 400px }"]
+          "cssStyles": ["h1 { margin-top: 300px }"]
         }
       },
       {
@@ -81,8 +72,60 @@
       },
       {
         "speaker": "Presenter",
-        "text": "Our story begins with tree-dwelling primates—small mammals with forward-facing eyes and grasping hands. These ancestors lived in forests and evolved traits useful for climbing and visual depth perception.",
-        "imagePrompt": "tree-dwelling primates with forward-facing eyes in a jungle."
+        "text": "This page shows the sales and profits of this company from January 2024 to June 2024.",
+        "image": {
+          "type": "chart",
+          "title": "Sales and Profits (from Jan to June)",
+          "chartData": {
+            "type": "bar",
+            "data": {
+              "labels": ["January", "February", "March", "April", "May", "June"],
+              "datasets": [
+                {
+                  "label": "Revenue ($1000s)",
+                  "data": [120, 135, 180, 155, 170, 190],
+                  "backgroundColor": "rgba(54, 162, 235, 0.5)",
+                  "borderColor": "rgba(54, 162, 235, 1)",
+                  "borderWidth": 1
+                },
+                {
+                  "label": "Profit ($1000s)",
+                  "data": [45, 52, 68, 53, 61, 73],
+                  "backgroundColor": "rgba(75, 192, 192, 0.5)",
+                  "borderColor": "rgba(75, 192, 192, 1)",
+                  "borderWidth": 1
+                }
+              ]
+            },
+            "options": {
+              "responsive": true,
+              "animation": false
+            }
+          }
+        }
+      },
+      {
+        "speaker": "Presenter",
+        "text": "Next, let's look at a diagram of our business process flow. This illustrates the key steps from product development to sales.",
+        "image": {
+          "type": "mermaid",
+          "title": "Business Process Flow",
+          "code": {
+            "kind": "text",
+            "text": "graph LR\n    A[Market Research] --> B[Product Planning]\n    B --> C[Development]\n    C --> D[Testing]\n    D --> E[Manufacturing]\n    E --> F[Marketing]\n    F --> G[Sales]\n    G --> H[Customer Support]\n    H --> A"
+          }
+        }
+      },
+      {
+        "speaker": "Presenter",
+        "text": "This is the image of a pingpong ball.",
+        "image": {
+          "type": "image",
+          "source": {
+            "kind": "url",
+            "url": "https://github.com/receptron/mulmocast-media/raw/refs/heads/main/test/pingpong.png"
+          }
+        }
       }
     ]
   }

package/assets/templates/children_book.json

@@ -13,9 +13,7 @@
       "height": 1024
     },
     "imageParams": {
-      "style": "A hand-drawn style illustration with a warm, nostalgic atmosphere. The background is rich with natural scenery—lush forests, cloudy skies, and traditional Japanese architecture. Characters have expressive eyes, soft facial features, and are portrayed with gentle lighting and subtle shading. The color palette is muted yet vivid, using earthy tones and watercolor-like textures. The overall scene feels magical and peaceful, with a sense of quiet wonder and emotional depth, reminiscent of classic 1980s and 1990s Japanese animation.",
-      "model": "gpt-image-1",
-      "size": "1536x1024"
+      "style": "A hand-drawn style illustration with a warm, nostalgic atmosphere. The background is rich with natural scenery—lush forests, cloudy skies, and traditional Japanese architecture. Characters have expressive eyes, soft facial features, and are portrayed with gentle lighting and subtle shading. The color palette is muted yet vivid, using earthy tones and watercolor-like textures. The overall scene feels magical and peaceful, with a sense of quiet wonder and emotional depth, reminiscent of classic 1980s and 1990s Japanese animation."
     },
     "speechParams": {
       "speakers": {

package/assets/templates/coding.json

@@ -0,0 +1,140 @@
+{
+  "title": "Coding presentation",
+  "description": "Template for software and coding presentation.",
+  "systemPrompt": "Generate a script for a technical presentation of the given topic. Use markdown with a code block to show some code on a slide. Avoid long coding examples, which may not fit in a single slide. Use the JSON below as a template.",
+  "script": {
+    "$mulmocast": {
+      "version": "1.0",
+      "credit": "closing"
+    },
+    "title": "Sample Title",
+    "speechParams": {
+      "speakers": {
+        "Presenter": {
+          "voiceId": "shimmer",
+          "displayName": {
+            "en": "Presenter",
+            "ja": "語り手"
+          }
+        }
+      }
+    },
+    "lang": "en",
+    "beats": [
+      {
+        "speaker": "Presenter",
+        "text": "Today we're exploring a fascinating concept that has shaped some of the most innovative companies and leaders of our time: the Reality Distortion Field. This term has become synonymous with visionary leadership and the ability to accomplish seemingly impossible goals.",
+        "image": {
+          "type": "textSlide",
+          "slide": {
+            "title": "This is the title of this slide",
+            "bullets": []
+          }
+        },
+        "textSlideParams": {
+          "cssStyles": ["h1 { margin-top: 400px }"]
+        }
+      },
+      {
+        "speaker": "Presenter",
+        "text": "Here is the sample code",
+        "image": {
+          "type": "markdown",
+          "markdown": ["# Markdown Table Example", "```TypeScript", "const main = () => {", "  console.log('Hello World')", "}", "```"]
+        }
+      },
+      {
+        "speaker": "Presenter",
+        "text": "The evolution of humans is a complex journey that spans millions of years, shaped by biology, environment, and culture. Here's a high-level summary of the key stages in human evolution",
+        "image": {
+          "type": "textSlide",
+          "slide": {
+            "title": "Human Evolution",
+            "bullets": [
+              "Early Primates",
+              "Hominids and Hominins",
+              "Australopithecus",
+              "Genus Homo Emerges",
+              "Homo erectus and Migration",
+              "Neanderthals and Other Archaic Humans",
+              "Homo sapiens"
+            ]
+          }
+        }
+      },
+      {
+        "speaker": "Presenter",
+        "text": "Our story begins with tree-dwelling primates—small mammals with forward-facing eyes and grasping hands. These ancestors lived in forests and evolved traits useful for climbing and visual depth perception.",
+        "image": {
+          "type": "markdown",
+          "markdown": [
+            "# Markdown Table Example",
+            "| Item              | In Stock | Price |",
+            "| :---------------- | :------: | ----: |",
+            "| Python Hat        |   True   | 23.99 |",
+            "| SQL Hat           |   True   | 23.99 |",
+            "| Codecademy Tee    |  False   | 19.99 |",
+            "| Codecademy Hoodie |  False   | 42.99 |"
+          ]
+        }
+      },
+      {
+        "speaker": "Presenter",
+        "text": "Next, let's look at a diagram of our business process flow. This illustrates the key steps from product development to sales.",
+        "image": {
+          "type": "mermaid",
+          "title": "Business Process Flow",
+          "code": {
+            "kind": "text",
+            "text": "graph LR\n    A[Market Research] --> B[Product Planning]\n    B --> C[Development]\n    C --> D[Testing]\n    D --> E[Manufacturing]\n    E --> F[Marketing]\n    F --> G[Sales]\n    G --> H[Customer Support]\n    H --> A"
+          }
+        }
+      },
+      {
+        "speaker": "Presenter",
+        "text": "This page shows the sales and profits of this company from January 2024 to June 2024.",
+        "image": {
+          "type": "chart",
+          "title": "Sales and Profits (from Jan to June)",
+          "chartData": {
+            "type": "bar",
+            "data": {
+              "labels": ["January", "February", "March", "April", "May", "June"],
+              "datasets": [
+                {
+                  "label": "Revenue ($1000s)",
+                  "data": [120, 135, 180, 155, 170, 190],
+                  "backgroundColor": "rgba(54, 162, 235, 0.5)",
+                  "borderColor": "rgba(54, 162, 235, 1)",
+                  "borderWidth": 1
+                },
+                {
+                  "label": "Profit ($1000s)",
+                  "data": [45, 52, 68, 53, 61, 73],
+                  "backgroundColor": "rgba(75, 192, 192, 0.5)",
+                  "borderColor": "rgba(75, 192, 192, 1)",
+                  "borderWidth": 1
+                }
+              ]
+            },
+            "options": {
+              "responsive": true,
+              "animation": false
+            }
+          }
+        }
+      },
+      {
+        "speaker": "Presenter",
+        "text": "This is the image of a pingpong ball.",
+        "image": {
+          "type": "image",
+          "source": {
+            "kind": "url",
+            "url": "https://github.com/receptron/mulmocast-media/raw/refs/heads/main/test/pingpong.png"
+          }
+        }
+      }
+    ]
+  }
+}

package/lib/actions/audio.d.ts

@@ -1,3 +1,3 @@
 import "dotenv/config";
-import { MulmoStudioContext } from "../types";
-export declare const audio: (context: MulmoStudioContext, concurrency: number) => Promise<void>;
+import { MulmoStudioContext } from "../types/index.js";
+export declare const audio: (context: MulmoStudioContext) => Promise<void>;