Kumiki

Kumiki is a CLI tool that automatically generates videos from JSON-based configuration files. You can create videos combining text, images, videos, and composite scenes using simple configuration files.

Features

• 📝 JSON-based Configuration: Define video composition in human-readable JSON format
• 🎬 Various Scene Types: Support for text, image, video, and composite scenes
• 🎵 Audio Support: BGM, narration, AI music generation
• 🔄 Scene Transitions: Fade, wipe, dissolve effects
• 🗣️ AI Voice Synthesis: Automatic narration generation via Google Gemini API
• 🎼 AI Music Generation: Automatic BGM generation via Google Gemini API
• 🖼️ AI Image Generation: Automatic image generation via Google Gemini API
• 🔍 Schema Validation: Syntax checking and validation for configuration files
• 💾 Intelligent Caching: Automatic caching and reuse of generated content
• 📋 AI-Assisted Development: Output JSON Schema for integration with AI tools

Requirements

• Node.js 18.0.0 or higher
• FFmpeg (must be installed on your system)
• Google Chrome (for preview functionality)
• Google Gemini API key (for AI features)

Installation

Install from npm (Recommended)

npm install -g @henteko/kumiki

# Verify installation
kumiki --version

Build from source

# Clone the repository
git clone https://github.com/henteko/kumiki.git
cd kumiki

# Install dependencies
npm install

# Build and install globally
npm run build
npm link

kumiki --version

Configuration

Set up your Gemini API key (required for AI features):

kumiki config set gemini.apiKey YOUR_API_KEY

You can also set it via environment variable:

export GEMINI_API_KEY=YOUR_API_KEY

Usage

Basic Commands

1. Initialize a New Project

kumiki init [filename]

Generate a sample configuration file.

Options:

• -f, --force: Overwrite existing file
• Default filename is project.json

2. Validate Project File

kumiki validate <project.json>

Validate the syntax and content of your configuration file.

3. Preview

kumiki preview <project.json>

Display a video preview in your browser (interactive).

4. Generate Video

kumiki generate <project.json> --output video.mp4

Generate a video from the configuration file.

Options:

• -o, --output <path>: Output file path (default: output.mp4)
• -t, --temp-dir <path>: Temporary files directory
• -c, --concurrency <number>: Parallel processing count (default: 2)
• --keep-temp: Keep temporary files

5. Show Schema

kumiki show-schema [--include-examples]

Display the JSON Schema for Kumiki projects. Useful for AI tool integration.

6. Configuration Management

# Set Gemini API key
kumiki config set gemini.apiKey YOUR_API_KEY

# Get a configuration value
kumiki config get gemini.apiKey

# Remove a configuration value
kumiki config unset gemini.apiKey

# List all configuration values
kumiki config list

# Show configuration file path
kumiki config path

Manage global configuration settings. Configuration is stored in ~/.kumiki/config.json.

7. Cache Management

# Check cache status
kumiki cache status

# Show cache size
kumiki cache size

# Clear cache
kumiki cache clear

# Clear only cache older than 30 days
kumiki cache clear --older-than 30d

Manage cached generated images, music, and narrations.

Project File Structure

Basic Example

To start a new project, use the kumiki init command to generate a sample file:

kumiki init my-project.json

Generated sample file:

{
  "version": "1.0.0",
  "name": "My Awesome Video",
  "settings": {
    "resolution": "1920x1080",
    "fps": 30,
    "narrationDefaults": {
      "voice": {
        "languageCode": "en-US",
        "name": "Journey",
        "speakingRate": 1.0
      },
      "volumeMix": {
        "narration": 0.8,
        "bgm": 0.3
      }
    }
  },
  "audio": {
    "backgroundMusic": {
      "src": "generate://ambient piano music for presentation",
      "volume": 0.7,
      "fadeIn": 2,
      "fadeOut": 3
    }
  },
  "scenes": [
    {
      "id": "intro",
      "type": "text",
      "duration": 5,
      "content": {
        "text": "Hello, Kumiki!",
        "style": {
          "fontSize": 64,
          "color": "#FFFFFF",
          "fontFamily": "Arial",
          "fontWeight": "bold",
          "textAlign": "center"
        },
        "position": {
          "x": "center",
          "y": "center"
        }
      },
      "background": {
        "type": "gradient",
        "value": "linear-gradient(45deg, #FC466B 0%, #3F5EFB 100%)"
      },
      "narration": {
        "text": "Hello, Kumiki!"
      }
    },
    {
      "id": "generate-image",
      "type": "image",
      "duration": 10,
      "content": {
        "src": "generate://A beautiful sunset over the ocean with orange and pink sky",
        "fit": "cover",
        "position": { "x": "center", "y": "center" }
      },
      "narration": {
        "text": "This is a beautiful sunset over the ocean with orange and pink sky generated by Gemini."
      }
    }
  ]
}

Scene Types

Text Scene

{
  "id": "text-1",
  "type": "text",
  "duration": 5,
  "content": {
    "text": "Hello World",
    "style": {
      "fontSize": 48,
      "color": "#FFFFFF",
      "fontFamily": "Arial",
      "fontWeight": "bold",
      "textAlign": "center"
    },
    "position": {
      "x": "center",
      "y": "center"
    }
  }
}

Image Scene

{
  "id": "image-1",
  "type": "image",
  "duration": 3,
  "content": {
    "src": "assets/logo.png",
    "fit": "contain",
    "position": {
      "x": "center",
      "y": "center"
    }
  }
}

Video Scene

{
  "id": "video-1",
  "type": "video",
  "duration": 10,
  "content": {
    "src": "assets/intro.mp4",
    "trim": {
      "start": 0,
      "end": 10
    }
  }
}

Composite Scene

{
  "id": "composite-1",
  "type": "composite",
  "duration": 5,
  "layers": [
    {
      "type": "image",
      "content": {
        "src": "assets/background.jpg",
        "fit": "cover",
        "position": { "x": "center", "y": "center" }
      }
    },
    {
      "type": "text",
      "content": {
        "text": "Overlay Text",
        "style": {
          "fontSize": 36,
          "color": "#FFFFFF",
          "fontFamily": "Arial"
        },
        "position": { "x": "center", "y": 100 }
      },
      "opacity": 0.9,
      "zIndex": 1
    }
  ]
}

Background Settings

{
  "background": {
    "type": "color",
    "value": "#1a1a1a"
  }
}

{
  "background": {
    "type": "gradient",
    "value": "linear-gradient(45deg, #667eea 0%, #764ba2 100%)"
  }
}

{
  "background": {
    "type": "image",
    "value": "assets/background.jpg"
  }
}

Transitions

{
  "transition": {
    "type": "fade",
    "duration": 1.0
  }
}

{
  "transition": {
    "type": "wipe",
    "duration": 0.5,
    "direction": "left"
  }
}

Audio Settings

BGM (from file)

{
  "audio": {
    "backgroundMusic": {
      "src": "assets/bgm.mp3",
      "volume": 0.5,
      "fadeIn": 2,
      "fadeOut": 2
    }
  }
}

BGM (AI-generated)

{
  "audio": {
    "backgroundMusic": {
      "src": {
        "type": "generate",
        "prompt": "calm and bright piano and strings BGM",
        "duration": 30,
        "seed": 42
      },
      "volume": 0.5,
      "fadeIn": 2,
      "fadeOut": 2
    }
  }
}

Narration

You can add narration to each scene. Audio is automatically cached to avoid regeneration with the same text and settings.

{
  "narration": {
    "text": "This video introduces new features.",
    "voice": {
      "languageCode": "en-US",
      "name": "Journey",
      "speakingRate": 1.0,
      "pitch": 0,
      "volumeGainDb": 0
    },
    "timing": {
      "delay": 0.5,
      "fadeIn": 0.3,
      "fadeOut": 0.3
    }
  }
}

AI-Assisted Development

Integration with Claude Code or Gemini CLI

# Get JSON Schema
kumiki show-schema --include-examples > schema.json

# Pass to AI tools to generate video composition
# Example: "Please create a 30-second product introduction video"

Schema Validation

# Validation example using ajv
kumiki show-schema > schema.json
ajv validate -s schema.json -d my-project.json

Advanced Usage

Project Settings

{
  "settings": {
    "resolution": "1920x1080",
    "fps": 30,
    "outputFormat": "mp4",
    "quality": "high",
    "narrationDefaults": {
      "voice": {
        "languageCode": "en-US",
        "name": "Journey",
        "speakingRate": 1.0
      },
      "volumeMix": {
        "narration": 0.8,
        "bgm": 0.3
      }
    },
    "transitionDefaults": {
      "type": "fade",
      "duration": 0.5
    }
  }
}

AI-Generated Content

Image Generation

{
  "content": {
    "src": {
      "type": "generate",
      "prompt": "Mount Fuji at sunset",
      "style": "photorealistic",
      "aspectRatio": "16:9"
    }
  }
}

Music Generation

{
  "audio": {
    "backgroundMusic": {
      "src": {
        "type": "generate",
        "prompt": "energetic rock-style BGM",
        "duration": 60,
        "config": {
          "genre": "rock",
          "tempo": "fast",
          "mood": "energetic"
        }
      }
    }
  }
}

Cache System

Kumiki automatically caches generated content (images, music, narration) to avoid regeneration with the same parameters.

• Image Cache: Cache key generated from prompt, style, and aspect ratio
• Music Cache: Cache key generated from prompt, duration, and config
• Narration Cache: Cache key generated from text and voice settings

Cache is stored in the .kumiki-cache/ directory.

Development

Setup

# Install dependencies
npm install

# Generate schemas
npm run generate:schema

# Run in development mode
npm run dev

# Build
npm run build

# Lint
npm run lint

# Type check
npm run typecheck

Project Structure

kumiki/
├── src/
│   ├── cli.ts              # CLI entry point
│   ├── commands/           # CLI commands
│   ├── core/              # Core functionality
│   ├── scenes/            # Scene renderers
│   ├── services/          # External service integrations
│   ├── schemas/           # TypeSpec definitions
│   └── utils/             # Utilities
├── examples/              # Sample projects
└── internal-docs/         # Internal documentation

Troubleshooting

FFmpeg Not Found

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows
# Download from FFmpeg official site and add to PATH

Out of Memory Error

For large video processing:

NODE_OPTIONS="--max-old-space-size=8192" kumiki generate large-project.json

Cache Issues

# Clear cache
kumiki cache clear

# Check temporary files
kumiki generate project.json --keep-temp

License

Apache License 2.0

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.