Name: yanghhu/ai-voiceover
Author: Community

AI ナレーション生成

voiceover CLI（パッケージ ai-voiceover-studio、Python 3.9以上）を使用してナレーションを生成します。

セットアップ確認

voiceover --version — 未インストールの場合: pip install -e "<repo>[edge]" （[edge] = 無料音声、[yaml] = voices.yaml用）
voiceover doctor --json を実行し、報告された fail をすべて修正します（キーは表示されません）。
エンジン: キーがない場合は無料の edge エンジンが使用されます（インターネット接続が必要、アカウント不要）。 MIRAGEA_API_KEY を設定するとデフォルトが Miragea に変わります（音声クローン、表現力豊かなモデル）。 OPENAI_API_KEY で --provider openai が有効になります。ユーザーにキーをチャットに貼り付けさせたり、エコーしたり、ファイルに書き込んだりしないでください。
MP3出力と動画には ffmpeg が必要です（バーンイン字幕には libass が必要）。

スクリプトを準備（Markdown または TXT）。1行または1段落ごとに話者タグを付けます:
```
[NARRATOR]: 最初のセリフ。
タグなしの行は現在の話者が続けます。

[ALEX](tags=excited, speed=1.1): 別のキャラクター。
[pause 1]
```
見出し、HTMLコメント、コードブロック、テーブルは無視されます。
音声の選択（オプション）。音声ファイルがない場合、各話者にはスクリプトの言語から自動的に独自の音声が割り当てられます。選択するには: voiceover voices --json（Edgeの en-GB-SoniaNeural のような音声を得るには --provider edge --filter en-GB を追加。Miragea の場合は voice_id = アクターID）。2つの音声が同じ名前を共有している場合は、ユーザーにどちらかを尋ねます。Miragea では、音声は公開された参照音声URLとその正確なトランスクリプト（reference_text）にすることもできます。ユーザーが所有しているか使用許可のある音声のみをクローンしてください。

voices.json を書く（ユーザーが音声を選んだ場合。キーは大文字）:

{"NARRATOR": {"actor_id": "en-US-AndrewNeural"}, "ALEX": {"actor_id": "en-US-AvaNeural", "speed": 1.05}}

ドライラン（オフライン、話者とタイミングを検証）: voiceover script script.md -o out/ --dry-run --json
生成: voiceover script script.md [--voices voices.json] -o out/ --json 出力: out/voiceover.mp3、out/voiceover.srt、out/manifest.json、out/segments/
保存されたパスと再生時間を報告します。コマンドが終了コード0で正常終了した場合のみ成功と見なします。

1行: voiceover say "テキスト" [--voice <voice id|https://ref.wav>] [--ref-text "..."] [--lang en] -o line.mp3
フェイスレス動画: voiceover video [--images slides/] --script script.md -o video.mp4 [--style clean|box|bold|minimal] [--size 1080x1920] [--speaker-labels] [--subtitles burn|sidecar|none] デフォルトで字幕はバーンインされます。--images を指定するとセグメントごとに1枚の画像で正確なスライドタイミングが設定され、指定なしではグラデーション背景が使用されます。Shorts用には --size 1080x1920 --style bold を使用します。
音声認識による字幕（Miragea）: --subtitles recognize を追加（API呼び出しが1回増えます）。
タイムアウト後のタスク再開: voiceover task <task_id> --wait -o out.mp3

同じコマンドを再実行しても安全です。変更されていないセグメントはキャッシュから取得され、リモートリクエストでは冪等性キーが使用されます。ユーザーが新しいテイクを希望する場合のみ --fresh を使用してください。
待機中にタイムアウトが発生した場合は、報告された task_id を保持し、voiceover task で再開します。再送信しないでください。
終了コード: 0 = 正常、1 = プロバイダータスク失敗、2 = 使用法/設定/APIエラー。--json の場合、エラーは {"error": {"code", "message", "http_status", "retryable"}, "task_id"?} として出力されます。
401: キー拒否 → ユーザーにキー変数を確認させます。403: アカウントにAPIアクセス権限がありません。429: クォータ/レート制限 → 待機。ループしないでください。400: テキスト/音声/速度/タグを修正します。
proxy_unsupported（edge）: コマンドに VOICEOVER_EDGE_PROXY を設定するか、HTTPS_PROXY を解除します。
対応言語: edge は75言語、Miragea は中国語、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語、ポルトガル語、スペイン語、イタリア語（音声クローン機能あり）をカバーします。