happy-audio-gen

happy-audio-gen

1 つの CLI で 6 つのプロバイダーを通じてテキストを音声に変換します。Bailian のボイスデザインフローは処理に長いポーリング時間を使用しますが、対象に含まれています。それ以外のプロバイダーはすべて同期型です（TTS は高速で、通常 10 秒未満です）。

クイック使用方法

# Shortest path — OpenAI default voice
bun scripts/main.ts --text "Hello, world" --out ./hello.mp3

# Chinese, MiniMax
bun scripts/main.ts --provider minimax --text "大家好" --voice male-qn-qingse --out ./hello.mp3

# Long-form, Bailian (auto-splits by sentence)
bun scripts/main.ts --provider bailian --textfiles ./script.md --out ./narration.mp3

このスキルを呼び出すタイミング

• ユーザーが音声の合成、TTS、読み上げ、ナレーション、吹き替え、またはボイスオーバーの作成を求めた場合。
• ユーザーが台本、テキスト、記事を音声に変換するよう求めた場合。
• ユーザーが TTS の音声またはモデルを指定した場合。

ユーザーが音声をテキストに文字起こしすることを希望する場合（これは STT で、別の分野です）、または音声ファイルの編集・ミキシングを希望する場合（専用の音声編集ツールを使用します）は、ここに振り分けないでください。

ステップ 0：事前確認（必須）

1. EXTEND.md の場所を確認します：

   • ./.happy-skills/happy-audio-gen/EXTEND.md
   • $XDG_CONFIG_HOME/happy-skills/happy-audio-gen/EXTEND.md
   • ~/.happy-skills/happy-audio-gen/EXTEND.md

   見つからない場合は、bun scripts/main.ts --setup を実行し、references/config/first-time-setup.md に沿ってユーザーを案内します。

2. 少なくとも 1 つのプロバイダーに認証情報があることを確認します（環境変数または 1Password の参照）。

3. Bun が利用可能であることを確認します。利用できない場合は、npx -y bun を使用します。

ステップ 1：プロバイダーを選択

優先順位：

1. --provider <id>
2. EXTEND.md の default_provider
3. 環境変数から自動検出：openai > elevenlabs > bailian > minimax > siliconflow > playht

言語や音声の意図に応じて選択します：

• 英語、自然で高速 → openai（gpt-4o-mini-tts / tts-1）。
• 多言語、音声クローン → elevenlabs。
• 中国語、長文 → bailian（qwen-tts は長い台本を自動で分割します）または minimax。
• 中国語の方言／ボイスデザイン → bailian（qwen3-tts-vd によるボイスデザイン）または siliconflow（CosyVoice2）。
• 超リアル、短文 → playht（2.0）。

ステップ 2：パラメーターを設定

• --text または --textfiles：入力。必ず引用符で囲みます。
• --out <path>：必須。拡張子によって形式が決まります（.mp3 / .wav / .ogg / .flac）。
• --voice <id>：プロバイダー固有です。よく知られた音声の一覧は references/voices.md を参照してください。
• --rate 0.5..2.0：話速。
• --instruction "..."：音声の指示（openai の gpt-4o-mini-tts と siliconflow のみが対応します）。
• --language <code>：en、zh、ja。明示的に対応しているプロバイダーは一部のみです。

ステップ 3：実行

bun scripts/main.ts \
  --provider openai \
  --model gpt-4o-mini-tts \
  --voice alloy \
  --text "..." \
  --out ./out.mp3

JSON モード：

{ "success": true, "provider": "openai", "model": "gpt-4o-mini-tts", "voice": "alloy", "output": "/abs/out.mp3", "size_bytes": 76032, "format": "mp3" }

ステップ 4：長文の処理

• happy-audio-gen は、1 回の呼び出しで処理できる長さに上限があるプロバイダー（Bailian は 1 回あたり中国語 200 文字以下）向けに、長い入力を自動で分割します。出力時にチャンクをバイト単位でそのまま連結します。
• MP3 を連結する際に最高の忠実度を得るには、バイト連結に頼らず、後から ffmpeg で各セグメントを結合してください。

ステップ 5：エラー

• [openai] OpenAI TTS 400 と invalid voice が表示される → 音声名がモデルでサポートされていません。alloy、ash、coral、echo、fable、onyx、nova、sage、shimmer のいずれかを使用してください。
• [minimax] ... 2049 invalid api key が表示される → MINIMAX_BASE_URL=https://api.minimaxi.com/v1 を試してください（リージョンが異なります）。
• [bailian] ... 400 DataInspectionFailed が表示される → Aliyun のコンテンツフィルターによるエラーです。ユーザーに伝えてください。
• [elevenlabs] 401 が表示される → キーが無効か、サブスクリプションの期限が切れています。

参考資料

• references/providers.md — プロバイダーごとの環境変数、デフォルトモデル、音声一覧。
• references/voices.md — 各プロバイダーの厳選された音声。
• references/error_codes.md — よくあるエラーとその解決方法。
• references/config/first-time-setup.md
• references/config/extend-schema.md
• assets/EXTEND.template.md