diegosouzapw 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, 関数型パターン