signalstats フィルタで映像信号の統計情報を取得する

この記事でわかること

• signalstats フィルタで取得できる統計情報の種類
• フレームごとの映像信号を数値で出力する方法
• CSV形式でデータを書き出してグラフ化する方法
• 放送品質チェックへの活用
• drawtext との組み合わせで統計をオーバーレイ表示する方法

テスト済みバージョン: FFmpeg 6.1
対象 OS: Windows / macOS / Linux

signalstatsとは

signalstats はFFmpegに内蔵された映像分析フィルタです。各フレームの輝度（Y）・色差（Cb/Cr）の統計値をフレームメタデータとして出力します。

主な用途：

• 放送コンテンツのQC（品質チェック）
• クリッピング（輝度が0または255を超えている部分）の検出
• 映像全体のノイズレベル分析
• フレームごとの明度変化の追跡

取得できる統計情報

基本的な使い方

統計情報を標準エラーに出力する：

ffmpeg -i input.mp4 -vf "signalstats,metadata=mode=print" -f null /dev/null

出力例（標準エラー）：

[Parsed_metadata_1 @ ...] lavfi.signalstats.YMIN=16
[Parsed_metadata_1 @ ...] lavfi.signalstats.YMAX=235
[Parsed_metadata_1 @ ...] lavfi.signalstats.YAVG=118.2

フレームメタデータとして取得する

signalstats の出力をメタデータとして保存し、ffprobe で読み出す方法：

ffmpeg -i input.mp4 -vf signalstats=stat=tout+vrep+brng,metadata=mode=print:file=stats.txt -f null /dev/null

stats.txt にフレームごとの統計情報が書き出されます。

CSV形式で出力してグラフ化

ffprobe -f lavfi -i "movie=input.mp4,signalstats" \
  -show_frames -select_streams v \
  -print_format csv \
  -show_entries frame_tags=lavfi.signalstats.YAVG,lavfi.signalstats.YMIN,lavfi.signalstats.YMAX \
  > signalstats_output.csv

出力されたCSVをExcelやPythonでグラフ化できます。

輝度平均をリアルタイムにオーバーレイ表示

signalstats と drawtext を組み合わせると、各フレームに統計値をオーバーレイして動画に書き込めます：

ffmpeg -i input.mp4 \
  -vf "signalstats,drawtext=fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:text='YAVG\: %{metadata\:lavfi.signalstats.YAVG}':x=10:y=10:fontsize=20:fontcolor=white" \
  output_stats.mp4

特定の統計のみ有効化する（stat オプション）

ffmpeg -i input.mp4 \
  -vf "signalstats=stat=tout+vrep+brng" \
  -f null /dev/null

複数指定する場合は + で連結します。

放送品質チェックの実用例

放送コンテンツでよく使われる「輝度が16未満または235超のフレーム」を検出：

ffprobe -f lavfi \
  -i "movie=input.mp4,signalstats" \
  -show_frames -select_streams v \
  -print_format flat \
  -show_entries frame_tags=lavfi.signalstats.YMIN,lavfi.signalstats.YMAX \
  2>/dev/null | grep -E "(YMIN|YMAX)"

YAVG推移をテキストファイルに保存する

フレームごとの輝度平均をシンプルなテキストで記録：

ffmpeg -i input.mp4 \
  -vf "signalstats,metadata=mode=print:key=lavfi.signalstats.YAVG:file=yavg.txt" \
  -f null /dev/null

よくある使い方まとめ

実測例

1080p/30fps、2分の動画でYAVG、YMIN、YMAXをフレームごとにCSVへ出す場合、約3,600フレーム分の行が出力されます。

ffprobe -f lavfi -i "movie=input.mp4,signalstats" \
  -show_frames -select_streams v \
  -print_format csv \
  -show_entries frame_tags=lavfi.signalstats.YAVG,lavfi.signalstats.YMIN,lavfi.signalstats.YMAX \
  > signalstats_output.csv

出力CSVは数百KBから数MB程度に収まることが多く、動画本体に比べると小さいです。処理時間はほぼデコード速度と同じで、再エンコードは発生しません。10bitや4K素材ではデコードが重くなり、CSV出力も増えます。環境により変動します。

つまずきやすいポイント

• 症状: メタデータが何も出力されない。 原因: signalstats だけでは値はフレームメタデータに格納されるが画面にもログにも出ない。対処: metadata=mode=print を必ずチェーンに追加します（例: -vf "signalstats,metadata=mode=print"）。標準エラーに出すには出力先を -f null /dev/null にします。

• 症状: /dev/null が使えない（Windows）。 原因: /dev/null は Unix 系のヌルデバイス。対処: PowerShell や cmd では NUL を使います（例: -f null NUL）。ファイルへ保存する metadata=...:file=stats.txt 方式なら OS を問わず動きます。

• 症状: TOUT・VREP・BRNG が常に 0 になる。 原因: これらは既定で無効、または stat= の指定漏れ。対処: signalstats=stat=tout+vrep+brng のように明示的に有効化します。複数指定は + で連結します。

• 症状: CSV の行数が想定と合わない。 原因: フレームレートやフレーム総数を取り違えている。対処: CSV は1フレーム1行なので、行数 ≒ 総フレーム数（おおよそ 尺(秒) × fps）です。2分30fpsなら約3,600行が目安です。

よくある質問

Q. signalstats は映像を再エンコードしますか。 A. 分析だけなら不要です。-f null で出力を捨てれば再エンコードは発生せず、処理時間はほぼデコード速度です。drawtext で値を焼き込む場合のみ再エンコードが必要になります。

Q. クリッピング（白飛び・黒つぶれ）を検出したいです。 A. YMIN と YMAX を見ます。放送基準では 16〜235 が有効範囲なので、YMIN<16 や YMAX>235 のフレームを探します。本記事の「放送品質チェックの実用例」がそのまま使えます。

Q. 値の単位や範囲は何ですか。 A. 8bit 映像では Y・U・V とも 0〜255 です。10bit 素材ではスケールが変わるため、しきい値は素材のビット深度に合わせて読み替えます。

Q. 特定の統計だけ軽く取りたいです。 A. stat= で必要な項目だけ有効化すると計算が減ります。例えば放送範囲チェックだけなら signalstats=stat=brng で十分です。

Q. CSV をそのままグラフにできますか。 A. はい。-print_format csv で出力したファイルは Excel や pandas で読み込めます。1列目がフレーム番号、以降が指定した frame_tags の順に並びます。

関連リソース

よく使うオプション・フィルタ・コーデック設定をまとめた PDF チートシートです。手元に置いておくと調べる時間を短縮できます。

FFmpeg チートシート

関連記事

• フィルタグラフの仕組みと複合フィルタの書き方

一次ソース: ffmpeg.org/ffmpeg-filters.html#signalstats / trac.ffmpeg.org/wiki/FfprobeShowStreamsWithEnhancedOutput