Vidgrid — eyes for video

vidgrid

動画クリップを注釈付きの画像グリッドに変換し、ビジョン LLM で分析できます。 デフォルトでは、1 セル = 1 秒です。

LLM は動画を視聴できませんが、1 枚の画像なら分析できます。vidgrid は動画から毎秒 1 フレームをサンプリングし、タイムスタンプ付きの番号入りストーリーボードにタイル状に配置します。さらに、必要に応じて結果を Claude、GPT、Gemini にプロンプトとともに送信できます。少数の画像をアップロードするだけで、「LLM が動画を見た」ような体験が得られます。

モデル

デフォルトでは、1 セル = 1 秒です。 自動選択機能は、ボード数が --max-boards（デフォルトは 10）以下に収まる最小のグリッド（セルが最も大きく、最も読みやすいもの）を選びます。長いクリップでそれだけでは足りない場合はグリッドを大きくし、最後の手段としてサンプリング頻度を下げます。--fps と --max-boards で細かく設定できます。

• グリッドサイズによって、1 枚の画像に収まる秒数が決まります
• デフォルトのサンプリングは 1fps です。ボード数を上限以下に保つ必要がある場合にのみ、1fps 未満に下げます
• 5 分を超える動画は拒否されます（先に分割してください）

グリッド	セル数	画像 1 枚あたりの秒数	おすすめの用途
2x2	4	4	非常に短いクリップ（2～4 秒）
3x3	9	9	デフォルト — 全体的に最も読みやすい
4x4	16	16	よりコンパクトですが、セルは小さくなります
5x5	25	25	実験的 — セルが小さく、LLM の精度が低下します

グリッドを大きくすると品質が低下します。 セルが小さくなり、細部が失われ、テキストや UI 要素のような細かな内容を LLM が読み取りにくくなります。1 枚の画像により多くの秒数を詰め込む必要がある場合を除き、3×3 を使ってください。5×5 は主に「試すとどうなるか見てみよう」という用途のオプションです。

動画から生成される画像の枚数

1fps でサンプリングした場合の、各グリッドサイズでのボード数です。

動画の長さ	2×2	3×3	4×4	5×5
3s	1（一部）	1（一部）	1（一部）	1（一部）
9s	3	1	1（一部）	1（一部）
25s	7	3	2	1
60s	15	7	4	3
186s（3 分）	47	21	12	8
300s（5 分、上限）	75	34	19¹	12

太字 = auto が選ぶグリッド（ボード数を --max-boards（デフォルトは 10）以下に保てる、最小のグリッド、つまりセルが最も大きいもの）です。

¹ 5 分の上限では、1fps のままだと 4×4 でもボード数が 10 を超えるため、auto はサンプリング頻度を下げ（約 1.9 秒に 1 セル）、ボード数を 10 枚以内に収めます。1fps を維持してボード数が増えることを許容するには、--fps 1.0 --max-boards 20 を使用してください。

ほとんどのビジョン LLM は 1 リクエストあたり約 10～20 枚の画像を受け入れるため、auto のデフォルト上限である 10 枚なら、動画全体を 1 回のモデル呼び出しで処理できます。

インストール

pip install vidgrid                         # core renderer only
pip install vidgrid[transcribe]             # + faster-whisper for --transcribe
pip install vidgrid[anthropic]              # + Claude support via --ask
pip install vidgrid[llm]                    # + Claude + GPT + Gemini
pip install vidgrid[all]                    # everything

Python 3.9 以上と、PATH に設定された ffmpeg が必要です。

クイックスタート

# 1. Auto-pick grid and sampling rate — smallest grid that fits in 10 boards
vidgrid clip.mp4 -o grid.png

# 2. Force a specific grid
vidgrid clip.mp4 -o grid.png --grid 4x4

# 3. Force a sampling rate — 0.5fps = 1 cell every 2 seconds
vidgrid long-clip.mp4 -o grid.png --fps 0.5

# 4. Raise the max-boards ceiling (default 10) if you want more boards
vidgrid lecture.mp4 -o grid.png --max-boards 20

# 5. Render + auto-transcribe + send to Claude in one call
vidgrid lecture.mp4 --transcribe --ask "bullet-point summary"

# 6. Use existing Whisper captions, burn them onto the grid
vidgrid interview.mp4 -o grid.png --captions whisper.json --burn-captions

# 7. Let the CLI fall back to python -m if the console script isn't on PATH
python3 -m vidgrid clip.mp4 -o grid.png

できること 3 つ

1. 動画を見ずに講演を要約する

vidgrid "team-meeting.mp4" \
  --transcribe \
  --ask "list the decisions made and who owns each" \
  --model claude-opus-4-7

vidgrid は毎秒 1 フレームをサンプリングし、音声に Whisper を実行して、グリッドと文字起こしを Claude に送信し、回答を出力します。モデルは焼き込み済みのタイムスタンプを使って、フレームと単語を関連付けます。

2. 画面録画から特定の場面を見つける

vidgrid bug-repro.mp4 --grid 3x3 \
  --ask "at which numbered frame does the error dialog appear?" \
  --model gpt-5

セルには全体を通した番号（1、2、3...）とタイムスタンプが付いているため、モデルは該当する場面を正確に示せます。シークする必要はありません。

3. 大量のストック映像をランク付けする

for clip in broll/*.mp4; do
  vidgrid "$clip" -o "grids/$(basename $clip .mp4).png"
done

PNG を 1 回のリクエストで Claude に送信し、ショットリストに照らしてクリップをランク付けしたり、除外したりするよう依頼します。これは vidgrid が想定して作られたワークフローです。

縦向きと横向き

vidgridは、ソースの向きにかかわらずグリッドの形状を正方形（N×N）に保ち、 各セル内ではソースのアスペクト比を維持します。横向きのソースでは横長のボードが、 縦向きのソースでは縦長のボードが生成されます。セルが切り抜かれることはありません。

2層キャプション（デフォルト）

デフォルトモードでは、LLMに相関する2つの入力を渡します。レンダリングされた グリッド画像と、別個のテキストとしてのWhisper文字起こしです。モデルは各セルに 表示されたタイムスタンプを通じて、これらを関連付けます。

キャプションを画像に焼き込むよりも優れている理由は次のとおりです。

1. フレームのピクセルを実際のコンテンツに使えます
2. テキストは、画像に焼き込まれたピクセルよりもトークンとして忠実度が高くなります
3. グリッドが見やすく、共有しやすい状態に保たれます

自己完結型の画像が必要な場合（共有やオフライン分析に便利です）は、 --burn-captions を追加してください。

キャプションファイル形式

vidgridは3種類のキャプション形式を読み書きできます。--captions フラグは ファイル拡張子から形式を自動判別します。--transcript-format フラグは --transcribe の出力形式を指定します。

形式	拡張子	サイズ（36語）	用途
json	.json	約4.8 KB	Remotionパイプライン、単語ごとの信頼度が必要なツール
srt	.srt	約1.4 KB	動画編集ソフト、汎用字幕形式
txt	.txt	約0.4 KB	最小サイズ、grepしやすく、解析も簡単

JSON（デフォルト、Remotion互換）：

[
  {"text": "hello", "startMs": 0, "endMs": 500, "timestampMs": 0, "confidence": 0.98},
  ...
]

SRT（SubRip字幕）：

1
00:00:00,000 --> 00:00:00,500
hello

2
00:00:00,500 --> 00:00:01,000
world

TXT（タイムスタンプ付きのプレーンテキスト、1行に1語）：

0.00 hello
0.50 world

どの形式も入力、出力、またはその両方に使用できます。形式を組み合わせることもできます。 --captions foo.srt --transcript-format txt を指定すると、.srt を読み込んで .txt に書き出せます。

Python API

from vidgrid import render

storyboard = render(
    input_path="interview.mp4",
    output_path="grid.png",
    grid="3x3",  # or "2x2", "4x4", "5x5", or None for auto
    transcribe=True,
)

print(storyboard.board_paths)        # ['grid-1.png', 'grid-2.png', ...]
print(storyboard.transcript_path)    # 'grid-transcript.json'
print(storyboard.all_samples)        # list[Sample] with timestamps

モジュール：vidgrid.probe、vidgrid.sample、vidgrid.compose、 vidgrid.captions、vidgrid.llm、vidgrid.presets。

出力構成

単一ボードの実行：

grid.png                 # the storyboard
grid.json                # sidecar: timestamps, layout, source info
grid-transcript.json     # only if --transcribe or --captions was used

複数ボードの実行：

grid-1.png, grid-2.png, grid-3.png, ...
grid.json                # index covering all boards + global cell numbering
grid-transcript.json

セル番号は、ボードをまたいで通し番号になります。3ボードの実行ではセル番号が1～27となるため、 LLMはどのフレームも曖昧さなく参照できます。

制限事項と注意点

• 動画の長さは最大5分です。 それより長い動画は拒否されます。 ffmpeg -ss START -t 300 input.mp4 chunk.mp4 を使って分割してください。
• シーン検出はありません。 v1では常に1秒あたり1フレームを均等にサンプリングします。 重複排除やずらしは行わず、間隔は常に正確に1秒です。
• 可変フレームレートの動画では、フレーム未満のシークずれ（≤1フレーム）が 発生する場合がありますが、1 fpsのサンプリングでは問題ありません。
• グリッドが大きいほど読みやすさが損なわれます。 5×5グリッドではセルの幅が約300pxになり、 人物や物体には十分ですが、細かなテキストやコードにはやや不向きです。3×3をおすすめします。
• LLM連携には公式SDK（anthropic、openai、google-genai）を使用しており、 追加機能として指定しない限りインストールされません。

先行事例

• IG-VLM — グリッド方式の有効性を示した研究論文
• llm-video-frames — Simon Willisonによるフレーム単位のアプローチ
• vcsi — LLMを使わないコンタクトシート作成ツール
• byjlw/video-analyzer — whisperと連続フレームを使用

vidgridの差別化ポイント：1セル＝1秒、番号付きセル、シンプルなCLI、 1つのパッケージで複数プロバイダーのLLM連携に対応。

ライセンス

MIT。バンドルされているSource Sans 3フォントは、SIL OFL 1.1の下でライセンスされています。