video-scene-analyzer

動画シーンアナライザー

動画ファイル内のシーン境界を検出し、コンテンツの概要、制作タグ、各シーンのビジュアル素材ライブラリを含む構造化 JSON を生成します。

前提条件

ffmpeg と ffprobe が必要です。次のコマンドで確認してください。

ffmpeg -version && ffprobe -version

見つからない場合は、ユーザーに知らせて終了してください。

このスキルには、独自の videx スクリプトが scripts/videx（SKILL.md からの相対パス）に含まれています。完全なパスを解決してください。

VIDEX="$(dirname "$(realpath "<path-to-SKILL.md>")")/scripts/videx"

ワークフローの概要

2 段階のプロセスです。

1. パス 1 -- 概要：低解像度のフレームを抽出し、すべて確認して、シーン境界を特定します
2. パス 2 -- 詳細分析：シーンごとに高解像度のフレームを抽出し、詳細なメタデータを生成します
3. 出力：analysis.json と会話の要約を書き出します

パス 1：概要スキャン

ステップ 1：動画のメタデータを取得する

ffprobe -v error -show_entries format=duration,size -show_entries stream=codec_name,width,height,r_frame_rate -of default=noprint_wrappers=1 <video>

出力 JSON 用に、再生時間、解像度、fps を記録します。

ステップ 2：概要フレームを抽出する

再生時間に応じて間隔を選択します。

再生時間	間隔	コマンド
< 5 min	2s	$VIDEX overview <video> 2 320 0.5
5-30 min	5s	$VIDEX overview <video> 5 320 0.5
> 30 min	10s	$VIDEX overview <video> 10 320 0.5

トランジションを見やすくするため、triplet=0.5（間隔を広めに設定）を使用します。

ステップ 3：概要フレームをすべて確認する

Read ツールを使って、すべての _b（中央）フレームを時系列順に確認します。フレームが多い場合は、20～30 枚ずつに分けて確認してください。

_b フレームがトランジション（ぼかし、ブレンド、フェード）のように見えるタイムスタンプでは、_a と _c のフレームも確認します。

ステップ 4：シーン境界を検出する

連続する _b フレームを比較します。次の場合にシーン境界が存在します。

• ハードカット：連続するフレーム間で内容がまったく異なる
• ディゾルブ／フェード：フレームにブレンドや、黒／白へのフェードまたは黒／白からのフェードが見られる
• 大きな変化：被写体は同じでも、場所、アングル、構図が明らかに異なる

ヒューリスティック：迷った場合は、分割する方を優先してください。ユーザーはシーンを結合できますが、見逃した境界で分割することはできません。

境界ごとに次の情報を記録します。

• おおよそのタイムスタンプ（2 つのサンプルポイントの中間）
• トランジションの種類（cut、dissolve、fade-to-black、fade-from-black、fade-to-white、fade-from-white、wipe）

最初のフレームは常にシーン 1 の開始点です。最後のサンプルポイントが最終シーンの終了点です（動画の再生時間を使用します）。

ステップ 5：シーン一覧を提示する

続行する前に、ユーザーにシーン一覧を提示します。

Scene 1: 0:00 - 0:04 (cut)
Scene 2: 0:04 - 0:07 (dissolve)
...

境界を調整するか、このまま続行するかを尋ねます。

パス 2：シーンの詳細分析

ステップ 6：シーンのフレームを抽出する

各シーンについて、1280px で抽出します。

$VIDEX range <video> <start>-<end> --triplet=0.2

短いシーン（< 2s）：--fps=5 を追加します
長いシーン（> 30s）：デフォルトの 2fps で問題ありません。

ステップ 7：各シーンを分析する

そのシーンで抽出したフレームをすべて確認します。次の項目を判断します。

コンテンツの概要：2～4 文。被写体、動作、場所、小道具、見えているテキストを記述します。

制作タグ：

タグ	値
camera_angle	アイレベル、ローアングル、ハイアングル、俯瞰、ダッチアングル、オーバー・ザ・ショルダー、POV
shot_size	エクストリームワイド、ワイド、ミディアムワイド、ミディアム、ミディアムクローズアップ、クローズアップ、エクストリームクローズアップ
camera_movement	静止、左パン、右パン、上チルト、下チルト、ズームイン、ズームアウト、ドリーイン、ドリーアウト、トラッキング、手持ち、クレーン、ステディカム
color_tone	暖色、寒色、ニュートラル、低彩度、高コントラスト、低コントラスト、モノクロ、ネオン、パステル、アースカラー
lighting	自然光、人工光、ハイキー、ローキー、逆光、サイド光、トップ光、シルエット、混合光
tempo	静的、ゆっくり、中程度、速い、非常に速い

テキストオーバーレイ：

• placement：なし、ローワーサード、中央、上部、全画面、透かし
• content：実際に見えるテキスト、または null

トランジション：

• in：シーンの始まり方（最初のシーンは none）
• out：シーンの終わり方（最後のシーンは none）

シーンの途中でタグが変わる場合は、支配的な値を使用し、変化について notes に記録します。

ステップ 7b：アセットライブラリを作成する

シーンを分析しながら、動画全体に登場する個別のビジュアルアセットをすべて一覧にします。各アセットについて、以下を記録してください。

フィールド	説明
id	ケバブケースの一意な識別子（例：student-summer、logo-brand）
type	character、background、icon、ui-screen、photo、product、logo、decoration、text-graphic、effect
label	主な視覚的特徴を含む、人が読める1行の説明
style	anime-illustration、flat-design、realistic-photo、3d-render、hand-drawn、typography、mixed
appears_in	このアセットが登場するシーン番号の配列

ガイドライン：

• 衣装が変わるキャラクターは、それぞれ別の項目にします（例：student-summer、student-winter）
• 複数のシーンに同じアイコンが登場する場合は、すべてのシーン番号を記載して1項目にまとめます
• 特徴的な背景のみを記載します（一般的な白や黒の背景は省略します）
• label は簡潔にしつつ、アセットを特定できるだけの詳細（色、ポーズ、大きさ、見分ける特徴）を含めます

型の一覧と例については、references/schema.md を参照してください。

ステップ 8：analysis.json を作成する

references/schema.md のスキーマに従って、完全な JSON を作成します。

保存先：./videx-out/<video-name>/analysis.json

ステップ 9：会話の要約

JSON の作成後、以下を提示してください。

1. シーンの総数と動画の長さ
2. タイムスタンプ付きの各シーンの1行要約
3. アセットライブラリの概要（合計数、種類別の内訳）
4. 動画全体で注目すべき制作パターン

エッジケース

• 10秒未満：1秒間隔を使用します。シーンが1つでも問題ありません。
• 1時間超：10秒間隔を使用します。概要フレームは複数のバッチに分けて読み取ります。
• 静的コンテンツ（スライドショー／画面録画）：スライドの切り替わりをシーンの境界とします。camera_movement: static と記録します。
• 境界が曖昧な場合：結合するよりも分割を優先します。

出力先

./videx-out/<video-name>/
├── overview/          (Pass 1)
├── range_*/           (Pass 2)
└── analysis.json      (final output)