画面収録ボイスオーバー は何をしますか？
画面収録にナレーションを付ける際の面倒な部分は、声そのものではなく「同期」です。各文章を、それが説明するクリックに合わせて並べ、文章がアクションよりも長い箇所を修正する作業。このスキルはその両方を自動で行い、ナレーションのずれや重なりを決して発生させません。
使用するタイミング
- 「このデモ／チュートリアル／画面収録にボイスオーバーを追加して」
- 「画面をサイレントで録画したので、ナレーションをつけて」または「自分の声／アクセントは使いたくない」
- 「ナレーションを画面上の操作に合わせて」
手順
-
MIRAGEA_API_KEYが設定されていることを確認する（絶対に表示しない）。音声：ユーザーに Miragea の音声 ID を一度尋ねるか、または自分の音声クリップの公開 URL とその正確なテキストを尋ねる。export MIRAGEA_VOICE_ID=...を提案し、二度と尋ねられないようにする。ユーザーが所有するか、使用許可のある音声のみをクローンする。 -
ステップを見つけて台本テンプレートを作成する：
python3 scripts/scenes.py demo.mp4 # -> demo.frames/*.jpg, demo.frames/steps.json, demo.script.txt -
フレームを見る（画像を読める）
demo.frames/内のフレームを確認し、各ステップに対して1つの明確な文章をdemo.script.txt内の各タイムスタンプの後、# stepコメントを置き換えて記述する。~N wordsのヒントに収まるようにし、そのラインが次のステップの前に収まるようにする。ステップのマージ、移動、削除は自由に行う。ユーザーが独自の台本を提供した場合は、その文章を一致するタイムスタンプに配置する。 -
費用をかけずにタイミングを確認する：
python3 scripts/voiceover.py demo.mp4 demo.script.txt --dry-runユーザーがフリーズフレームをゼロにしたい場合は、
will freezeとマークされたラインを短くする。 -
レンダリング：
python3 scripts/voiceover.py demo.mp4 demo.script.txt --voice VOICE_ID # 字幕はファイルとして python3 scripts/voiceover.py demo.mp4 demo.script.txt --burn --music bed.mp3 # 字幕焼き込み＋BGM（自動ダッキング） -
ユーザーに出力されたJSONからパスを伝える：
video（ナレーション付きMP4）、voice_track（WAV、編集者用）、srt/vtt。frozen_secondsが0より大きい場合はその旨を伝える。 -
ラインを変更するには、台本を編集して手順5を再度実行する：変更されていないラインはキャッシュから無料で提供される。
台本フォーマット
[00:00] Acmeへようこそ。サインイン後に表示されるダッシュボードです。
[00:04] 「新しいプロジェクト」をクリックし、名前を入力して、それを所有するチームを選びます。
[01:02.5] 以上です。プロジェクトの準備が整いました。
許容されるタイムスタンプ: [mm:ss], [h:mm:ss], mm:ss.s, 12.5s。# で始まる行はコメントです。
同期の仕組み
- 各ラインはそのタイムスタンプで正確に開始されます。次のステップの前に0.25秒の余裕が確保されます。
- スロットより長いラインは、最大
--max-speed（デフォルト1.15倍、自然な速度）まで速度が上げられます。 - それでも収まらない場合、ビデオはそのステップの最終フレームを保持し、文章が終了したら再開します。後続のラインは同じ量だけシフトされるため、同期が失われることはありません。
- 字幕は各ラインの実際の発話長に基づいてタイミングが調整されます（最大2行×42文字）。
- ラウドネスは約-16 LUFS（YouTube/Web標準）に正規化されます。音楽が指定された場合、音声の下に自動的にダッキングされます。
オプション
| フラグ | デフォルト | 説明 |
|---|---|---|
--voice ID / --ref-url URL --ref-text TEXT | 環境変数 | 保存済みMiragea音声、または公開クリップからクローン（正確なテキスト＝安い1倍料金） |
--model | expressive | または standard |
--max-speed | 1.15 | フレームフリーズ前の最大速度倍率 |
--burn | オフ | 字幕を動画に焼き込む |
--music FILE | なし | 背景音楽、ループ再生・自動ダッキング |
--keep-audio | オフ | 録画の元の音声を小さく保持する |
--dry-run | スロット計画を推定発話速度で表示（API呼び出しなし） | |
-o FILE | VIDEO.voiceover.mp4 | 出力パス（元のファイルは変更されない） |
コストと制限
音声合成はMirageaにより文字単位で課金されます（保存済み音声または正確な参照テキストの場合は1倍、最新料金は GET https://miragea.ai/v1/capabilities）。3分のデモは通常2,000～3,000文字です。各ラインは2,000文字未満である必要があります。参照クリップは、Mirageaのアップロードエンドポイントがリリースされるまで公開URLである必要があります。
トラブルシューティング
no timestamp/not after the previous line-> エラーで指定された台本のラインを修正する。no voice chosen->--voiceを渡すかMIRAGEA_VOICE_IDを設定する。401キーが間違っている,402miragea.aiでチャージする,429待ってから再実行する（キャッシュされたラインは再課金されない）。scenes.pyのステップ数が多すぎる／少なすぎる ->--threshold 0.02（増やす） /0.08（減らす）、--min-gap。
実際の台本、計画JSON、生成された字幕については examples/ を参照してください。