# Kumiki

KumikiはJSONベースの設定ファイルから動画を自動生成するCLIツールです。シンプルな構成ファイルを使用して、テキスト、画像、動画、複合シーンを組み合わせた動画を作成できます。

## 特徴

- 📝 **JSONベースの設定**: 人間が読みやすいJSON形式で動画の構成を定義
- 🎬 **多様なシーンタイプ**: テキスト、画像、動画、複合シーンをサポート
- 🎵 **音声サポート**: BGM、ナレーション、AI音楽生成
- 🔄 **シーントランジション**: フェード、ワイプ、ディゾルブ効果
- 🗣️ **AI音声合成**: Google Gemini APIによるナレーション自動生成
- 🎼 **AI音楽生成**: Google Gemini APIによるBGM自動生成
- 🖼️ **AI画像生成**: Google Gemini APIによる画像自動生成
- 🔍 **スキーマ検証**: 設定ファイルの構文チェックと検証
- 💾 **インテリジェントキャッシュ**: 生成コンテンツの自動キャッシュと再利用
- 📋 **AI支援開発**: JSON Schemaを出力してAIツールと連携

## 必要条件

- Node.js 18.0.0以上
- FFmpeg（システムにインストール済みであること）
- Google Chrome（プレビュー機能用）
- Google Gemini APIキー（AI機能用）

## インストール

### npmからインストール（推奨）

```bash
npm install -g @henteko/kumiki

# インストール確認
kumiki --version
```

### ソースからビルド

```bash
# リポジトリをクローン
git clone https://github.com/henteko/kumiki.git
cd kumiki

# 依存関係をインストール
npm install

# ビルドとグローバルインストール
npm run build
npm link

kumiki --version
```

### 設定

Gemini APIキーを設定します（AI機能に必要）：

```bash
kumiki config set gemini.apiKey YOUR_API_KEY
```

環境変数でも設定できます：

```bash
export GEMINI_API_KEY=YOUR_API_KEY
```

## 使い方

### 基本的なコマンド

#### 1. 新規プロジェクトの初期化

```bash
kumiki init [filename]
```

サンプルの設定ファイルを生成します。

オプション:
- `-f, --force`: 既存ファイルを上書き
- デフォルトのファイル名は `project.json`

#### 2. プロジェクトファイルの検証

```bash
kumiki validate <project.json>
```

設定ファイルの構文と内容を検証します。

#### 3. プレビュー

```bash
kumiki preview <project.json>
```

ブラウザで動画のプレビューを表示します（インタラクティブ）。

#### 4. 動画生成

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

設定ファイルから動画を生成します。

オプション:
- `-o, --output <path>`: 出力ファイルパス（デフォルト: output.mp4）
- `-t, --temp-dir <path>`: 一時ファイルディレクトリ
- `-c, --concurrency <number>`: 並列処理数（デフォルト: 2）
- `--keep-temp`: 一時ファイルを保持

#### 5. スキーマ表示

```bash
kumiki show-schema [--include-examples]
```

KumikiプロジェクトのJSON Schemaを表示します。AIツールとの連携に便利です。

#### 6. 設定管理

```bash
# Gemini APIキーを設定
kumiki config set gemini.apiKey YOUR_API_KEY

# 設定値を取得
kumiki config get gemini.apiKey

# 設定値を削除
kumiki config unset gemini.apiKey

# すべての設定値を表示
kumiki config list

# 設定ファイルのパスを表示
kumiki config path
```

グローバル設定を管理します。設定は `~/.kumiki/config.json` に保存されます。

#### 7. キャッシュ管理

```bash
# キャッシュの状態を確認
kumiki cache status

# キャッシュサイズを表示
kumiki cache size

# キャッシュをクリア
kumiki cache clear

# 30日以上前のキャッシュのみクリア
kumiki cache clear --older-than 30d
```

生成された画像、音楽、ナレーションのキャッシュを管理します。

## プロジェクトファイルの構造

### 基本的な例

新規プロジェクトを開始する場合は、`kumiki init` コマンドを使用してサンプルファイルを生成できます：

```bash
kumiki init my-project.json
```

生成されるサンプルファイル：

```json
{
  "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."
      }
    }
  ]
}
```

### シーンタイプ

#### テキストシーン

```json
{
  "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"
    }
  }
}
```

#### 画像シーン

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

#### 動画シーン

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

#### 複合シーン

```json
{
  "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
    }
  ]
}
```

### 背景設定

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

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

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

### トランジション

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

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

### 音声設定

#### BGM（ファイルから）

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

#### BGM（AI生成）

```json
{
  "audio": {
    "backgroundMusic": {
      "src": {
        "type": "generate",
        "prompt": "穏やかで明るいピアノとストリングスのBGM",
        "duration": 30,
        "seed": 42
      },
      "volume": 0.5,
      "fadeIn": 2,
      "fadeOut": 2
    }
  }
}
```

### ナレーション

各シーンにナレーションを追加できます。音声は自動的にキャッシュされ、同じテキストと設定での再生成を避けます。

```json
{
  "narration": {
    "text": "この動画では新機能を紹介します。",
    "voice": {
      "languageCode": "ja-JP",
      "name": "Kore",
      "speakingRate": 1.0,
      "pitch": 0,
      "volumeGainDb": 0
    },
    "timing": {
      "delay": 0.5,
      "fadeIn": 0.3,
      "fadeOut": 0.3
    }
  }
}
```

## AI支援開発

### Claude CodeやGemini CLIとの連携

```bash
# JSON Schemaを取得
kumiki show-schema --include-examples > schema.json

# AIツールに渡して動画構成を生成
# 例: "30秒の製品紹介動画を作成してください"
```

### スキーマ検証

```bash
# ajvを使用した検証例
kumiki show-schema > schema.json
ajv validate -s schema.json -d my-project.json
```

## 高度な使い方

### プロジェクト設定

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

### AI生成コンテンツ

#### 画像生成

```json
{
  "content": {
    "src": {
      "type": "generate",
      "prompt": "夕日に染まる富士山",
      "style": "photorealistic",
      "aspectRatio": "16:9"
    }
  }
}
```

#### 音楽生成

```json
{
  "audio": {
    "backgroundMusic": {
      "src": {
        "type": "generate",
        "prompt": "エネルギッシュなロック調のBGM",
        "duration": 60,
        "config": {
          "genre": "rock",
          "tempo": "fast",
          "mood": "energetic"
        }
      }
    }
  }
}
```

### キャッシュシステム

Kumikiは生成されたコンテンツ（画像、音楽、ナレーション）を自動的にキャッシュし、同じパラメータでの再生成を避けます。

- **画像キャッシュ**: プロンプト、スタイル、アスペクト比でキャッシュキーを生成
- **音楽キャッシュ**: プロンプト、長さ、設定でキャッシュキーを生成
- **ナレーションキャッシュ**: テキスト、音声設定でキャッシュキーを生成

キャッシュは `.kumiki-cache/` ディレクトリに保存されます。

## 開発

### セットアップ

```bash
# 依存関係のインストール
npm install

# スキーマの生成
npm run generate:schema

# 開発モードで実行
npm run dev

# ビルド
npm run build

# Lint
npm run lint

# 型チェック
npm run typecheck
```

### プロジェクト構造

```
kumiki/
├── src/
│   ├── cli.ts              # CLIエントリーポイント
│   ├── commands/           # CLIコマンド
│   ├── core/              # コア機能
│   ├── scenes/            # シーンレンダラー
│   ├── services/          # 外部サービス連携
│   ├── schemas/           # TypeSpec定義
│   └── utils/             # ユーティリティ
├── examples/              # サンプルプロジェクト
└── internal-docs/         # 内部ドキュメント
```

## トラブルシューティング

### FFmpegが見つからない

```bash
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows
# FFmpeg公式サイトからダウンロードしてPATHに追加
```

### メモリ不足エラー

大きな動画を処理する場合：

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

### キャッシュの問題

```bash
# キャッシュをクリア
kumiki cache clear

# 一時ファイルを確認
kumiki generate project.json --keep-temp
```

## ライセンス

Apache License 2.0

## 貢献

プルリクエストを歓迎します。大きな変更を行う場合は、まずissueを作成して変更内容について議論してください。