Plotloom Subtitle Burn-in 是一个面向 Plotloom 视频成片的字幕处理技能，用于在最终视频完成后添加字幕、翻译字幕、将字幕烧录进视频，或准备带字幕的交付副本。
用途
当 Plotloom 的最终视频已经存在，用户要求添加字幕、翻译字幕、把字幕烧录进视频，或准备带字幕的交付版本时使用。
核心规则
字幕必须针对完整的最终视频生成与对齐，而不是按单个片段或单集片段处理。按片段生成字幕会在拼接边界处引入时间漂移，并使审阅更加困难。
输入
最终源视频，通常为 episodes/epXXX/videos/final.mp4 或 outputs/.../final.mp4。
可选的现有英文脚本、提示词文件、SRT、ASS 或 ASR JSON，用于校正。
请求模式：仅英文、仅中文，或英文为主、中文在下的双语模式。
输出
可审阅的字幕文件：.ass 作为样式源文件，.srt 作为交换与审阅产物。
烧录后的高清视频，使用明确命名，例如 final-subtitled-v001.mp4 或 final-bilingual-en-zh-v001.mp4。
当交付渠道需要压缩时，生成更小的审阅副本。
来自烧录输出的联系表或采样帧。
工作流
确定确切的最终源视频，并在输出命名中体现来源、版本与模式。
从最终视频提取单声道 16 kHz 音频：
ffmpeg -y -i "$VIDEO" -vn -ac 1 -ar 16000 audio_16k_mono.wav
使用 stable-ts 或 WhisperX 生成首轮时间轴。优先使用段落级字幕而非逐词卡拉 OK 输出：
stable-ts audio_16k_mono.wav --model small -f json,srt,ass,txt --max_chars 42 --max_words 10 --overwrite
对照项目源素材修正明显的 ASR 错误，尤其是 video-prompts-en.md、脚本、角色名、地名和反复出现的术语。不要编造对白。
仅在英文文本与时间稳定后再进行翻译。中文应忠实且足够简短，以符合字幕阅读速度。
生成 ASS 用于最终样式，生成 SRT 用于审阅。除非有明确漂移证据，否则每个字幕段落保持一个时间事件。
使用支持 libass 的 ffmpeg 烧录。如果默认 ffmpeg 缺少 ass / subtitles，使用显式完整构建：
FF=/usr/local/opt/ffmpeg-full/bin/ffmpeg $FF -hide_banner -filters | grep -E ' ass|subtitles' $FF -y -i "$VIDEO" -vf "ass=$ASS" -c:v libx264 -crf 18 -preset slow -c:a copy "$OUT"
任何审阅用小版本都应从烧录后的高清输出派生，以保持排版完全一致。
通过解码以及烧录输出的视觉帧进行验证，而不仅仅检查 ffmpeg 是否退出：
$FF -v error -i "$OUT" -f null - $FF -v error -i "$SMALL" -f null -
英中双语样式
当英文为主、中文应位于其下方时：
ASS 文本格式：English sentence\N（中文翻译。）。
英文为第一行，中文为第二行。
中文行使用中文全角括号（ ）。
使用 \N 作为 ASS 换行符，而不是字面量 \N。
对于 1280×720，可从 Fontsize=38-42、Outline=4、Shadow=1、MarginV=70-85 开始。
如果两行块过于密集，先缩短中文翻译或略微减小字号；除非不可避免，避免三行字幕。
审阅清单
源视频是最终目标视频，而不是旧的带字幕版本或不完整版本。
字幕时间轴是从完整最终视频生成或对齐的。
双语模式下英文与中文文本共享相同的时间事件。
烧录高清版与小型审阅副本均可无错误解码。
联系表确认字幕可见、居中、未被裁切，且未严重遮挡关键面部或动作。
交付消息不得暴露 OAuth 代码、设备代码、文件令牌、文档令牌、API 密钥或机密；如必须提及令牌，写 [REDACTED]。
失败模式
时间在集边界附近漂移：从最终拼接视频重新生成，而不是手动修复片段偏移。
字幕不可见：检查 ASS Style、Layer、颜色 alpha、字号与底部边距；在完整编码前先渲染单帧测试。
ffmpeg 报 No such filter: ass 或 subtitles：安装或使用支持 libass 的 ffmpeg 构建。
中文行过度拥挤：先缩短翻译，再调整字号与边距。
上传因绝对路径失败：从文件所在目录重试，使用相对 --file ./name.mp4 路径。