屏幕录制配音
为屏幕录制配音的慢工不在于声音本身，而在于同步：将每句话和它所描述的点击动作对齐，并修复句子比动作长的情况。本技能自动完成这两件事，绝不让旁白漂移或重叠。
使用时机
- “为这个演示 / 教程 / 屏幕录制添加配音。”
- “我录了无声屏幕，请旁白”或“我不想用自己的声音/口音。”
- “让旁白匹配屏幕上的操作。”
步骤
-
检查是否设置了
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/中（你可以读取图片），为每步写一句清晰的句子到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 # 烧录字幕 + 背景音乐闪避 -
将打印的 JSON 中的路径提供给用户：
video（已配音的 MP4）、voice_track（供编辑器使用的 WAV）、srt/vtt。如果frozen_seconds大于零，请提一下。 -
要修改某句话，编辑脚本并再次运行步骤 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 行 x 42 个字符）。
- 响度标准化至约 -16 LUFS（YouTube/网络标准）。如有背景音乐，会自动在语音下方闪避。
选项
| 标志 | 默认值 | 作用 |
|---|---|---|
--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密钥错误，402需要在 miragea.ai 充值，429请稍候重试（已缓存的句子不会重复计费）。scenes.py生成的步骤过多或过少 ->--threshold 0.02（更多）/0.08（更少），--min-gap。
参见 examples/ 获取真实脚本、计划 JSON 及其生成的字幕。