Communitygithub.com

ffmpeg-captions-subtitles

FFmpeg 7.1 LTS および 8.0.1(最新安定版、2025年11月20日リリース)向けの完全な字幕・キャプションシステム。字幕の焼き込み(SRT/ASS/VTT)、ソフト字幕トラックの追加、字幕抽出、フォーマット変換、スタイル設定、配置調整、CEA-608/708クローズドキャプション、drawtextテキストオーバーレイ、Whisper AI自動文字起こし、バッチ処理に対応。

ffmpeg-captions-subtitles とは?

このスキルは、FFmpegの字幕・キャプション機能を最大限に活用するための包括的なガイドです。SRT、ASS、WebVTTなど、さまざまな字幕フォーマットの詳細なリファレンスを提供し、ビデオへの字幕の焼き込み(ハードコーディング)、ソフト字幕トラックの追加、コンテナからの字幕抽出、フォーマット変換といった基本的な操作から、フォントサイズや色、輪郭、影、位置揃えを指定したスタイル設定、CEA-608/708クローズドキャプションの処理、drawtextフィルタによるテキストオーバーレイ、さらにはFFmpeg 8.0以降で利用可能なWhisper AIによる自動文字起こし(VAD対応、多言語、GPU対応)までをカバーします。各操作に対応した即席のコマンド例、スタイルパラメータテーブル、位置揃えチャート、Whisperモデル比較表、バッチ処理スクリプト、アクセシビリティのベストプラクティスが含まれており、プロフェッショナルなキャプション作成を支援します。Windows環境でも適切に動作するよう、ファイルパスの表記に関する重要なガイドラインも提供しています。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

重要なガイドライン

Windowsのファイルパス要件

必須: Windowsではファイルパスに必ずバックスラッシュ(\)を使用すること

EditツールやWriteツールをWindowsで使用する場合、ファイルパスにはフォワードスラッシュ(/)ではなく、必ずバックスラッシュ(\)を使用しなければなりません。

ドキュメント作成ガイドライン

ユーザーから明示的に要求されない限り、新しいドキュメントファイルを作成しないでください。


クイックリファレンス

タスクコマンド
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.vttWeb/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字幕(埋め込み)ビットマップベースヨーロッパの放送
PGS.supBlu-rayビットマップ字幕Blu-ray
CEA-608/708(埋め込み)クローズドキャプション米国の放送、ストリーミング

フォーマットの特性

SRT (SubRip):
- シンプルなテキストベースのフォーマット
- 基本的なHTMLタグ(<b>, <i>, <u>)をサポート
- 幅広く互換性あり
- 配置や高度なスタイリングは非対応

ASS/SSA:
- 高度なスタイリング(フォント、色、輪郭)
- 画面上の任意の場所に正確に配置可能
- アニメーションとエフェクトのサポート
- カラオケのタイミング

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カラオケの色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フォーマット(アルファ、青、緑、赤)を使用:
- 白: &HFFFFFF または &H00FFFFFF
- 黒: &H000000 または &H00000000
- 黄: &H00FFFF(00-青, FF-緑, FF-赤)
- 赤: &H0000FF
- 青: &HFF0000
- 50%透明の黒: &H80000000

字幕トラックの追加(ソフト字幕)

SRTをトラックとして埋め込む

# MP4にSRTを追加(MOVテキスト)
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  output.mp4

# MKVにSRTを追加
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s srt \
  output.mkv

# WebMにSRTを追加(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

# MKVにASS字幕を追加(スタイルを保持)
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

複数の字幕位置

# 異なる位置にある2つの字幕トラック
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. 標準ビデオでは最低24ポイントのフォントサイズを使用する
  3. 複数の話者がいる場合は話者識別を含める
  4. 字幕が重要な視覚コンテンツを隠さないように配置する
  5. 各行は最大42文字に抑える
  6. 表示時間: キャプションあたり最小1秒、最大7秒

品質

  1. スタイル付き字幕(アニメ、ミュージックビデオ)にはASSフォーマットを使用する
  2. シンプルな会話にはSRTを使用する
  3. Web配信にはWebVTTを使用する
  4. 可能な場合は元のスタイルを維持する
  5. 配布前にターゲットデバイスでテストする

パフォーマンス

  1. 字幕の焼き込みは必要な場合のみ行う(ストリーミング、互換性)
  2. アーカイブと柔軟性のためにソフト字幕を優先する
  3. 大きなファイルに字幕を焼き込む場合はハードウェアエンコーディングを使用する
  4. バッチ操作では並列処理を行う

このガイドはFFmpegの字幕・キャプション操作をカバーしています。図形やグラフィックを含むテキストオーバーレイについては、shapes-graphicsスキルを参照してください。

関連スキル