ffmpeg-captions-subtitles

关键指南

Windows 文件路径要求

强制要求：在 Windows 上始终对文件路径使用反斜杠

在 Windows 上使用 Edit 或 Write 工具时，必须在文件路径中使用反斜杠（\），不得使用正斜杠（/）。

文档指南

除非用户明确要求，否则绝不要创建新的文档文件。

---

快速参考

任务	命令
烧录 SRT 字幕	ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
烧录 ASS 字幕	ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4
添加软字幕	ffmpeg -i video.mp4 -i subs.srt -c copy -c:s mov_text output.mp4
提取字幕	ffmpeg -i video.mkv -map 0:s:0 output.srt
设置字幕样式	-vf "subtitles=s.srt:force_style='FontSize=24,PrimaryColour=&HFFFFFF'"
叠加文本	-vf "drawtext=text='Hello':x=10:y=10:fontsize=24:fontcolor=white"

格式	扩展名	最适用场景
SRT	.srt	简单、通用
ASS	.ass	带样式、动画、动漫
VTT	.vtt	Web/HTML5 视频

何时使用此技能

用于字幕和说明文字操作：

• 将字幕硬编码（烧录）到视频中
• 向容器添加软字幕轨道
• 从 MKV/MP4 中提取字幕
• 设置说明文字样式（字体、颜色、位置）
• 动态文本叠加

---

FFmpeg 说明文字和字幕（2025）

使用 FFmpeg 处理字幕、隐藏式说明文字和文本叠加的完整指南。

字幕格式参考

支持的格式

格式	扩展名	特性	用途
SubRip	.srt	简单的时间码和文本	通用、Web
Advanced SubStation Alpha	.ass/.ssa	丰富的样式、定位和特效	动漫、样式化字幕
WebVTT	.vtt	Web 标准、提示、样式	HTML5 视频
TTML/DFXP	.ttml/.dfxp	广播、无障碍功能	流媒体服务
MOV Text	.mov（嵌入式）	QuickTime 原生格式	Apple 生态系统
DVB Subtitle	（嵌入式）	基于位图	欧洲广播
PGS	.sup	Blu-ray 位图字幕	Blu-ray
CEA-608/708	（嵌入式）	隐藏式说明文字	美国广播、流媒体

格式特性

SRT (SubRip):
- Simple text-based format
- Supports basic HTML tags (<b>, <i>, <u>)
- Widely compatible
- No positioning or advanced styling

ASS/SSA:
- Advanced styling (fonts, colors, outlines)
- Precise positioning anywhere on screen
- Animation and effects support
- Karaoke timing

WebVTT:
- HTML5 standard format
- CSS-like styling
- Cue settings for positioning
- Speaker identification

烧录字幕（硬字幕）

基本字幕烧录

# Burn SRT subtitles
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4

# Burn ASS/SSA subtitles (preserves styling)
ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4

# Burn subtitles from MKV container
ffmpeg -i video.mkv -vf "subtitles=video.mkv" output.mp4

# Burn specific subtitle track (index 0)
ffmpeg -i video.mkv -vf "subtitles=video.mkv:si=0" output.mp4

# Burn subtitles with stream index
ffmpeg -i video.mkv -vf "subtitles=video.mkv:stream_index=1" output.mp4

样式化字幕烧录

# Force style (overrides subtitle styling)
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Outline=2,Shadow=1'" \
  output.mp4

# Yellow subtitles with black outline
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=28,PrimaryColour=&H00FFFF,OutlineColour=&H000000,Outline=3'" \
  output.mp4

# Larger font for accessibility
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=36,Bold=1'" \
  output.mp4

ASS 样式参数

参数	说明	示例
FontName	字体系列	FontName=Arial
FontSize	字号（磅）	FontSize=24
PrimaryColour	文本颜色（AABBGGRR）	PrimaryColour=&HFFFFFF
SecondaryColour	卡拉 OK 颜色	SecondaryColour=&H00FFFF
OutlineColour	轮廓/边框颜色	OutlineColour=&H000000
BackColour	阴影/背景颜色	BackColour=&H80000000
Bold	粗体文本（0/1）	Bold=1
Italic	斜体文本（0/1）	Italic=1
Underline	下划线文本（0/1）	Underline=1
Outline	轮廓宽度	Outline=2
Shadow	阴影深度	Shadow=1
Alignment	位置（数字键盘样式）	Alignment=2
MarginL/R/V	边距（像素）	MarginV=50

颜色格式（ASS）

ASS uses &HAABBGGRR format (Alpha, Blue, Green, Red):
- White: &HFFFFFF or &H00FFFFFF
- Black: &H000000 or &H00000000
- Yellow: &H00FFFF (00-Blue, FF-Green, FF-Red)
- Red: &H0000FF
- Blue: &HFF0000
- 50% transparent black: &H80000000

添加字幕轨道（软字幕）

将 SRT 嵌入为轨道

# Add SRT to MP4 (MOV text)
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  output.mp4

# Add SRT to MKV
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s srt \
  output.mkv

# Add SRT to WebM (WebVTT)
ffmpeg -i video.webm -i subs.srt \
  -c copy -c:s webvtt \
  output.webm

多条字幕轨道

# Add multiple languages
ffmpeg -i video.mp4 -i subs_en.srt -i subs_es.srt -i subs_fr.srt \
  -map 0:v -map 0:a -map 1 -map 2 -map 3 \
  -c copy -c:s mov_text \
  -metadata:s:s:0 language=eng -metadata:s:s:0 title="English" \
  -metadata:s:s:1 language=spa -metadata:s:s:1 title="Spanish" \
  -metadata:s:s:2 language=fra -metadata:s:s:2 title="French" \
  output.mp4

# Add ASS subtitles to MKV (preserves styling)
ffmpeg -i video.mp4 -i styled.ass \
  -map 0 -map 1 \
  -c copy -c:s ass \
  output.mkv

设置默认字幕轨道

# Set subtitle as default
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  -disposition:s:0 default \
  output.mp4

# Set forced subtitles (always display)
ffmpeg -i video.mp4 -i forced.srt \
  -c copy -c:s mov_text \
  -disposition:s:0 forced \
  output.mp4

提取字幕

提取到外部文件

# Extract first subtitle track to SRT
ffmpeg -i video.mkv -map 0:s:0 output.srt

# Extract specific subtitle stream
ffmpeg -i video.mkv -map 0:s:1 output.srt

# Extract to ASS format
ffmpeg -i video.mkv -map 0:s:0 output.ass

# Extract to WebVTT
ffmpeg -i video.mkv -map 0:s:0 output.vtt

# Extract all subtitle tracks
ffmpeg -i video.mkv -map 0:s subs_%d.srt

列出可用字幕轨道

# Show all streams including subtitles
ffprobe -v error -show_entries stream=index,codec_name,codec_type:stream_tags=language,title \
  -of csv=p=0 video.mkv

# Show only subtitle streams
ffprobe -v error -select_streams s \
  -show_entries stream=index,codec_name:stream_tags=language,title \
  -of csv=p=0 video.mkv

转换字幕格式

# SRT to ASS
ffmpeg -i subs.srt subs.ass

# ASS to SRT (loses styling)
ffmpeg -i subs.ass subs.srt

# SRT to WebVTT
ffmpeg -i subs.srt subs.vtt

# WebVTT to SRT
ffmpeg -i subs.vtt subs.srt

drawtext 叠加和 Whisper AI 集成

drawtext 叠加（字体、定位、转义、时间表达式、文本框、轮廓和动画文本）以及 Whisper AI 转录/字幕生成工作流的详细示例位于 references/drawtext-and-whisper.md。创建烧录式文本图形或根据语音生成字幕时，请加载该参考资料。

CEA-608/708 隐藏式说明文字

提取隐藏式说明文字

# Extract CEA-608 captions from ATSC stream
ffmpeg -f lavfi -i "movie=broadcast.ts[out0+subcc]" -map 0:1 captions.srt

# Extract from video with embedded CC
ffmpeg -i video_with_cc.mp4 \
  -filter_complex "[0:v]format=yuv420p[v];[0:v]crop=1:1:0:0[c]" \
  -map "[c]" -c:v libx264 -f null - 2>&1 | grep -A 1 "Closed caption"

添加 CEA-608 说明文字

# Embed CEA-608 captions (requires eia608 line)
ffmpeg -i video.mp4 -i captions.scc \
  -c:v libx264 -c:a copy \
  -vf "movie=captions.scc[captions];[0:v][captions]overlay" \
  output.mp4

字幕定位

ASS 对齐值

7 (top-left)     8 (top-center)     9 (top-right)
4 (mid-left)     5 (mid-center)     6 (mid-right)
1 (bottom-left)  2 (bottom-center)  3 (bottom-right)

位置示例

# Top center subtitles
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=8,MarginV=20'" \
  output.mp4

# Left-aligned subtitles
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=1,MarginL=50,MarginV=30'" \
  output.mp4

# Right side for speaker identification
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=3,MarginR=50'" \
  output.mp4

多个字幕位置

# Two subtitle tracks at different positions
ffmpeg -i video.mp4 \
  -vf "[in]subtitles=speaker1.srt:force_style='Alignment=1,MarginL=50'[tmp];\
       [tmp]subtitles=speaker2.srt:force_style='Alignment=3,MarginR=50'" \
  output.mp4

批量处理

将字幕烧录到多个视频中

#!/bin/bash
# burn_subs_batch.sh

for video in *.mp4; do
    base="${video%.mp4}"
    if [ -f "${base}.srt" ]; then
        ffmpeg -i "$video" \
          -vf "subtitles=${base}.srt:force_style='FontSize=24,Outline=2'" \
          -c:a copy \
          "output/${base}_subbed.mp4"
    fi
done

批量转换字幕格式

#!/bin/bash
# convert_subs.sh

for srt in *.srt; do
    base="${srt%.srt}"
    ffmpeg -i "$srt" "${base}.vtt"
done

故障排除

常见问题

“无法找到合适的输出格式”

# Specify output format explicitly
ffmpeg -i video.mkv -map 0:s:0 -f srt output.srt

字幕出现乱码

# Force UTF-8 encoding
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:charenc=UTF-8" \
  output.mp4

未找到字体

# Specify fonts directory
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:fontsdir=/path/to/fonts" \
  output.mp4

# List available fonts
fc-list : family | sort | uniq

字幕时间偏移

# Delay subtitles by 2 seconds
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:itsoffset=2" \
  output.mp4

# Or use setpts to adjust
ffmpeg -i subs.srt -itsoffset 2 delayed.srt

字幕未显示在高分辨率视频上

# Scale subtitle rendering to video resolution
ffmpeg -i video_4k.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=48,Outline=3'" \
  output.mp4

验证命令

# Check if subtitles are present
ffprobe -v error -select_streams s -show_entries stream=codec_name -of default=nw=1 video.mp4

# Count subtitle lines
grep -c "^[0-9]" subs.srt

# Validate SRT format
ffmpeg -i subs.srt -f null -

最佳实践

无障碍性

1. 使用高对比度颜色（深色背景上的白色或黄色）
2. 标准视频的字体大小至少为 24pt
3. 多人发言时标明说话者
4. 放置字幕时避免遮挡重要画面内容
5. 保持行文简短（每行最多 42 个字符）
6. 每条字幕的显示时长：最短 1 秒，最长 7 秒

质量

1. 样式化字幕（动漫、音乐视频）使用 ASS 格式
2. 简单对话使用 SRT
3. 网页投放使用 WebVTT
4. 尽可能保留原始样式
5. 分发前在目标设备上进行测试

性能

1. 仅在必要时（流媒体、兼容性）烧录字幕
2. 归档和灵活使用时优先采用软字幕
3. 将字幕烧录到大型文件时使用硬件编码
4. 批量操作时并行处理

本指南介绍了 FFmpeg 的字幕和说明文字操作。如需了解带形状和图形的文本叠加，请参阅 shapes-graphics 技能。