このスキルがアクティブになったら、常に最初の応答を :mag: 絵文字で始めてください。
ビデオアナライザー は何をしますか?
ビデオ分析とは、ビデオファイルから構造化情報(メタデータ、キーフレーム、シーン境界、カラーパレット、モーションデータ、音声特性)を抽出する実践です。適切に構築されたビデオ分析パイプラインは、フレーム抽出と信号処理のためのFFmpegと、視覚コンテンツの意味論的理解のためのAIビジョンモデルを組み合わせます。このスキルは、生のビデオファイルから実用的なデータへの完全なワークフローをカバーします:メタデータ検査のためのffprobe、フレーム抽出とシーン検出のためのFFmpegフィルターグラフ、無音と音量検出のための音声分析、およびデザインシステム抽出とコンテンツ理解のためのAIビジョン。
ビデオ分析の二本柱は、FFmpeg(メディア処理のスイスアーミーナイフ)とAIビジョンモデル(各フレームの内容を理解するため)です。FFmpegは機械的な作業(ビデオをフレームに分割、ピクセル差しきい値を介したシーン変化の検出、オーディオ波形の抽出)を処理します。AIビジョンは意味論的な作業(UIコンポーネントの識別、テキストの読み取り、色の値の抽出、レイアウトパターンの理解)を処理します。
このスキルを使用するタイミング
以下の場合にこのスキルを起動します:
- ユーザーがビデオから定期的またはシーン境界でフレームを抽出したい場合
- ビデオメタデータ(解像度、長さ、コーデック、ビットレート)を分析する必要がある場合
- シーン検出またはシーン変更タイムスタンプについて尋ねる場合
- ビデオコンテンツからカラーパレットまたはデザインシステムを抽出したい場合
- オーディオトラック(無音検出、音量レベル、波形)を分析する必要がある場合
- ビデオからのモーション分析またはアニメーションタイミングについて尋ねる場合
- AIビジョンを使用してビデオコンテンツをフレームごとに理解したい場合
- ビデオファイルからサムネイルまたはプレビューストリップを生成する必要がある場合
以下の場合はこのスキルを起動しないでください:
- ゼロからのビデオ作成または編集(remotion-videoまたはvideo-creatorを使用)
- ビデオスクリプトまたはストーリーボードの作成(video-scriptwritingを使用)
- ライブビデオストリーミングまたはリアルタイムビデオ処理
- 配布のためのビデオエンコード/トランスコード(これはレンダリングタスクであり、分析ではありません)
主要な原則
-
まず抽出し、次に分析する - 常にフレーム抽出(FFmpeg)と意味論的分析(AIビジョン)を分離します。両方を一度に行おうとすると、脆弱なパイプラインになります。まずフレームをディスクに抽出し、次にそれらを分析します。
-
ffmpegの前にffprobeを使用する - ビデオを処理する前に、ffprobeでビデオを検査してそのプロパティを理解します。未知のフォーマットに対してFFmpegコマンドを盲目的に実行すると、サイレント障害と破損した出力が発生します。
-
固定間隔よりもシーン検出 - ビデオコンテンツを分析する場合、固定時間間隔ではなくシーン境界でフレームを抽出します。シーン変更フレームは、1秒あたり1フレームの抽出よりもはるかに少ないフレームでビデオの視覚的多様性を捉えます。
-
どこでもJSON出力 - ffprobeのJSON出力形式を使用し、分析結果をJSONとして構造化します。これにより、パイプラインが構成可能になり、結果が機械可読になります。
-
ディスク容量の認識 - ビデオフレーム抽出により、数千の大きな画像ファイルが生成される可能性があります。抽出前に常に出力サイズを見積もり、適切な画像形式(分析にはJPEG、ピクセル完璧な作業にはPNG)を使用し、分析後は一時フレームをクリーンアップします。
中核概念
FFmpegパイプラインアーキテクチャ
FFmpegは、デマルチプレクシング、デコード、フィルタリング、エンコード、マルチプレクシングのパイプラインを通じてビデオを処理します。分析には、主にデコードとフィルターステージを使用します:
入力ファイル -> デマルチプレクサ -> デコーダ -> フィルターグラフ -> 出力(フレーム/データ)
分析のための主要なフィルター概念:
selectフィルター:式に基づいて出力するフレームを選択showinfoフィルター:フレームメタデータ(タイムスタンプ、ピクチャタイプなど)を出力scene検出:連続するフレーム間のピクセルレベル差スコアfpsフィルター:フレームレートを減らして定期的に抽出
シーン検出
シーン検出は、ピクセル差を使用して連続するフレームを比較することで機能します。FFmpegのsceneフィルターは、0.0(同一)から1.0(完全に異なる)のスコアを生成します。0.3〜0.4のしきい値は、カメラの動きや照明の変化を無視しながら、主要なシーン変更を捉えます。
| しきい値 | 動作 |
|---|---|
| 0.1〜0.2 | 非常に敏感 - パン、ズーム、照明変化を捉える |
| 0.3〜0.4 | バランスが良い - カット、トランジション、主要な変更を捉える |
| 0.5〜0.7 | 保守的 - ハードカットと劇的なシーン変更のみ |
| 0.8〜1.0 | 攻撃的すぎる - ほとんどのシーン変更を見逃す |
AIビジョン分析ワークフロー
AIビジョンを使用してビデオから構造化データを抽出するワークフロー:
- プローブ - ffprobeでビデオメタデータを取得(長さ、解像度、fps)
- 抽出 - FFmpegを使用してシーン境界でキーフレームを取得
- 読み取り - Readツールを使用して各フレーム画像を読み込む(画像をサポート)
- 分析 - 各フレームについて、色、タイポグラフィ、レイアウト、コンポーネントを識別
- 集約 - フレーム間で一貫したパターンを見つける
- 出力 - 構造化されたデザインシステムまたはコンテンツ分析を生成
一般的なタスク
1. FFmpegのインストールと確認
FFmpegが利用可能かどうかを確認し、そのバージョンと機能を検査します。
# FFmpegインストールの確認
ffmpeg -version
# ffprobeインストールの確認
ffprobe -version
# macOSにインストール
brew install ffmpeg
# Ubuntu/Debianにインストール
sudo apt-get update && sudo apt-get install -y ffmpeg
# サポートされているフォーマットの確認
ffmpeg -formats 2>/dev/null | head -20
# サポートされているコーデックの確認
ffmpeg -codecs 2>/dev/null | grep -i h264
2. シーン境界でのキーフレーム抽出
重要な視覚的変化が発生するフレームのみを抽出します。これはビデオコンテンツをサンプリングする最も効率的な方法です。
# シーン変更でのフレーム抽出(しきい値0.3)
mkdir -p scenes
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)',showinfo" \
-vsync vfr \
scenes/scene_%04d.png \
2>&1 | grep showinfo
# タイムスタンプをファイルに記録して抽出
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)',showinfo" \
-vsync vfr \
scenes/scene_%04d.png \
2>&1 | grep "pts_time" > scenes/timestamps.txt
# シーンフレームをJPEGとして抽出(より小さいファイル、分析に適しています)
mkdir -p scenes
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)'" \
-vsync vfr \
-q:v 2 \
scenes/scene_%04d.jpg
3. 定期的な間隔でのフレーム抽出
コンテンツの変更に関係なく、均等にサンプリングが必要な場合。
# 1秒あたり1フレームを抽出
mkdir -p frames
ffmpeg -i input.mp4 -vf "fps=1" frames/frame_%04d.png
# 5秒ごとに1フレームを抽出
mkdir -p frames
ffmpeg -i input.mp4 -vf "fps=1/5" frames/frame_%04d.png
# Iフレームのみを抽出(コーデックからのキーフレーム)
mkdir -p keyframes
ffmpeg -i input.mp4 \
-vf "select='eq(pict_type,I)'" \
-vsync vfr \
keyframes/kf_%04d.png
# 特定のタイムスタンプで単一フレームを抽出
ffmpeg -i input.mp4 -ss 00:01:30 -frames:v 1 thumbnail.png
# 最初のフレームのみを抽出
ffmpeg -i input.mp4 -frames:v 1 first_frame.png
4. ffprobeを使用したビデオメタデータの分析
処理前にビデオプロパティを検査します。機械可読な結果には常にJSON出力を使用します。
# 完全なメタデータをJSONとして(ストリームとフォーマット)
ffprobe -v quiet \
-print_format json \
-show_format \
-show_streams \
input.mp4
# 長さのみを取得
ffprobe -v error \
-show_entries format=duration \
-of default=noprint_wrappers=1:nokey=1 \
input.mp4
# 解像度を取得
ffprobe -v error \
-select_streams v:0 \
-show_entries stream=width,height \
-of csv=s=x:p=0 \
input.mp4
# フレームレートを取得
ffprobe -v error \
-select_streams v:0 \
-show_entries stream=r_frame_rate \
-of default=noprint_wrappers=1:nokey=1 \
input.mp4
# コーデック情報を取得
ffprobe -v error \
-select_streams v:0 \
-show_entries stream=codec_name,codec_long_name,profile \
-of json \
input.mp4
# 総フレーム数をカウント
ffprobe -v error \
-count_frames \
-select_streams v:0 \
-show_entries stream=nb_read_frames \
-of default=noprint_wrappers=1:nokey=1 \
input.mp4
5. シーンの検出とタイムスタンプの一覧表示
フレームを抽出せずにシーン変更タイムスタンプのリストを取得します。
# シーン変更タイムスタンプの一覧
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)',showinfo" \
-f null - \
2>&1 | grep pts_time
# すべてのフレームのシーンスコアを抽出(分析用)
ffmpeg -i input.mp4 \
-vf "select='gte(scene,0)',metadata=print" \
-f null - \
2>&1 | grep "lavfi.scene_score"
# シーン変更の数をカウント
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)',showinfo" \
-f null - \
2>&1 | grep -c "pts_time"
6. オーディオ波形の抽出と無音の検出
オーディオトラックを分析して、無音ギャップ、音量レベル、視覚的な波形を確認します。
# 無音期間の検出(チャプター区切りを見つけるのに便利)
ffmpeg -i input.mp4 \
-af silencedetect=noise=-30dB:d=0.5 \
-f null - \
2>&1 | grep silence
# オーディオ波形を画像として生成
ffmpeg -i input.mp4 \
-filter_complex "showwavespic=s=1920x200:colors=blue" \
-frames:v 1 \
waveform.png
# 音量レベルの分析
ffmpeg -i input.mp4 \
-af volumedetect \
-f null - \
2>&1 | grep volume
# オーディオスペクトル可視化の抽出
ffmpeg -i input.mp4 \
-filter_complex "showspectrumpic=s=1920x512:color=intensity" \
-frames:v 1 \
spectrum.png
7. AIビジョン分析ワークフロー
フレームを抽出し、Claudeのビジョン機能で分析して、ビデオコンテンツから構造化情報を抽出します。
# ステップ1:ビデオをプローブ
ffprobe -v quiet -print_format json -show_format -show_streams input.mp4
# ステップ2:シーンフレームを抽出
mkdir -p analysis_frames
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.3)'" \
-vsync vfr \
-q:v 2 \
analysis_frames/frame_%04d.jpg
フレームを抽出した後、Readツールを使用して各画像を読み込みます。Readツールは画像ファイル(PNG、JPGなど)をサポートし、視覚的に提示します。各フレームについて、以下を分析します:
- 色:主要な16進数カラー値、背景色、アクセントカラーを抽出
- タイポグラフィ:フォントサイズ、ウェイト、行間、見出し階層を識別
- レイアウト:グリッドパターン、フレックスレイアウト、スペーシングのリズム、マージンを検出
- コンポーネント:ボタン、カード、ヘッダー、ナビゲーション、フォームを識別
- アニメーション状態:トランジション、ホバー状態、ローディングインジケーターを記録
すべてのフレームにわたる発見を集約して、一貫性のあるデザインシステムを構築します。
8. ビデオからのデザインシステム抽出
製品デモやUIウォークスルービデオからデザインシステムを抽出するための完全なワークフロー。
# ステップ1:ビデオ情報を取得
ffprobe -v quiet -print_format json -show_format input.mp4
# ステップ2:シーンフレームを抽出(各ユニークな画面をキャプチャ)
mkdir -p design_frames
ffmpeg -i input.mp4 \
-vf "select='gt(scene,0.4)'" \
-vsync vfr \
-q:v 1 \
design_frames/screen_%04d.png
# ステップ3:カバレッジのために定期的な間隔でも抽出
ffmpeg -i input.mp4 \
-vf "fps=1/3" \
-q:v 1 \
design_frames/interval_%04d.png
フレーム抽出後、各フレームをAIビジョンで分析して、以下をコンパイルします:
{
"colors": {
"primary": "#2563EB",
"secondary": "#7C3AED",
"background": "#FFFFFF",
"surface": "#F3F4F6",
"text": "#111827",
"textSecondary": "#6B7280"
},
"typography": {
"headingFont": "Inter",
"bodyFont": "Inter",
"scale": ["12px", "14px", "16px", "20px", "24px", "32px", "48px"]
},
"spacing": {
"unit": "8px",
"scale": ["4px", "8px", "12px", "16px", "24px", "32px", "48px", "64px"]
},
"components": ["button", "card", "navbar", "sidebar", "input", "modal"]
}
アンチパターン / よくある間違い
| 間違い | なぜ間違っているのか | 代わりにすべきこと |
|---|---|---|
| ビデオからすべてのフレームを抽出 | 数千のファイルを生成し、ディスクと分析時間を浪費する | シーン検出または固定間隔(1 fps以下)を使用する |
| 処理前にffprobeをスキップ | 未知のコーデックや破損ファイルがサイレントFFmpeg障害を引き起こす | 常に最初にプローブしてフォーマットとプロパティを検証する |
| バルクフレーム抽出にPNGを使用 | PNGファイルはJPEGより5〜10倍大きく、分析品質の向上は最小限 | 分析にはJPEG(-q:v 2)を使用。ピクセル正確な作業にのみPNGを使用 |
| シーンしきい値を低く設定しすぎる(0.1) | カメラの動き、照明の変化を捉え、フレームが多くなりすぎる | 0.3〜0.4から始め、結果に基づいて調整する |
selectフィルターで-vsync vfrを無視 | タイムラインのギャップを埋めるために重複フレームを生成 | selectフィルターを使用するときは常に-vsync vfrを使用する |
| タイムスタンプなしでフレームを分析 | 分析結果をビデオのタイムラインに関連付けることができない | showinfoフィルターを使用して各フレームでpts_timeをキャプチャする |
| 数百のフレームに対してAIビジョンを実行 | コンテキスト制限を超え、トークンを浪費する | 分析パスごとに10〜20の代表的なフレームに制限する |
| ffmpegパスをハードコーディング | OSとインストール方法によって動作が異なる | ffmpegとffprobeを直接、PATHに依存して使用する |
落とし穴
-
-vsync vfrは select フィルターで必須 --vsync vfrがないと、FFmpegは選択されたフレーム間の「欠落」フレームを重複で埋めて、一定のフレームレートを維持します。つまり、5つのシーン変更フレームを抽出しても、500の出力ファイルが生成される可能性があり、そのほとんどが重複です。selectフィルターは常に-vsync vfrと組み合わせて使用します。 -
シーン検出しきい値はコンテンツによって異なる - しきい値0.3はナラティブビデオのカットには適していますが、アニメーションコンテンツやスクリーンレコーディングでは、段階的なトランジションが低いシーンスコアを生成するため、0.4〜0.5が必要になる場合があります。抽出後のフレーム数を常に確認し、しきい値を調整します。
-
ffprobeのフレームカウントは遅い -
-count_framesをffprobeで使用すると、フレームを正確にカウントするためにビデオ全体をデコードします。長いビデオでは、これに数分かかる場合があります。代わりにストリームメタデータのnb_framesを使用するか(精度は劣るが即座)、長さとフレームレートから推定します。 -
オーディオ無音検出パラメータは調整が必要 - デフォルトの
-30dBノイズしきい値は、ほとんどのコンテンツで機能しますが、静かなパッセージ(ポッドキャストなど)では-40dBに調整する必要があり、アクション映画では-25dBに調整する必要があります。常にdパラメータを使用して最小無音時間を設定します(例:d=0.5は500ms)。 -
showinfoは唯一起こる - FFmpegがストリームの終わりに達すると、「フレーム数」の要約行を出力します。これはshowinfoの行やpts_timeの発生ではありません。
grep pts_timeは、シーン変更がない場合、正しい空の結果を生成します。ただし、grepに-cを使う場合、カウントにその要約行を含めないように注意してください。 -
画像読み込みにはディスク上のファイルが必要 - Claudeはstdinからの画像パイプをサポートしていません。AIビジョン分析の前に、まずFFmpegを使用してフレームをディスクに書き込む必要があります。
-f image2pipeでパイプしようとすると、Claudeが画像を読み込めないため機能しません。
環境変数
| 変数 | 説明 | デフォルト値 |
|---|---|---|
SCENE_THRESHOLD | 分析のデフォルトのシーン検出しきい値 | 0.3 |
FRAME_QUALITY | 抽出されたフレームのJPEG品質(1〜31、低いほど良い) | 2 |
MAX_ANALYSIS_FRAMES | AIビジョン分析に送信する最大フレーム数 | 20 |
ANALYSIS_WORKING_DIR | 抽出されたフレームのための一時ディレクトリ | ./analysis_frames |
FFMPEG_VERBOSE | 詳細なFFmpeg出力を有効にする(デバッグ用) | false |