ffmpeg-video-analysis

重要なガイドライン

Windows のファイルパス要件

必須：Windows ではファイルパスに必ずバックスラッシュを使用してください

Windows で Edit または Write ツールを使用する場合、ファイルパスにはスラッシュ（/）ではなく、バックスラッシュ（\）を必ず使用してください。

---

クイックリファレンス

タスク	フィルター	コマンドパターン
黒いフレームを検出	blackdetect	-vf blackdetect=d=0.5:pic_th=0.98
静止したフレームを検出	freezedetect	-vf freezedetect=n=0.003:d=2
ぼやけを検出	blurdetect	-vf blurdetect=low=5:high=15
自動クロップ	cropdetect	-vf cropdetect=24:16:0
シーンの切り替わり	scdet	-vf scdet=threshold=10
品質メトリクス	psnr、ssim	-lavfi "[0:v][1:v]psnr" -f null -
フレーム情報	showinfo	-vf showinfo

このスキルを使用する場面

品質管理と自動化のワークフローに使用します。

• 動画の自動解析パイプライン
• 問題のあるフレーム（黒い、静止した、ぼやけたフレーム）の検出
• 最適なクロップパラメーターの特定
• エンコード後の品質測定
• 放送基準への準拠確認
• コンテンツを考慮した編集判断

---

FFmpeg 動画解析フィルター（2025）

品質管理、自動化、プロフェッショナルなワークフロー向けの動画解析フィルターを網羅したガイドです。

検出フィルター

blackdetect - 黒いフレームを検出

完全に黒い動画シーケンスを検出します。CM の挿入箇所、シーンの境界、エンコードの問題を特定するのに役立ちます。

# Basic black detection
ffmpeg -i input.mp4 -vf "blackdetect=d=0.5:pic_th=0.98:pix_th=0.10" -f null -

# More sensitive detection (darker threshold)
ffmpeg -i input.mp4 -vf "blackdetect=d=0.1:pic_th=0.90" -f null -

# Save detection results to log
ffmpeg -i input.mp4 -vf "blackdetect=d=0.5" -f null - 2>&1 | grep blackdetect

# Detect and extract black segments
ffmpeg -i input.mp4 -vf "blackdetect=d=2.0" -f null - 2>&1 | \
  grep -oP 'black_start:\K[0-9.]+|black_end:\K[0-9.]+'

パラメーター：

パラメーター	説明	デフォルト	範囲
d	最小継続時間（秒）	2.0	> 0
pic_th	画像の黒さの割合のしきい値	0.98	0-1
pix_th	ピクセルの黒さのしきい値	0.10	0-1

出力形式：

[blackdetect @ 0x...] black_start:10.5 black_end:12.3 black_duration:1.8

blackframe - ほぼ黒いフレームを検出

blackdetect と同様ですが、個々のフレームとその黒さの度合いを報告します。

# Detect frames that are 98% black
ffmpeg -i input.mp4 -vf "blackframe=amount=98:threshold=32" -f null -

# Output includes frame number and percentage
ffmpeg -i input.mp4 -vf "blackframe=amount=90" -f null - 2>&1 | grep blackframe

パラメーター：

パラメーター	説明	デフォルト	範囲
amount	割合のしきい値	98	0-100
threshold	ピクセルの輝度のしきい値	32	0-255

freezedetect - 静止したフレームを検出

動画が静止しているように見える（同じフレームが繰り返される）シーケンスを検出します。

# Basic freeze detection
ffmpeg -i input.mp4 -vf "freezedetect=n=0.003:d=2" -f null -

# More sensitive (detect shorter freezes)
ffmpeg -i input.mp4 -vf "freezedetect=n=0.001:d=0.5" -f null -

# Very strict (only perfectly identical frames)
ffmpeg -i input.mp4 -vf "freezedetect=n=0:d=1" -f null -

パラメーター：

パラメーター	説明	デフォルト	範囲
n	ノイズ許容値（フレーム差分）	0.001	0-1
d	静止状態の最小継続時間	2.0	> 0

出力形式：

[freezedetect @ 0x...] freeze_start: 45.2
[freezedetect @ 0x...] freeze_duration: 3.5
[freezedetect @ 0x...] freeze_end: 48.7

blurdetect - ぼやけたフレームを検出

ピントが外れている、またはモーションブラーが発生しているフレームを検出します。

# Basic blur detection
ffmpeg -i input.mp4 -vf "blurdetect=low=5:high=15:radius=50" -f null -

# More sensitive detection
ffmpeg -i input.mp4 -vf "blurdetect=low=3:high=10" -f null -

# Output blur values per frame
ffmpeg -i input.mp4 -vf "blurdetect,metadata=print:file=blur.txt" -f null -

パラメーター：

パラメーター	説明	デフォルト	範囲
low	低エッジしきい値	5	1-100
high	高エッジしきい値	15	1-100
radius	検索半径	50	1-100
block_pct	ブロックの割合	80	0-100
block_width	ブロック幅	-	> 0
block_height	ブロック高さ	-	> 0
planes	解析するプレーン	1	0-15

出力メタデータ：

• lavfi.blur - ぼやけの値（低いほどぼやけています）

scdet - シーン切り替わりの検出

フレーム間の差分に基づいてシーンの切り替わりを検出します。

# Basic scene detection
ffmpeg -i input.mp4 -vf "scdet=threshold=10:sc_pass=1" -f null -

# More sensitive (detect more scene changes)
ffmpeg -i input.mp4 -vf "scdet=threshold=5" -f null -

# Output scene changes with timestamps
ffmpeg -i input.mp4 -vf "scdet=t=10,metadata=print:file=scenes.txt" -f null -

# Combined with select filter to extract scene thumbnails
ffmpeg -i input.mp4 -vf "scdet=threshold=10,select='gt(scene,0.4)',showinfo" \
  -vsync vfr scene_%04d.jpg

パラメーター：

パラメーター	説明	デフォルト	範囲
threshold / t	シーン切り替わりのしきい値	10.0	0-100
sc_pass	シーンスコアを出力に渡す	0	0-1

出力メタデータ：

• lavfi.scd.score - シーン切り替わりスコア（0-1）
• lavfi.scd.mafd - フレーム間の平均絶対差分
• lavfi.scd.time - シーン切り替わりのタイムスタンプ

cropdetect - 自動クロップ検出

黒い境界線を取り除くための最適なクロップ値を自動的に検出します。

# Basic crop detection
ffmpeg -i input.mp4 -vf "cropdetect=24:16:0" -f null -

# More aggressive detection (lower threshold)
ffmpeg -i input.mp4 -vf "cropdetect=16:2:0" -f null -

# Detect and apply crop in one command
crop=$(ffmpeg -i input.mp4 -vf "cropdetect=24:16:0" -f null - 2>&1 | \
  grep -oP 'crop=\K[0-9:]+' | tail -1)
ffmpeg -i input.mp4 -vf "crop=$crop" output.mp4

# Detect letterbox dimensions
ffmpeg -i input.mp4 -vf "cropdetect=round=2:reset=0" -f null - 2>&1 | grep crop

パラメーター：

パラメーター	説明	デフォルト	範囲
limit	黒いピクセルのしきい値	24	0-255
round	最も近い倍数に丸める	16	>= 2
reset	カウンターをリセット（フレーム数）	0	>= 0
skip	初期フレームをスキップ	0	>= 0

出力形式：

[cropdetect @ 0x...] x1:0 x2:1919 y1:140 y2:939 w:1920 h:800 x:0 y:140 crop=1920:800:0:140

idet - インターレース検出

動画がインターレースかどうかを検出し、フィールド順を特定します。

# Basic interlace detection
ffmpeg -i input.mp4 -vf "idet" -frames:v 500 -f null -

# Output detection summary
ffmpeg -i input.mp4 -vf "idet" -f null - 2>&1 | grep -A5 "Repeated Fields"

出力内容：

• 単一（プログレッシブフレーム）
• 複数（インターレース。同じフレームの複数のフィールド）
• 繰り返し（フィールドの繰り返し。プルダウン）
• トップフィールドファースト（TFF）とボトムフィールドファースト（BFF）

---

品質指標

psnr - ピーク信号対雑音比

2 つの動画を比較し、PSNR 品質指標を出力します。

# Compare original vs encoded
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]psnr" -f null -

# Output PSNR per frame to file
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]psnr=stats_file=psnr.log" -f null -

# Get average PSNR only
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]psnr" -f null - 2>&1 | grep "average"

出力形式：

[Parsed_psnr_0 @ 0x...] PSNR y:45.123 u:48.456 v:49.789 average:46.234 min:35.123 max:inf

品質の目安：

PSNR（dB）	品質
> 40	優秀（区別できない）
35-40	良好
30-35	普通
< 30	低い

ssim - 構造的類似性指標

品質比較では、PSNR よりも人間の知覚に即した指標です。

# Compare original vs encoded
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]ssim" -f null -

# Output SSIM per frame to file
ffmpeg -i original.mp4 -i encoded.mp4 \
  -lavfi "[0:v][1:v]ssim=stats_file=ssim.log" -f null -

出力形式：

[Parsed_ssim_0 @ 0x...] SSIM Y:0.987 (18.87) U:0.992 (20.97) V:0.993 (21.55) All:0.989 (19.59)

品質の目安：

SSIM	品質
> 0.98	優秀
0.95-0.98	良好
0.90-0.95	普通
< 0.90	低い

vmafmotion - VMAF モーションスコア

VMAF で使用されるモーションアクティビティスコアを計算します。

# Calculate motion score
ffmpeg -i input.mp4 -vf "vmafmotion" -f null - 2>&1 | grep vmafmotion

# Get average motion
ffmpeg -i input.mp4 -vf "vmafmotion" -f null - 2>&1 | tail -1

signalstats - 映像信号統計

放送品質管理（QC）向けに、包括的な信号解析を行います。

# Full signal analysis
ffmpeg -i input.mp4 -vf "signalstats=stat=tout+vrep+brng" -f null -

# Output to file
ffmpeg -i input.mp4 -vf "signalstats,metadata=print:file=stats.txt" -f null -

# Check for broadcast-safe levels
ffmpeg -i input.mp4 -vf "signalstats=stat=brng,metadata=print" -f null - 2>&1 | \
  grep "lavfi.signalstats.BRNG"

利用可能な統計情報：

統計情報	説明
tout	時間方向の外れ値
vrep	垂直方向のラインの繰り返し
brng	放送範囲の違反

出力メタデータの内容：

• YMIN、YMAX - 輝度の範囲
• YAVG - 平均輝度
• UMIN、UMAX、VMIN、VMAX - 色差の範囲
• SATMIN、SATMAX、SATAVG - 彩度
• HUEAVG - 平均色相
• BRNG - 放送範囲外のピクセル数

---

フレーム情報

showinfo - フレーム情報の表示

各フレームの詳細情報を出力します。

# Show all frame info
ffmpeg -i input.mp4 -vf "showinfo" -f null -

# Show specific frames only
ffmpeg -i input.mp4 -vf "select='eq(n,0)+eq(n,100)',showinfo" -f null -

# Parse specific information
ffmpeg -i input.mp4 -vf "showinfo" -f null - 2>&1 | grep "pts_time"

出力内容：

[Parsed_showinfo_0 @ 0x...] n:   0 pts:      0 pts_time:0       duration:   1001
 duration_time:0.0417083 fmt:yuv420p cl:left sar:1/1 s:1920x1080 i:P iskey:1
 type:I checksum:12345678 plane_checksum:[AAAAAAAA BBBBBBBB CCCCCCCC]

フィールド：

• n - フレーム番号
• pts - 表示タイムスタンプ
• pts_time - 秒単位の PTS
• duration - フレームの長さ
• fmt - ピクセル形式
• s - サイズ（解像度）
• i - インターレース（P＝プログレッシブ、T＝トップ、B＝ボトム）
• iskey - キーフレームかどうか
• type - フレームタイプ（I/P/B）

siti - 空間情報と時間情報

ITU-T P.910 に準拠した SI/TI の計算です。

# Calculate SI/TI
ffmpeg -i input.mp4 -vf "siti" -f null - 2>&1 | grep siti

# Output to file
ffmpeg -i input.mp4 -vf "siti=print_summary=1" -f null -

出力：

• SI - 空間情報（エッジ／テクスチャの複雑さ）
• TI - 時間情報（モーションアクティビティ）

---

自動化パターン

一括解析、構造化レポートの生成、しきい値チェック、FFmpeg の検出フィルター・品質指標・フレーム情報を対象とした CI 形式の検証に使えるシェル自動化レシピは、references/automation-patterns.md にあります。場当たり的な解析コマンドを再利用可能なパイプラインにする際は、このリファレンスを読み込んでください。

---

ベストプラクティス

1. 適切なしきい値を使う - まずデフォルト値を使い、コンテンツに応じて調整します
2. 長い動画はサンプリングする - まず -t を使って一部分を解析します
3. フィルターを組み合わせる - 検出フィルターを連結し、包括的に解析します
4. 出力を解析する - grep/awk を使って関連データを抽出します
5. 一括処理する - 一貫した QC ワークフロー用のスクリプトを作成します
6. 結果を記録する - metadata=print:file= を使って結果を保存します

このガイドでは、2025 年版の動画解析フィルターを解説しています。エンコード品質については、ffmpeg-fundamentals-2025 を参照してください。ハードウェアアクセラレーションによる解析については、ffmpeg-hardware-acceleration の GPU フィルターのサポートを確認してください。