核心用法
Video Caption Overlay 是一套基于 MoviePy + PIL 的命令行字幕合成工具，专为短视频（TikTok、Reels、YouTube Shorts）批量生产设计。输入基础视频、JSON 格式的字幕时间轴、可选背景音乐，输出带淡入淡出胶囊动画的最终视频。
关键工作流程
1. 准备素材：基础 MP4 视频、背景音乐（可选）、按 phase 结构编写的 captions.json
2. 执行合成：uv run 一键调用，自动处理字体回退、音频混合、视频编码
3. 输出成品：H.264 编码的最终视频，可直接上传各平台
技术亮点：PIL textbbox 修复
原生 PIL 的 textbbox() 返回的 y0 存在非零偏移（通常 7-15px），导致文字偏离胶囊视觉中心。本工具通过计算 y_off = bb[1] 并在绘制时补偿 ty = y - y_off，彻底消除文字下沉问题。
显著优点
- 零 GUI 依赖：纯命令行，服务器/CI 环境友好，适合自动化流水线
- 精确时间控制：phase 结构支持多行胶囊叠加、重叠淡入淡出
- 样式高度可配：字体、颜色、圆角、内边距、透明度全部 JSON 配置
- 音频灵活处理：可替换原声、叠加 BGM、控制音量和起始时间
潜在缺点与局限性
- Emoji 支持残缺：NotoColorEmoji.ttf 在 PIL 中尺寸受限，建议用文字替代
- Python 生态依赖：需维护 MoviePy、Pillow、FFmpeg 等版本兼容性
- 无可视化预览：JSON 编写无实时反馈，需反复渲染验证效果
- 性能瓶颈：纯 Python 合成长视频效率低于 GPU 加速方案（如 Premiere 的 Mercury Engine）
适合人群
- 需要批量生成 10-60 秒带货视频的 MCN 机构
- 追求"代码即配置"、希望版本控制字幕样式的技术型创作者
- 部署自动化短视频生产线的 SaaS 开发者
常规风险
- 字体版权：商用需自备合法授权字体（默认 Montserrat 需确认许可）
- 输出质量：MoviePy 默认编码参数可能不满足平台二压标准，建议自定义 FFmpeg 参数
- 时间同步：phase 的
start/end手动填写易出错，建议配套生成工具校验 - 维护状态：依赖 MoviePy 2.x 的 API，需关注上游 breaking changes