用途
为视频添加字幕（captions/subtitles）。当用户需要为视频配字幕时使用，可用于上传平台、再编辑，或直接把字幕烧进画面。
两种输出，同一个转写引擎
转写引擎为 mlx-whisper（与 transcribe 相同）。输出形式有两种：
- 侧车文件（.srt / .vtt）：用于 YouTube/Vimeo 上传、再编辑或其它工具。
- 烧录（Burned-in）：把像素烘焙进视频画面，适用于播放器不显示字幕轨的场景（如社交短片）。烧录通过 PIL → ffmpeg overlay 渲染（mise ffmpeg 缺少 drawtext）。
关键：为字幕转写时使用 --clean
这与去除填充词（filler-removal）相反。Whisper 在此默认逐字保留（保留 um/uh），因为填充词去除需要它们。字幕不需要，观众不想在屏幕上看到 “um, uh”。为字幕转写时始终传入 --clean：
uv run video-agent transcribe video.mp4 --clean --srt -o subs.srt
导出字幕文件（不烧录）
uv run video-agent transcribe video.mp4 --clean --srt -o subs.srt # SubRip
uv run video-agent transcribe video.mp4 --clean --vtt -o subs.vtt # WebVTT
可将 subs.srt 与视频一起上传，或手工编辑（修正人名/错别字、调整时间）后再烧录该编辑后的文件（见下）。
把字幕烧录进视频
# 自动转写并一步烧录（内部是否使用 --clean 转写？否——需自行传入）
uv run video-agent captions video.mp4 -o captioned.mp4 --clean
# 精度最佳的工作流：转写 → 手工编辑 .srt → 烧录编辑后的文件
uv run video-agent transcribe video.mp4 --clean --srt -o subs.srt
# ...修正 subs.srt 中的错别字、专有名词，调整不齐的行的时间...
uv run video-agent captions video.mp4 --srt subs.srt -o captioned.mp4
--srt 同时接受 .srt 和 .vtt。传入 --srt 时不执行转写，只烧录传入的文件，因此这也是编辑后重新烧录的方式。
样式
uv run video-agent captions video.mp4 -o out.mp4 --srt subs.srt \
--size 48 --color yellow --position bottom --no-box
- --size 像素（默认约为画面高度的 5%）
- --color white|yellow|red|black
- --position bottom（默认）| top | center
- --no-box 去除半透明可读性底框（背景杂乱时建议保留）
文本自动换行至画面宽度约 90%，居中。
注意事项
- 字幕数量 = 编码次数？不——单次编码。每个片段成为一张全帧 RGBA PNG，用 enable='between(t,…)' 门控叠加，全部在一次 ffmpeg 编码中完成。对短片和常见演讲足够。对非常长的视频（数百个片段）命令行会变得很大；可分割视频，分别加字幕，再拼接。
- 时间来自 whisper 片段边界，读起来没问题，但可能有约 0.3 秒的松动。需要严格同步时，可编辑 .srt 中的时间再用 --srt 重新烧录。
- 逐词 “卡拉 OK” 式字幕（每拍弹出一两个词）未内置。可通过 --words 转写、分组为短片段、为每组写起止紧凑的自定义 .srt，再用 captions --srt 近似实现。需要逐词动画弹出（缓动、缩放）时，可使用可选的 remotion-graphics 技能中的 KineticCaption，喂入相同的 --words 时间戳。两种方式的时间都从 --words 转写中提取，绝不手写估算。
- 在最终分辨率的视频上烧录。如果同时为社交做重构（reframe 技能），先重构，再加字幕——这样字号和换行匹配输出帧而非原始帧。