Cartesia Download CLI - Architecture Reference

Overview

テキストから Cartesia TTS API で音声を生成する CLI ツール。Claude LLM による感情アノテーション付き。

Package Structure

apps/cli/src/
├── cli.ts                    # gunshi エントリポイント
├── types.ts                  # RawCliArgs, RcConfig, AppError
├── commands/
│   └── download.ts           # download コマンド実装
└── core/
    ├── config.ts             # 設定解決 (args → env → rc → defaults)
    ├── io.ts                 # ファイル I/O 抽象化 (neverthrow)
    └── format-error.ts       # ユーザー向けエラーメッセージ

packages/core/src/
├── types.ts                  # TtsConfig, TtsClient, TextAnnotator
├── pipeline.ts               # TTS ストリーミングパイプライン
├── tts-client.ts             # Cartesia API ラッパー
├── annotator.ts              # アノテーターファクトリ
├── marker-parser.ts          # [SEP] マーカーパーサー
├── wav.ts                    # WAV ヘッダービルダー
└── providers/
    └── claude-annotator.ts   # Claude 感情アノテーション

Command: download

cartesia-download [flags]

| Flag | Short | Default | Description | | -------------------- | ----- | -------------------------- | ------------------------ | | --text | -t | — | 読み上げテキスト | | --input | -i | — | テキストファイルパス | | --voice-id | | — | Cartesia Voice ID (必須) | | --output | -o | — | WAV 出力パス | | --model | -m | sonic-3 | TTS モデル ID | | --sample-rate | | 44100 | サンプルレート (Hz) | | --provider | | claude | LLM プロバイダー | | --provider-model | | claude-sonnet-4-20250514 | LLM モデル | | --provider-api-key | | — | LLM API キー | | --no-annotate | | false | 感情アノテーション無効化 |

Data Flow

テキスト入力 (--text / --input ファイル)
    ↓
設定解決 (CLI args > env vars > .cartesiarc.json > defaults)
    ↓
[感情アノテーション] Claude が SSML タグ + [SEP] マーカーを挿入
    ↓
チャンクごとに Cartesia TTS API → PCM ストリーム → stdout
    ↓
[--output 指定時] WAV ファイル + アノテーション済みテキスト (.txt) 保存

Emotion Annotation

Claude が以下の SSML タグをテキストに挿入する:

<emotion value="happy|sad|angry|excited|..."/> — 感情
<speed ratio="0.5-1.0"/> — 速度 (1.0 以下)
<volume ratio="0.5-2.0"/> — 音量

使用可能な感情値: neutral, angry, excited, content, sad, scared, happy, curious, sarcastic, hesitant, confident, calm, surprised

[SEP] マーカーでチャンク分割し、チャンクごとに TTS API を呼ぶことでリアルタイムストリーミングを実現。

Config Resolution Priority

CLI args (最優先)
環境変数 (CARTESIA_API_KEY, CARTESIA_VOICE_ID, ANTHROPIC_API_KEY)
RC ファイル (.cartesiarc.json — ディレクトリを上方探索)
デフォルト値 (model: sonic-3, sampleRate: 44100)

Error Types

| Error | Cause | | --------------------- | --------------------------- | | MissingApiKey | CARTESIA_API_KEY 未設定 | | MissingVoiceId | Voice ID 未指定 | | MissingText | --text も --input も未指定 | | FileReadError | 入力ファイル読み取り失敗 | | FileWriteError | 出力ファイル書き込み失敗 | | TtsApiError | Cartesia API エラー | | AnnotationError | Claude API エラー | | UnsupportedProvider | "claude" 以外のプロバイダー |

Key Design Patterns

neverthrow: 全ての I/O は ResultAsync でエラーハンドリング
DI: io, ttsClient, annotator は外部注入 (テスタビリティ)
Streaming: PCM チャンクを逐次 stdout に書き出し、リアルタイム再生可能
Immutable: const only, 関数型パターン