Communitygithub.com

ffmpeg-captions-subtitles

適用於 FFmpeg 7.1 LTS 和 8.0.1 的完整字幕與隱藏式字幕系統。主動啟動:燒錄字幕、加入軟字幕、擷取字幕、格式轉換、字幕樣式、位置對齊、CEA-608/708 隱藏式字幕、drawtext 文字覆疊、Whisper AI 自動轉錄及批次處理。

ffmpeg-captions-subtitles 是什麼?

這是一個專為開發者與 AI 代理(如 Claude Code、Cursor、Codex)設計的 FFmpeg 字幕技能,全面支援 FFmpeg 7.1 LTS 與 8.0.1 穩定版。其主要功能涵蓋硬編碼(燒錄)SRT/ASS/VTT 字幕、加入軟字幕軌道、從影片中擷取字幕、字幕格式轉換(如 SRT 轉 ASS/WebVTT)、進階樣式設定(字型、顏色、外框、陰影)、精確位置對齊(使用 ASS 九宮格定位)、CEA-608/708 隱藏式字幕處理、使用 drawtext 濾鏡進行動態文字覆疊,以及整合 Whisper AI 進行自動語音轉錄與字幕生成(支援 VAD、多語言、GPU 加速,需 FFmpeg 8.0+)。技能提供詳盡的格式參考表格、樣式參數指南、位置對齊圖表、Whisper 模型比較、VAD 配置、動態文字範例及無障礙最佳實踐,確保能產出專業、樣式正確且符合無障礙規範的字幕。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Biel-developer/skills-videos/tree/HEAD/skills/ffmpeg-captions-subtitles

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

重要準則

Windows 檔案路徑要求

強制:在 Windows 上使用反斜線作為檔案路徑

在 Windows 上使用編輯或寫入工具時,檔案路徑必須使用反斜線(\),不可使用正斜線(/)。

文件撰寫指南

除非使用者明確要求,否則絕對不要建立新的文件檔案。


快速參考

任務指令
燒錄 SRTffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
燒錄 ASSffmpeg -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網頁 / HTML5 影片

使用時機

用於字幕與隱藏式字幕操作:

  • 硬編碼(燒錄)字幕到影片中
  • 將軟字幕軌道加入容器
  • 從 MKV/MP4 中擷取字幕
  • 字幕樣式設定(字型、顏色、位置)
  • 動態文字覆疊

FFmpeg 字幕與隱藏式字幕(2025)

使用 FFmpeg 處理字幕、隱藏式字幕與文字覆疊的完整指南。

字幕格式參考

支援的格式

格式副檔名功能使用情境
SubRip.srt簡單的時間軸 + 文字通用、網頁
Advanced SubStation Alpha.ass/.ssa豐富樣式、位置、特效動漫、有樣式的字幕
WebVTT.vtt網頁標準、線索、樣式HTML5 影片
TTML/DFXP.ttml/.dfxp廣播、無障礙串流服務
MOV Text.mov(內嵌)QuickTime 原生Apple 生態系統
DVB Subtitle(內嵌)點陣圖基礎歐洲廣播
PGS.sup藍光點陣圖字幕藍光
CEA-608/708(內嵌)隱藏式字幕美國廣播、串流

格式特性

SRT (SubRip):
- 簡單的文字格式
- 支援基本 HTML 標籤(<b>、<i>、<u>)
- 廣泛相容
- 不支援定位或進階樣式

ASS/SSA:
- 進階樣式(字型、顏色、外框)
- 可在畫面任意位置精確定位
- 支援動畫和特效
- 卡拉 OK 時間軸

WebVTT:
- HTML5 標準格式
- 類似 CSS 的樣式
- 可用線索設定定位
- 可標示說話者

燒錄字幕(硬編碼)

基本字幕燒錄

# 燒錄 SRT 字幕
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4

# 燒錄 ASS/SSA 字幕(保留樣式)
ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4

# 從 MKV 容器燒錄字幕
ffmpeg -i video.mkv -vf "subtitles=video.mkv" output.mp4

# 燒錄特定字幕軌(索引 0)
ffmpeg -i video.mkv -vf "subtitles=video.mkv:si=0" output.mp4

# 使用串流索引燒錄字幕
ffmpeg -i video.mkv -vf "subtitles=video.mkv:stream_index=1" output.mp4

樣式化字幕燒錄

# 強制設定樣式(覆蓋原有字幕樣式)
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Outline=2,Shadow=1'" \
  output.mp4

# 黃色字幕搭配黑色外框
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=28,PrimaryColour=&H00FFFF,OutlineColour=&H000000,Outline=3'" \
  output.mp4

# 為無障礙需求使用較大字型
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 使用 &HAABBGGRR 格式(Alpha、藍、綠、紅):
- 白色:&HFFFFFF 或 &H00FFFFFF
- 黑色:&H000000 或 &H00000000
- 黃色:&H00FFFF(00-藍、FF-綠、FF-紅)
- 紅色:&H0000FF
- 藍色:&HFF0000
- 50% 透明黑色:&H80000000

加入字幕軌道(軟字幕)

將 SRT 內嵌為軌道

# 將 SRT 加入 MP4(MOV 文字格式)
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  output.mp4

# 將 SRT 加入 MKV
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s srt \
  output.mkv

# 將 SRT 加入 WebM(WebVTT 格式)
ffmpeg -i video.webm -i subs.srt \
  -c copy -c:s webvtt \
  output.webm

多條字幕軌道

# 加入多種語言
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

# 將 ASS 字幕加入 MKV(保留樣式)
ffmpeg -i video.mp4 -i styled.ass \
  -map 0 -map 1 \
  -c copy -c:s ass \
  output.mkv

設定預設字幕軌道

# 將字幕設為預設
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  -disposition:s:0 default \
  output.mp4

# 設定強制字幕(始終顯示)
ffmpeg -i video.mp4 -i forced.srt \
  -c copy -c:s mov_text \
  -disposition:s:0 forced \
  output.mp4

擷取字幕

擷取到外部檔案

# 擷取第一條字幕軌道為 SRT
ffmpeg -i video.mkv -map 0:s:0 output.srt

# 擷取特定字幕串流
ffmpeg -i video.mkv -map 0:s:1 output.srt

# 擷取為 ASS 格式
ffmpeg -i video.mkv -map 0:s:0 output.ass

# 擷取為 WebVTT 格式
ffmpeg -i video.mkv -map 0:s:0 output.vtt

# 擷取所有字幕軌道
ffmpeg -i video.mkv -map 0:s subs_%d.srt

列出可用的字幕軌道

# 顯示所有串流,包含字幕
ffprobe -v error -show_entries stream=index,codec_name,codec_type:stream_tags=language,title \
  -of csv=p=0 video.mkv

# 僅顯示字幕串流
ffprobe -v error -select_streams s \
  -show_entries stream=index,codec_name:stream_tags=language,title \
  -of csv=p=0 video.mkv

轉換字幕格式

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

# ASS 轉 SRT(會失去樣式)
ffmpeg -i subs.ass subs.srt

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

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

drawtext 覆疊與 Whisper AI 整合

有關 drawtext 覆疊(字型、定位、跳脫、時間表達式、方框、外框、動態文字)以及 Whisper AI 轉錄/字幕生成工作流程的詳細範例,請參考 references/drawtext-and-whisper.md。在需要建立燒錄式文字圖形或從語音生成字幕時,請載入該參考文件。

CEA-608/708 隱藏式字幕

擷取隱藏式字幕

# 從 ATSC 串流擷取 CEA-608 字幕
ffmpeg -f lavfi -i "movie=broadcast.ts[out0+subcc]" -map 0:1 captions.srt

# 從內嵌 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 隱藏式字幕

# 內嵌 CEA-608 字幕(需要 eia608 行)
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(上左)      8(上中)      9(上右)
4(中左)      5(中中)      6(中右)
1(下左)      2(下中)      3(下右)

定位範例

# 頂部中央字幕
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=8,MarginV=20'" \
  output.mp4

# 靠左對齊的字幕
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=1,MarginL=50,MarginV=30'" \
  output.mp4

# 將字幕放在右側以識別說話者
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=3,MarginR=50'" \
  output.mp4

多字幕定位

# 兩個不同位置的字幕軌道
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

疑難排解

常見問題

「找不到合適的輸出格式」

# 明確指定輸出格式
ffmpeg -i video.mkv -map 0:s:0 -f srt output.srt

字幕出現亂碼

# 強制使用 UTF-8 編碼
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:charenc=UTF-8" \
  output.mp4

找不到字型

# 指定字型目錄
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:fontsdir=/path/to/fonts" \
  output.mp4

# 列出可用字型
fc-list : family | sort | uniq

字幕時間偏移

# 將字幕延遲 2 秒
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:itsoffset=2" \
  output.mp4

# 或使用 setpts 調整
ffmpeg -i subs.srt -itsoffset 2 delayed.srt

在高解析度影片上字幕未顯示

# 根據影片解析度縮放字幕渲染
ffmpeg -i video_4k.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=48,Outline=3'" \
  output.mp4

驗證指令

# 檢查字幕是否存在
ffprobe -v error -select_streams s -show_entries stream=codec_name -of default=nw=1 video.mp4

# 計算字幕行數
grep -c "^[0-9]" subs.srt

# 驗證 SRT 格式
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 技能。

相關技能