tts は何をしますか？
任意のテキストを音声に変換します。ローカル（Kokoro）とクラウド（Noiz）の2つのバックエンド、シンプルモードとタイムラインモード、そしてセグメントごとの音声制御をサポートしています。
トリガー
- テキスト読み上げ / tts / 話す / 発声
- 音声クローン / 吹き替え
- epubからオーディオ / srtからオーディオ / オーディオに変換
- 语音 / 说 / 讲 / 说话
シンプルモード — テキストから音声へ
speak がデフォルトで、サブコマンドは省略可能です：
# 基本的な使い方（speak は暗黙）
python3 skills/tts/scripts/tts.py -t "Hello world" # -o パスで保存先を指定
python3 skills/tts/scripts/tts.py -f article.txt -o out.mp3
# 音声クローン — ローカルファイルパスまたはURL
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio ./ref.wav
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio https://example.com/my_voice.wav -o clone.wav
# 音声メッセージ形式
python3 skills/tts/scripts/tts.py -t "Hello" --format opus -o voice.opus
python3 skills/tts/scripts/tts.py -t "Hello" --format ogg -o voice.ogg
サードパーティ連携（Feishu/Telegram/Discord）については ref_3rd_party.md を参照してください。
タイムラインモード — SRTから時間合わせした音声へ
セグメントごとの正確なタイミングが必要な場合（吹き替え、字幕、動画ナレーションなど）。
ステップ1：SRTを取得または作成する
ユーザーが持っていない場合は、テキストから生成します：
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt --cps 15 --gap 500
--cps = 1秒あたりの文字数（デフォルト4、中国語に適切；英語は約15）。エージェントが手動でSRTを書くこともできます。
ステップ2：音声マップを作成する
デフォルトとセグメントごとの音声設定を制御するJSONファイル。segments キーは単一インデックス "3" または範囲 "5-8" をサポートします。
Kokoro音声マップ：
{
"default": { "voice": "zf_xiaoni", "lang": "cmn" },
"segments": {
"1": { "voice": "zm_yunxi" },
"5-8": { "voice": "af_sarah", "lang": "en-us", "speed": 0.9 }
}
}
Noiz音声マップ（emo、reference_audio を追加サポート）。reference_audio はローカルパスまたはURL（ユーザー自身の音声；Noizのみ）：
{
"default": { "voice_id": "voice_123", "target_lang": "zh" },
"segments": {
"1": { "voice_id": "voice_host", "emo": { "Joy": 0.6 } },
"2-4": { "reference_audio": "./refs/guest.wav" }
}
}
動的参照音声スライシング：
動画を翻訳または吹き替えする際に、各文が元の動画の同じタイムスタンプの音声を自動的に参照音声として使用するようにしたい場合は、マップ内で reference_audio を設定する代わりに --ref-audio-track 引数を使用します：
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --ref-audio-track original_video.mp4 -o output.wav
完全なサンプルは examples/ を参照してください。
ステップ3：レンダリング
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json -o output.wav
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --backend noiz --auto-emotion -o output.wav
どちらを選ぶべきか
| ニーズ | 推奨 |
|---|---|
| 単にテキストを読み上げるだけ | Kokoro（デフォルト） |
| EPUB/PDFオーディオブック（チャプター付き） | Kokoro（ネイティブサポート） |
音声ブレンド（"v1:60,v2:40"） | Kokoro |
| 参照音声からの音声クローン | Noiz |
感情制御（emoパラメータ） | Noiz |
| セグメントごとの正確なサーバーサイド時間 | Noiz |
ユーザーが感情制御＋音声クローン＋正確な時間を同時に必要とする場合、3つすべてをサポートするバックエンドはNoizだけです。
ゲストモード（APIキー不要）
APIキーが設定されていない場合、tts.py は自動的にゲストモードにフォールバックします。これは認証不要の限定的なNoizエンドポイントです。ゲストモードは --voice-id、--speed、--format のみをサポートし、音声クローン、感情、時間、タイムラインレンダリングは利用できません。
# ゲストモード（APIキー未設定時に自動検出）
python3 skills/tts/scripts/tts.py -t "Hello" --voice-id 883b6b7c -o hello.wav
# 代わりにkokoroを使用するための明示的なバックエンドオーバーライド
python3 skills/tts/scripts/tts.py -t "Hello" --backend kokoro
利用可能なゲスト音声（15種類内蔵）：
| voice_id | 名前 | 言語 | 性別 | トーン |
|---|---|---|---|---|
063a4491 | 販売員（なおみ） | ja | F | 喜び |
4252b9c8 | 落ち着いた女性 | ja | F | 穏やか |
578b4be2 | 熱血漢（たける） | ja | M | 怒り |
a9249ce7 | 安らぎ（みなと） | ja | M | 穏やか |
f00e45a1 | 旅人（かいと） | ja | M | 穏やか |
b4775100 | 悦悦｜社交分享 | zh | F | Joyful |
77e15f2c | 婉青｜情绪抚慰 | zh | F | Calm |
ac09aeb4 | 阿豪｜磁性主持 | zh | M | Calm |
87cb2405 | 建国｜知识科普 | zh | M | Calm |
3b9f1e27 | 小明｜科技达人 | zh | M | Joyful |
95814add | Science Narration | en | M | Calm |
883b6b7c | The Mentor (Alex) | en | M | Joyful |
a845c7de | The Naturalist (Silas) | en | M | Calm |
5a68d66b | The Healer (Serena) | en | F | Calm |
0e4ab6ec | The Mentor (Maya) | en | F | Calm |
セキュリティとデータ開示
このスキルは実行時に以下のファイルおよびネットワーク操作を行います：
- 認証情報の保存：
config --set-api-keyを実行すると、キーは~/.config/noiz/api_key（権限0600）に保存されます。環境変数NOIZ_API_KEYも代替としてサポートされています。 - レガシーキーの移行：
~/.noiz_api_keyが存在し~/.config/noiz/api_keyが存在しない場合、キーは新しい場所にコピー（削除はしない）されます。メッセージが表示され、古いファイルは手動で削除するためにそのまま残されます。 - ネットワーク呼び出し（Noizバックエンド）：テキストとオプションの参照音声は合成のために
https://noiz.ai/v1/にアップロードされます。Noizコマンドを呼び出さない限り、データは送信されません。 - 参照音声のダウンロード：
--ref-audioがURLの場合、ファイルは一時ファイルにダウンロードされ、API呼び出しに使用された後、削除されます。voice-idまたはref-audioが提供されていない場合、デフォルトの参照音声がstorage.googleapis.comまたはnoiz.aiからダウンロードされます。 - 一時ファイル：合成中に一時的な音声/テキストファイルが作成される場合があり、使用後はクリーンアップされます。
- ffmpeg：タイムライン
renderモードで最終音声を組み立てるためにのみ呼び出されます。
出力パスと ~/.config/noiz/ 以外のファイルは変更されません。Kokoroバックエンドは完全にオフラインで動作し、ネットワークアクセスはありません。
要件
ffmpegがPATHに含まれていること（タイムラインモードのみ）requestsパッケージ：uv pip install requests（Noizバックエンドに必要）- APIキーは Noiz Developer で取得し、
python3 skills/tts/scripts/tts.py config --set-api-key YOUR_KEYを実行してください（ゲストモードはキーなしでも動作しますが、機能は制限されます） - Kokoro：すでにインストールされている場合は、
--backend kokoroを渡してローカルバックエンドを使用します
Noiz API認証
Authorization としてbase64エンコードされたAPIキーのみを使用してください。プレフィックスは付けません（例：APIKEY や Bearer は不要）。プレフィックスがあると401エラーになります。
バックエンドの詳細と完全な引数リファレンスについては、reference.md を参照してください。