yanghhu/miragea-video-voiceover

AI配音

「AI配音」は、動画の文字原稿からワンクリックでマルチキャラクターナレーション（WAV）とタイムコード付き SRT 字幕を生成する Agent スキルです。音声はアカウント内の既存キャラクター、または参照音声からの音声クローンを使用。口播き、映画解説、小説プロモーション、販売促進、広告、オーディオブックに対応し、ローカル環境に GPU は不要です。

一言で言うと

AI配音 = [キャラクター] タグ付きの文字原稿 → ナレーション全体 voiceover.wav + タイムコード付き字幕 voiceover.srt + 各行の開始・終了時間 manifest.json を 1 コマンドで生成。各発話は Miragea 公開 API が生成し、ローカルは Python 3.9+ 標準ライブラリのみ、GPU もサードパーティパッケージのインストールも不要です。

対象ユーザーとユースケース

シナリオ	典型的なニーズ	推奨プリセット
口播き / 知識系ブロガー	自分のクローン音声で毎日口播き、縦画面字幕	--preset koubo
映画 / ドラマ解説	ナレーション＋キャラクター台詞のマルチ音声、タイムラインに合わせる	--preset jieshuo
小説プロモーション / オーディオブック	マルチキャラクター朗読、段落間のポーズ、キャラクター名付き字幕	--preset youshengshu
販売促進動画	テンポの良い売り文句ナレーション、大きめ字幕、複数バージョンテスト	--preset daihuo
デジタルヒューマン / AI 分身	クリーンな声音駆動音声＋発話ごとのタイムライン	--preset shuziren
広告 / プロモーション動画	余白、正確なポーズ、固定ブランド音声	--preset guanggao
既存動画への字幕追加	音声 / 動画からタイムスタンプ付き SRT を認識	miragea_audio.py recognize

同シリーズには、シナリオ別の詳細な原稿作成方法を解説するスキルもあります：口播きナレーション、映画解説ナレーション、小説プロモーションナレーション、テキスト音声変換、音声クローン、字幕生成。

コア機能パラメータ

項目	説明
出力ファイル	voiceover.wav（ナレーション全体）、voiceover.srt（タイムコード付き字幕）、manifest.json（各行の話者・テキスト・開始終了秒数）、lines/（各行の音声、原稿修正時に再利用）
音声ソース	アカウント内の既存キャラクター actor_id=（actors で確認）、またはサーバーから直接アクセス可能な参照音声 URL ref= ＋参照音声内の実際の発話 ref_text=（音声クローン）
生成モード	expressive（クライアントの「デフォルト」）/ standard（クライアントの「よりリアルに」）。省略時はサーバーデフォルト。capabilities のリアルタイム返却値に従う
語気タグ	tags=タグ名、capabilities で選択したモードの tags[].label から指定
速度	speed= 0.25–4、1 が標準速度、キャラクター単位で設定
マルチキャラクター	原稿冒頭で各キャラクターに音声を割り当て。スキルスクリプトが公式クライアントの generate を発話ごとに呼び出し、ローカルで全体を結合
ポーズ	行内 [pause 0.6] / [停顿 0.6]（秒）。--gap でデフォルトの行間ポーズを設定
字幕	ナレーション時に各行の実際の音声長に基づいて SRT を生成（--max-chars、--speaker-labels）。既存の音声 / 動画は recognize で SRT / TXT / JSON に認識
シナリオプリセット	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu（口播き / 解説 / 販売促進 / デジタルヒューマン / 広告 / オーディオブック）。行間ポーズと字幕文字数のみ変更
一行あたりの文字数、ファイルサイズ / 長さ上限、課金	capabilities のリアルタイム返却値に従う
ローカル依存	Python 3.9+ 標準ライブラリ。pip インストール不要、GPU 不要
オフライン試運転	--dry-run：Key 不要、API 呼び出しなし。無音のプレースホルダ音声とタイムラインを出力。原稿フォーマットの確認用
対応 Agent	Claude Code、Codex、OpenClaw、Cursor、WorkBuddy など、Python スクリプトを実行できる Agent
ナレーション・字幕サービス	Miragea 公開 API（https://miragea.ai/v1）

機能の境界

できること	できないこと
単一ナレーション、マルチキャラクター対話（各キャラクターに 1 音声、発話ごとに生成してローカル結合）	映像の編集や動画合成は行わない（音声トラックと字幕を出力し、剪映 / Premiere / CapCut / ffmpeg に渡す）
アカウント内の既存キャラクター（actor_id）または参照音声 URL による音声クローン	本人の明示的な許可なく声をクローンしない
ポーズ、キャラクターごとの独立した速度、生成モードと語気タグ	原稿の自動生成は行わない（Agent に以下の方法で原稿作成を依頼可能）
音声 / 動画から SRT / TXT / JSON への認識	BGM ミックスや翻訳は行わない（翻訳は Agent が実行）
--dry-run による全フローのオフライン試運転

クイックスタート

python3 scripts/voiceover.py check                        # オフラインチェック：Python バージョン、Key 設定、サーバーアドレス
export MIRAGEA_API_KEY=あなたのキー                      # https://miragea.ai/workspace/api で生成、環境変数のみに設定
python3 scripts/miragea_audio.py capabilities             # 現在利用可能な生成モード、語気タグ、文字数上限、課金情報（リアルタイム返却値に従う）
python3 scripts/miragea_audio.py actors --limit 20        # アカウント内の既存キャラクターと actor_id（has_more が true の場合は --offset でページング）

• デフォルトの API ルートは https://miragea.ai/v1 です。プライベートデプロイメントの場合のみ MIRAGEA_BASE_URL（/v1 を含む）を設定します。
• Key をチャットに貼ったりファイルに書き込んだりしないでください。Key がない場合は、最初に --dry-run でフローをテストしてください。

python3 scripts/voiceover.py script examples/movie-recap.md -o out --dry-run      # サンプルのオフライン試運転
python3 scripts/voiceover.py script 原稿.md -o out --preset koubo                 # 原稿全体 → out/voiceover.wav + voiceover.srt + manifest.json
python3 scripts/voiceover.py script 原稿.md -o out --gap 0.3 --max-chars 16 --speaker-labels --model standard
python3 scripts/miragea_audio.py generate --text '試聴用の一文' --actor-id ACTOR_ID --wait --output test1.mp3
python3 scripts/miragea_audio.py recognize --file 完成品.mp4 --wait --output 完成品.srt

• --gap：行間ポーズの秒数（デフォルト 0.25）。--max-chars：字幕一行あたりの最大文字数（デフォルト 18、縦画面は 12–16 推奨、英語は 40 推奨）。
• --preset で行間ポーズと字幕文字数を一度に設定できます。個別に --gap / --max-chars で上書きも可能。

あなたの発言 → Agent の実行

あなたの発言	Agent の実行
“この口播き原稿を音声にして”	原稿.md を書き込み（単一キャラクター）→ script 原稿.md -o out --preset koubo
“映画解説のナレーション、ナレーターと 2 キャラクターで”	front matter で narrator / キャラクターの音声を定義 → script ... --preset jieshuo
“自分の声でナレーションして”	actors で自分のクローンキャラクターの actor_id を検索。またはサーバーからアクセス可能な参照音声 URL とその中の発話を指定 → ref= + ref_text=
“もっと嬉しそうな口調で”	capabilities で選択したモードのタグを確認 → キャラクターに tags=タグ名 を追加
“一文だけ試聴したい”	miragea_audio.py generate --text "..." --actor-id ID --wait --output test1.mp3
“5 行目が間違ってる”	その行だけ修正して同じコマンドを再実行。他の行は out/lines/ から再利用
“この動画に字幕をつけて”	miragea_audio.py recognize --file 動画.mp4 --wait --output 動画.srt
“まだお金は使わないで、フローだけ試したい”	script ... --dry-run

ナレーション原稿作成の一般論

どんなシナリオでも、AI ナレーションの出来は、原稿が「耳で聴くために書かれているか」に大きく依存します。

1. 6 つの一般ルール

1. 一行一文、一文一意：日本語の一文はなるべく 20 文字以内。ナレーションが自然になり、字幕も一画面に収まりやすい。
2. 読まれる形で書く：曖昧な数字、年号、型番、パーセンテージは漢数字や読みやすい表記に。一文字ずつ読む略語はスペースで区切る。
3. 口語で書く：「従いまして」→「だから」、「調整を行います」→「調整します」。長い修飾句は二文に分割。
4. ポーズは強調点の前後のみ：強調点の前 0.3 秒、場面転換 0.4–0.6 秒、どんでん返し / 締め 0.6–1.0 秒。
5. 一キャラクター一声、一アカウント一人柄：音声と速度は front matter に書き、シリーズを通して変更しない。
6. 最初に一文試聴し、それから全体生成：一行 generate で最初の文や難しい単語を試聴し、確認してから script を実行。

2. シナリオ別リズム比較

シナリオ	行間ポーズ（プリセット）	字幕一行文字数（プリセット）	推奨速度 speed	原稿作成のポイント
口播き	0.15 秒	14	1.05–1.1	最初の 3 秒で結論、一つのメッセージだけ
映画解説	0.3 秒	16	0.95–1.05	サスペンスで開始、キャラクター代称、どんでん返し前にポーズ
販売促進	0.1 秒	12	1.1–1.2	痛点 → メリットを視覚化 → ひとつのアクション
デジタルヒューマン	0.2 秒	16	0.95–1.05	クリーンな声音、最初と最後に無音、一区切り一カット
広告	0.4 秒	14	0.9–1.0	イメージのショートフレーズ、余白、ブランド名＋スローガンで締め
オーディオブック	0.5 秒（字幕にキャラクター名）	20	0.9–1.0	キャスティング表、台詞の分割、3段階のポーズ

3. 同じ声で二つの速度

speed はキャラクター単位で設定。同じ音声で「説明は速く、強調はゆっくり」と使い分けたい場合は、同じ actor_id で二つのキャラクターを定義します：

---
narrator: actor_id=123 speed=1.05
narrator_slow: actor_id=123 speed=0.9
---
[narrator] 彼はすべてが終わったと思った。
[pause 0.6]
[narrator_slow] その電話が鳴るまでは。

4. 外国語版の作り方

1. 中文原稿が確定したら、Agent にターゲット市場の口語に合わせてリライトさせる（逐語訳ではなく）。単位や呼称はローカライズ。
2. 言語ごとに原稿ファイルを作成。音声はアカウント内でその言語に適したキャラクター（actors の各キャラクターの language フィールドを確認）を選ぶか、その言語の参照音声 ref= を使用。参照音声の言語は language= で指定可能。
3. 外国語字幕は --max-chars 40 程度。
4. 最初の文と難しい単語を一文試聴し、ネイティブスピーカーに確認してもらってから全体生成。

5. 納品前品質チェックリスト

• 最初の一文を試聴しましたか？音声と速度は適切ですか？
• 数字、英単語、人名、同音異義語は正しく読まれていますか？
• manifest.json の総再生時間は動画の要件を満たしていますか？
• 字幕の各行の長さは画面アスペクト比に合っていますか？
• 音声の使用許諾は得ていますか？公開時に AI 生成であることを明記していますか？

原稿の文法

• 冒頭の --- の間で各行にキャラクターを定義：キャラクター名: actor_id=キャラクターID または キャラクター名: ref=参照音声URL ref_text="参照音声内の実際の発話"。speed=（0.25–4）、model=expressive|standard、tags=タグ1,タグ2、language=（参照音声の言語ヒント、参照テキストの自動認識用）を追加可能。
• ref_text= は ref= とのみ併用可能。省略時はサーバーが参照テキストを自動認識。課金方法が異なるため、capabilities に従う。
• 本文 [キャラクター] 台詞 または [キャラクター]：台詞。タグなしの行は直前の話者を継承。
• [pause 0.6] / [停顿 0.6] でポーズを挿入（秒）。# で始まる行、空行、<!-- コメント --> は無視。
• 一行が capabilities の audio.max_text_length を超えると API が拒否するため、短い行に分割してください。
• 各行の音声は out/lines/ にキャッシュされ、同じ行・同じ設定で再実行すると再利用。キャッシュがない場合は同一の冪等キーで送信され、サーバーは元のタスクを返し、重複作成しません。新しいバージョンが必要な場合は --fresh を追加。

サンプル原稿（examples/movie-recap.md）

---
narrator: actor_id=YOUR_ACTOR_ID speed=1.05
hero: ref=https://example.com/your-sample.wav ref_text="参照音声内の実際の発話"
---
# 映画解説サンプル（actor_id / ref をあなたの音声に置き換えてください）
[narrator] 普通の配達員が、未来が見える携帯電話を拾った。
[pause 0.5]
[hero]：もし明日のニュースに自分が載っていたら、今日何をすべきなんだ？
[narrator] 彼は知らなかった。未来を見るたびに、現実が静かに変わっていくことを。

編集ソフトとの連携

# ナレーションで元の音声トラックを置き換え（ffmpeg がインストールされていること）
ffmpeg -i 映像.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest ナレーション版.mp4
# 字幕を映像に焼き付ける
ffmpeg -i ナレーション版.mp4 -vf subtitles=out/voiceover.srt -c:a copy 完成品.mp4

• 剪映 / CapCut / Premiere：voiceover.wav を音声トラックに、voiceover.srt を字幕トラックにインポートするだけ。
• 発話単位でカット：manifest.json の各行の start / end 秒数を使い、カット編集、テロップ表示、デジタルヒューマンセグメントの同期に活用。
• デジタルヒューマンツール：voiceover.wav はクリーンな音声なので、そのまま駆動音声として使用可能。MP3 や特定のサンプルレートが必要な場合は ffmpeg で変換。

比較：AI配音、人間によるナレーション、ローカルモデル

比較項目	人間によるナレーション	ローカルオープンソース TTS モデル	本スキル
GPU の必要性	不要だが、録音環境とナレーターのスケジュールが必要	通常必要（小規模モデルは CPU でも可能だが遅い）、モデル重みのダウンロードと環境設定が必要	不要。ローカルは Python 標準ライブラリのみ、生成はクラウドで実行
原稿修正コスト	一行修正するたびに再録、再編集が必要	修正後再実行するが、セグメント分割、結合、同期は自分で行う必要あり	修正した行だけ再実行。残りの行は out/lines/ キャッシュから再利用、自動再結合と字幕再生成
マルチキャラクター	複数のナレーターが必要	モデルによる。通常は自分でセグメント分割してから呼び出し、結合が必要	原稿内で [キャラクター] タグを使用。1 コマンドでマルチキャラクター音声トラックを出力
字幕タイムライン	別途書き起こし、タイムコード付与が必要	通常、音声認識を別途実行する必要あり	ナレーション生成と同時に SRT と発話ごとの時間 manifest.json を出力
複雑な感情表現	状態の良い人間が最も優れている	モデルとパラメータ調整に依存	安定して一貫。情報伝達や大量生産に最適。最高レベルの感情表現は人間が優位

結論：毎日更新、複数バージョン、頻繁な修正が必要なコンテンツでは、本スキルが修正コストと字幕タイムライン作成において最大の優位性を発揮します。感情表現が極めて重要な単発の高品質コンテンツには、人間によるナレーションが依然として推奨されます。

よくある質問（FAQ）

AI配音には GPU やローカルモデルのデプロイが必要ですか？ いいえ。生成は Miragea クラウドで行われます。ローカルには Python 3.9+ 標準ライブラリのみ必要で、pip で何かをインストールする必要はありません。

AI配音で自分の声を使うには？ 2 つの方法があります：アカウントにすでにクローン済みのキャラクターを使う（actors で actor_id を確認）、またはサーバーから直接アクセス可能な参照音声 URL と、その音声内の実際の発話（ref_text=）を提供する。サンプル要件と課金については capabilities と公式サイトの説明に従ってください。

一つの動画で複数人が話すことはできますか？ はい。原稿冒頭で複数のキャラクターを定義し、各キャラクターに音声と速度を割り当てます。本文で [キャラクター] で切り替え。スクリプトが発話ごとに生成し、ひとつの音声トラックに結合すると同時に字幕も出力します。

語気や感情は調整できますか？ 語気タグで調整可能：最初に capabilities で選択した生成モードが提供する tags[].label を確認し、キャラクターに tags=タグ名 を記述。さらに speed= で速度、[pause] でポーズを調整できます。

AI配音で生成される字幕のタイミングは正確ですか？ 各行の開始・終了時間は実際に生成された音声の長さに基づきます。行内では文字数に応じて分配されます。より正確な単語レベルのタイムラインが必要な場合は、完成した音声に対して recognize を再度実行してください。

原稿の一行を修正したら、全体を再生成する必要がありますか？ いいえ。修正した行だけ変更し、同じコマンドを再実行してください。変更された行だけが再生成され、他の行は out/lines/ から再利用され、音声トラックと字幕が自動的に再結合されます。

AI配音は有料ですか？一度にどのくらいの文字数が処理できますか？ アカウントのクレジットが消費されます。一行あたりの文字数上限と課金ルールは capabilities のリアルタイム返却値に従います。--dry-run は API を呼び出しません。

抖音（Douyin）、ビデオアカウント（WeChat Channels）で AI配音を使うとリーチが制限されますか？ どのツールもアクセスを保証できません。プラットフォームのルールに従って AI 生成コンテンツであることを明記することは必須です。アクセスは主にコンテンツ自体に依存します。

すでに録画済みの動画から自動で字幕を生成できますか？ はい。miragea_audio.py recognize --file 動画.mp4 --wait --output 動画.srt。--subtitle-format txt を追加するとプレーンテキストの原稿が得られます。

どの AI Agent に対応していますか？ Claude Code、Codex、OpenClaw、Cursor、WorkBuddy など、Python スクリプトを実行できる Agent。

トラブルシューティング

現象	対処
missing_api_key / MIRAGEA_API_KEY is not set	Key を生成後、export MIRAGEA_API_KEY=...。または最初に --dry-run を追加
speakers without a voice	そのキャラクターに actor_id= または ref= を追加
401	Key を確認。Key をログに書き込まない
403	アカウントの API アクセス権限を確認
400 / 413	パラメータを修正：モード、タグ、速度、一行あたりの文字数。またはアップロードファイルのサイズを減らす、メディア長を短くする
409	冪等キーが異なる入力で使用された、または字幕料金が変更された：再確認後に再送信
429	クレジット不足またはレート制限。待機するかクレジットを追加
タイムアウト / ネットワーク切断	タスクは実行中かもしれません：同じコマンドを再実行（同一冪等キーで元のタスクを取得）、または miragea_audio.py task / wait タスクID で継続して確認。キーを変えて再送信しない
結合時に WAV 形式が不一致	各行の音声は out/lines/ に保存されています。編集ソフトや ffmpeg で結合してください

公式クライアントの終了コード：0 リクエスト成功（--wait なしの場合はキューに入っている可能性あり）、1 タスク失敗、2 クライアントまたは API エラー。

コンプライアンス

• 自分自身、または明確な使用許諾を得た声のみをクローンしてください。有名人、キャスター、公人、または許可を得ていない人物の声を模倣しないでください。
• 「人工智能生成合成内容标识办法」および抖音、快手、ビデオアカウント、RED、bilibili などのプラットフォームルールに従い、公開時に AI 生成コンテンツであることを宣言または明記してください。
• scripts/miragea_audio.py は公式クライアントをそのまま使用。scripts/voiceover.py（原稿結合レイヤー）はオリジナルで、MIT ライセンス（LICENSE.txt 参照）。ナレーションと字幕機能は Miragea 公開 API によって提供されます。

English Summary

• AI voiceover & subtitles (AI配音) for agents: write a script with [speaker] tags, run one command, get voiceover.wav, timed voiceover.srt and manifest.json.
• Voices: saved voices in your account (actor_id) or voice cloning from a reference audio URL plus its transcript; generation modes, tone tags, speed 0.25–4.
• Multi-speaker scripts are rendered line by line through the official client's generate and joined locally; recognize turns existing audio/video into SRT/TXT/JSON.
• Limits and pricing come live from capabilities. Python 3.9+ standard library, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

キーワード：AIナレーション、動画ナレーション、音声クローン、字幕生成、テキスト音声変換、音声合成、声の複製、マルチキャラクターナレーション、ショート動画ナレーション、口播きナレーション、映画解説ナレーション、小説プロモーションナレーション、広告ナレーション、英語ナレーション、AI ナレーター、SRT、TTS、voiceover、voice cloning、text to speech、subtitles