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	カラオケの色	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. 1行を短く保ちます（1行あたり最大42文字）
6. 表示時間は、字幕ごとに最低1秒、最大7秒にします

品質

1. スタイル付き字幕（アニメ、ミュージックビデオ）にはASS形式を使用します
2. シンプルな会話にはSRTを使用します
3. Web配信にはWebVTTを使用します
4. 可能な限り元のスタイルを維持します
5. 配布前に対象デバイスでテストします

パフォーマンス

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

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