视频字幕叠加

用于短视频的动画药丸式字幕叠加。无需Premiere，无需CapCut——纯Python实现。

使用方法

bash
uv run --with moviepy --with pillow scripts/overlay.py \
--video base.mp4 \
--output final.mp4 \
--captions scripts/example_captions.json \
--audio music.mp3 \
--audio-start 8 \
--audio-vol 0.5

如需保留原始视频音频，则无需使用--audio参数。

自定义字体

bash
--font-black /path/to/Montserrat-Black.ttf \
--font-bold /path/to/Montserrat-Bold.ttf

若未指定字体，则默认从~/.local/share/fonts/目录加载Montserrat字体。

captions.json格式

阶段数组——每个阶段是一个时间窗口，包含一个或多个垂直堆叠的药丸式字幕行。

json
[
{
start: 0,
end: 3.2,
y_frac: 0.06,
lines: [
{
text: POV:,
size: 28,
bold: true,
bg: [0, 195, 255],
fg: [0, 0, 0],
bg_opacity: 0.9,
px: 20, py: 9, r: 12
},
{
text: 多喝水,
size: 50,
bg: [255, 255, 255],
fg: [0, 0, 0]
}
]
}
]

字段	类型	默认值	描述
start	float	必填	阶段开始时间（秒）
end

float | 必填 | 阶段结束时间（秒） | | y_frac | float | 0.06 | 垂直位置（视频高度的比例） | | lines[].text | string | 必填 | 字幕文本 | | lines[].size | int | 50 | 字体大小（像素） | | lines[].bold | bool | false | 使用粗体（相对于黑色/重型字体） | | lines[].bg | [R,G,B] | [255,255,255] | 药丸背景颜色 | | lines[].fg | [R,G,B] | [0,0,0] | 文字颜色 | | lines[].bg_opacity | float | 0.93 | 药丸背景透明度（0-1） | | lines[].px | int | 26 | 水平内边距 | | lines[].py | int | 13 | 垂直内边距 | | lines[].r | int | 18 | 边框圆角半径 |

PIL文本边界框修正

PIL的textbbox((0,0), text, font)返回(x0, y0, x1, y1)，其中y0是一个非零偏移量（根据字体大小通常为7-15像素）。在(x, y)位置绘制文本时若不补偿此偏移量，会导致文本显示在药丸视觉中心的下方。

在pill()中实现的修正方法：
python
bb = draw.textbbox((0, 0), text, font=font)
xoff, yoff = bb[0], bb[1]
vis_w = bb[2] - bb[0] # 实际视觉宽度
vis_h = bb[3] - bb[1] # 实际视觉高度

绘制文本时补偿偏移量

tx = cx - visw // 2 - xoff ty = y - y_off draw.text((tx, ty), text, font=font, fill=fg)

表情符号说明

NotoColorEmoji.ttf在任意尺寸下均无法与PIL正常配合使用（位图字体仅支持有限尺寸）。请使用文本替代方案（例如使用免费配送代替免费配送 🚚）以确保可靠渲染。

示例输出

请参阅scripts/example_captions.json获取完整的3阶段TikTok广告结构：

• - 阶段1（0-3.2秒）：钩子——屏幕顶部药丸堆叠
• 阶段2（2.8-5.8秒）：产品宣传——重叠淡入效果
• 阶段3（5.3-8.0秒）：行动号召——屏幕底部价格+配送+个人简介链接