video-analysis

動画分析

CLI ツールを使用して MP4／動画ファイルを分析します。すべてのコマンドは、jq でフィルタリングできる JSON を出力します。

FFprobe の基本

フォーマットとストリーム（最もよく使う項目）

ffprobe -v quiet -print_format json -show_format -show_streams FILE.mp4

主なフィールド：.format.duration、.streams[].codec_name、.streams[].codec_type

ストリームの選択

-select_streams v:0   # first video stream
-select_streams a:0   # first audio stream
-select_streams v     # all video streams

パケット（サンプルレベルのデータ）

ffprobe -v quiet -print_format json -show_packets FILE.mp4

主なフィールド：.packets[].pts_time、.packets[].flags、.packets[].size

フラグの意味：K = キーフレーム、D = 破棄、_ = なし

キーフレームパケットのみ

ffprobe -v quiet -print_format json -show_packets -select_streams v:0 FILE.mp4 | \
  jq '[.packets[] | select(.flags | test("K"))]'

キーフレーム数のカウント

ffprobe -v quiet -print_format json -show_packets -select_streams v:0 FILE.mp4 | \
  jq '[.packets[] | select(.flags | test("K"))] | length'

フレーム（デコードされたフレーム情報）

ffprobe -v quiet -print_format json -show_frames FILE.mp4

主なフィールド：.frames[].pict_type（I/P/B）、.frames[].key_frame、.frames[].pts_time

フレーム数の制限（高速化）

ffprobe -v quiet -print_format json -show_frames -read_intervals "%+#100" FILE.mp4

最初の100フレームのみを読み取ります。

よく使うクエリ

再生時間

ffprobe -v quiet -show_entries format=duration -of csv=p=0 FILE.mp4

フレーム数

ffprobe -v quiet -select_streams v:0 -show_entries stream=nb_frames -of csv=p=0 FILE.mp4

コーデック情報

ffprobe -v quiet -print_format json -show_streams FILE.mp4 | \
  jq '.streams[] | {codec: .codec_name, type: .codec_type, profile: .profile}'

動画の解像度

ffprobe -v quiet -select_streams v:0 -show_entries stream=width,height -of csv=p=0 FILE.mp4

サンプルレート／チャンネル数（音声）

ffprobe -v quiet -select_streams a:0 -show_entries stream=sample_rate,channels -of csv=p=0 FILE.mp4

MP4 ボックス構造（mp4dump）

mp4dump --format json FILE.mp4

主なボックス

• ftyp：ファイルの種類／ブランド
• moov：ムービーのメタデータ（すべてのトラック情報を含む）
• mvhd：ムービーヘッダー（再生時間、タイムスケール）
• trak：トラックコンテナー
• mdhd：メディアヘッダー（トラックごとのタイムスケール／再生時間）
• stbl：サンプルテーブル（stts、stss、stsz、stco）
• stss：同期サンプルテーブル（キーフレームの位置）
• moof：ムービーフラグメント（フラグメント化された MP4）
• mdat：メディアデータ

特定のボックスを検索

mp4dump --format json FILE.mp4 | jq '.. | objects | select(.name == "mvhd")'

フラグメント化された MP4 の確認

mp4dump --format json FILE.mp4 | jq '[.. | objects | select(.name == "moof")] | length'

ゼロ以外の場合は、フラグメント化されています。

JQ パターン

フィールド値でフィルタリング

jq '.streams[] | select(.codec_type == "video")'

特定のフィールドを抽出

jq '.streams[] | {codec: .codec_name, duration: .duration}'

項目数をカウント

jq '.packets | length'

先頭から N 個の項目

jq '.packets[:10]'

値の合計

jq '[.packets[].size | tonumber] | add'

CSV 出力（スクリプト用）

ffprobe -v quiet -select_streams v:0 -show_entries packet=pts_time,flags,size -of csv=p=0 FILE.mp4

出力例：0.000000,1263,K__（パケットごとに1行）

テスト用アセット

サンプルファイルは elements/test-assets/ にあります：

• 10s-bars.mp4 - 音声付きの10秒間のカラーバー
• frame-count.mp4 - フレーム数のカウントテスト
• bars-n-tone.mp4 - マルチトラックテスト