ffmpeg-burn-subtitles-pil
用 PIL 渲染透明 PNG 图层 + ffmpeg overlay 的方式烧硬字幕,适用于 ffmpeg 构建不含 libass/freetype/fontconfig 的环境。
When to use
- 用户要求「烧字幕 / 硬字幕 / 把字幕压进视频 / 加字幕的成片」
ffmpeg -filters查不到ass/subtitles/drawtext,或报No such filter: 'ass'- 需要双语字幕(如中上英下、各一行、底部居中、白字细黑描边)按语音时间轴逐句同步
- 需要把「片头板标题 + 正片 + 片尾板」拼成完整交付版
- 不适用:只需外挂 SRT 文件;或环境有 libass(那就直接
subtitles=xxx.srt一行搞定)
第 0 步(必做):先探明本机 ffmpeg 的真实能力
ffmpeg -hide_banner -filters > /tmp/ff_filters.txt
ffmpeg -hide_banner -version | head -3 # 看 configuration 里有没有 --enable-libass / --enable-freetype / --enable-fontconfig
用 Grep 工具检索 /tmp/ff_filters.txt(注意:部分沙箱里 shell 的 grep 管道被禁用,会静默返回空 —— 不要据此判断「滤镜不存在」)。
确认这几个是否在:fade / afade / anullsrc / concat / overlay / scale / format。
同时确认双输入音频滤镜(见 Pitfalls 第 4 条)。
Steps
1. 排时间轴 → 生成字幕母版(SRT + 一份机器可读 JSON)
写一个 Python 脚本,输入「每句台词 + 所属单元/镜头 + 起始秒」,输出:
*_中文.srt/*_英文.srt/*_双语.srt(供外挂)*.ass(文字母版存档)subs.json:[{key, file, unit, start, end, dur, cn, en}, ...]—— 后续两步都读它,不要回头去解析 SRT/ASS
排布规则(关键):
- 若成片实际单元时长 ≠ 设计网格(例如设计 30s、实测 30.0417s),必须做绝对时码换算吸收累计漂移:
to_abs(unit, t) = (unit-1)*UNIT_LEN + (t - (unit-1)*GRID) - 必须 全局串行 排布,不能按单元分组后再串行 —— 否则跨单元的长句(L-cut)会让溢出字幕与下一单元首句重叠
- 典型参数:
LEAD_IN=0.25GAP=0.15MIN_DUR=0.60 - 排完打印校验:重叠数、越界数必须为 0;并列出所有跨单元台词
2. PIL 渲染透明 PNG 图层(每句一张)
用 scripts/gen_sub_overlay.py 为每条 cue 渲染一张全画布尺寸的 RGBA 透明 PNG。
- 字体(macOS):中文
/System/Library/Fonts/STHeiti Medium.ttc(index=1);英文/System/Library/Fonts/HelveticaNeue.ttc(index=0)。其他系统用font.get_fonts()或fc-list找。 - 双语版式(中上英下):中文较大、英文约中文的 0.55–0.6 倍;各自一行;底部居中。
- 描边靠
draw.text(..., stroke_width=N, stroke_fill=(0,0,0,alpha))。 - 居中要用 textbbox 修正偏移,不要直接用
(W-w)/2:bbox = dr.textbbox((0,0), text, font=font, stroke_width=stroke) w = bbox[2]-bbox[0]; h = bbox[3]-bbox[1] x = (W-w)//2 - bbox[0]; y = bottom_y - h - bbox[1] - 另存一张全透明垫片
transparent.png(间隙用)。
3. 组成「字幕图层视频」再单次 overlay
用 scripts/gen_sub_layer.py:把 cue PNG 与透明垫片按时间轴交替排列 → -loop 1 -framerate FPS -t <dur> -i <png> → concat 成一条图层流 → 对正片做一次 overlay。
ffmpeg -y -v error -i <正片> \
-loop 1 -framerate 24 -t <dur0> -i <seg0.png> ... (N 段) \
-filter_complex "[1:v]format=rgba,setpts=PTS-STARTPTS[s0]; ... ; [s0][s1]...concat=n=N:v=1:a=0[layer]; [0:v][layer]overlay=0:0:format=auto,format=yuv420p[vout]" \
-map "[vout]" -map 0:a:0 -c:v libx264 -preset fast -crf 18 -c:a copy -movflags +faststart -t <总时长> <输出>
⚠️ 输入索引从 1 开始(-i 正片 占输入 0)——见 Pitfalls 第 1 条,这是最容易踩的坑。
4.(可选)标题板 + 正片 + 片尾板 合板
用 scripts/assemble_final.py:把标题板/片尾板(静态图)先编码成与正片完全同参数的片段(分辨率/帧率/pix_fmt/音频采样率声道一致),再用 concat demuxer 无损拼接:
ffmpeg -f concat -safe 0 -i list.txt -c copy -movflags +faststart out.mp4
静态图转片段的 -vf:scale=W:H:force_original_aspect_ratio=decrease,pad=W:H:(ow-iw)/2:(oh-ih)/2:color=black,fade=t=in:st=0:d=1,fade=t=out:st=<dur-0.8>:d=0.8,format=yuv420p,并配 -f lavfi -i anullsrc=r=48000:cl=stereo 补静音轨。
Pitfalls
⚠️ 静默失败:
rc=0但字幕一帧都没烧进去 —— 输入索引 off-by-one。-i 正片是输入 0,图层段是输入 1..N。若循环里写[{k}:v](k 从 0 起),就会把正片本身当成第 0 段图层 → concat 出的「图层」前段是原画,真字幕段被挤到片尾之外被-t裁掉。 必须写[{k+1}:v]。 → 通用教训:ffmpeg 滤镜图不报错 ≠ 结果正确。rc=0只证明语法通过。合板必须做小样验证,不要直接跑全长。 给脚本加
--tlimit=<秒>参数(只编码前 90–120 秒),几十秒出结果;抽全分辨率帧看底部区域确认字幕出现;通过后再跑全长。全长 600s/1080p 档约 4–5 分钟。不要用 shell 的
grep判断 ffmpeg 能力。 部分沙箱会静默拦截cmd | grep,返回空 stdout 且退出码 0 —— 会被误读成「没有这个滤镜」。改成> /tmp/x.txt后用 Grep 工具检索。侧链闪避不可用(部分构建):
sidechaincompress/sidechaingate在filter_complex里可能无法解析第二个输入 label,报Error binding filtergraph inputs/outputs: Invalid argument(rc=234)。最小复现可确认。 → 替代方案:静态混音 + 电平差。例:对白 gain 1.9、终混amix=inputs=2:normalize=0,alimiter=limit=0.94:level=disabled,对白 mean −16dB / 底噪 −30dB → SNR 14dB,对白清晰度够用。代价是底噪不自动下压。PIL 居中不要用
(W-w)/2:textlength/textbbox不含描边与 bearing,直接算会偏。用textbbox把偏移减掉。字体 index 要试:
.ttc是字体集合,STHeiti Medium.ttc的 index=1 才是 Medium;index=0可能报错或给出另一种字重。跨单元长句(L-cut):若一句台词跨越单元边界,混音时两段必须各自只播自己那一段(
atrim=start=<负偏移>接续),不能整句重复播放,否则接缝处会出现叠字。
Verification
- 字幕层:抽 2–3 帧全分辨率图,裁出底部 20% 条带拼版目检 —— 必须肉眼看到字。只看
rc=0或文件体积不算验收。 - 时间轴:脚本里断言「重叠=0、越界=0」;末句结束时间 ≤ 片长。
- L-cut 接续(信号级,硬证据):对每条跨单元台词,取目标单元首段音频与其源音频「应播区段」做归一化互相关,峰值应落在 lag≈0、NCC 显著(实测可达 0.99)。短窗(<0.4s)把搜索范围收到 ±50ms 并放宽最小窗口,否则相关函数会因样本不足返回哨兵值(如 −2.0)被误判为失败。
- 成片规格:
ffprobe核对 duration / 分辨率 / 帧率 / 音频采样率声道数,与源一致。 - 合板段:抽头板、正片首帧、片尾板各 1 帧拼版,确认淡入淡出与三段衔接无黑帧、无错位。
参考脚本
以下四个脚本是从一次真实项目(21:9 / 600s / 双语字幕)跑通后归档的,里面的绝对路径与项目常量是示例,复用时改开头的
PROJ / WD / FIN / SR / UNIT_LEN等常量即可。它们同时是「排布 → 渲染 → 合板 → 验收」四个阶段的参考实现。
scripts/gen_sub_overlay.py— subs.json → 逐条透明 PNG 图层scripts/gen_sub_layer.py— PNG 序列 → 图层视频 → 单次 overlay(含--tlimit小样通道)scripts/verify_lcut.py— 跨单元对白接续的信号级互相关验收scripts/assemble_final.py— 标题板 + 正片 + 片尾板 同参编码 + 无损 concat