视频字幕
一条命令将视频（或音频）文件转换成易于阅读的字幕，并可选择性地生成带字幕的 MP4。原始的语音识别片段经常断词（例如“cen”/“ts”）且时间过长；此技能会重建完整单词并重新排列成合适的提示。
使用时机
- “为这个视频添加字幕/隐藏字幕”、“给我的演讲制作 SRT”、“烧录字幕”。
- “制作 TikTok/Reels/Shorts 风格的字幕” -> 使用
--style shorts --burn。 - 用户需要
.vtt文件用于网站的<track>标签或 YouTube 上传。
步骤
-
检查
MIRAGEA_API_KEY是否已设置（切勿打印出来）。如果缺失，告诉用户在 https://miragea.ai 创建密钥并执行export MIRAGEA_API_KEY=...。 -
在用户的文件上运行脚本：
python3 scripts/captions.py path/to/video.mp4 # -> video.srt + video.vtt python3 scripts/captions.py path/to/video.mp4 --burn # + video.captioned.mp4 python3 scripts/captions.py path/to/short.mp4 --style shorts --burn # 弹出字幕，居中 -
读取它打印的 JSON（
srt、vtt、video、cues），并告知用户文件路径。 -
如果用户希望修改措辞，编辑
.srt文本（保留时间戳）并重新运行--burn： 转录结果已缓存在<file>.transcript.json中，因此重新运行无需额外费用。
选项
| 标志 | 默认值 | 作用 |
|---|---|---|
--style standard | 是 | 每行 42 字符，每提示 1–7 秒（广播约定） |
--style shorts | 每提示 1–3 个单词，大写，烧录时居中 | |
--burn | 关闭 | 写入 <name>.captioned.mp4（H.264，复制原始音频） |
--upper | 关闭 | 大写标准字幕 |
--out-dir DIR | 输入文件所在目录 | 输出文件存放位置 |
--force | 关闭 | 忽略缓存的转录结果并重新转录 |
成本与限制
仅上传 16 kHz 单声道音频轨道（而非视频），每个文件最长 90 分钟 / 1 GB。Miragea 按每秒音频 3 点计费；缓存的重新运行免费。实时费率请查看 GET https://miragea.ai/v1/capabilities。
故障排除
ffmpeg not found-> 安装 ffmpeg（brew install ffmpeg、sudo apt install ffmpeg、winget install ffmpeg）。401-> 密钥错误；402-> 在 miragea.ai 充值；429-> 稍后重试（重试是安全的）。- 音乐较多的片段字幕略微提前/延迟：修剪片头后使用
--force重新运行。
请参阅 examples/ 目录查看示例输出。