Vidgrid — eyes for video

vidgrid

将视频片段转换为带标注的图像网格，用于视觉大模型分析。 默认情况下，一个单元格 = 一秒。

大模型无法观看视频，但可以分析单张图像。vidgrid 每秒从视频中采样一帧，将其拼成带编号和时间戳的故事板，还可以选择将结果连同提示词发送给 Claude、GPT 或 Gemini。只需上传几张图像，就能获得近似于“我的大模型刚刚看完一段视频”的效果。

工作原理

默认情况下，一个单元格 = 一秒。 自动选择器会挑选能让网格数量保持在 --max-boards（默认为 10）以下的最小网格（单元格最大、最易读）。如果长视频无法满足要求，就会增大网格；作为最后手段，会降低采样率。可使用 --fps 和 --max-boards 进行全面控制。

• 网格大小决定一张图片能容纳多少秒的视频
• 默认采样率为 1fps；只有在需要将网格数量控制在上限以内时，才会降至 1fps 以下
• 时长超过 5 分钟的视频会被拒绝（请先将其剪成较短片段）

网格	单元格数	每张图片的秒数	适用场景
2x2	4	4	非常短的视频片段（2–4 秒）
3x3	9	9	默认值 — 整体可读性最佳
4x4	16	16	更紧凑，但单元格更小
5x5	25	25	实验性选项 — 单元格较小，大模型准确率会下降

网格越大，质量越差。 单元格会变小，细节会丢失，大模型也更难识别文字或 UI 元素等精细内容。除非你确实需要在一张图片中塞入更多秒的视频，否则建议使用 3×3。5×5 基本上只是一个“看看会怎样”的选项。

视频会生成多少张图片

在 1fps 采样时，各种网格大小对应的网格数量：

视频时长	2×2	3×3	4×4	5×5
3 秒	1（不完整）	1（不完整）	1（不完整）	1（不完整）
9 秒	3	1	1（不完整）	1（不完整）
25 秒	7	3	2	1
60 秒	15	7	4	3
186 秒（3 分钟）	47	21	12	8
300 秒（5 分钟，上限）	75	34	19¹	12

粗体 = auto 的选择结果——在使网格数量低于 --max-boards（默认为 10）的前提下，选择最小的网格（单元格最大）。

¹ 在 5 分钟上限处，即使使用 4×4 网格，1fps 采样也会产生超过 10 个网格，因此自动模式会降低采样率（约每 1.9 秒采样 1 个单元格），以达到 10 个网格的限制。使用 --fps 1.0 --max-boards 20 可保持 1fps 采样，并接受更多网格。

大多数视觉大模型单次请求可接受约 10–20 张图像，因此自动模式默认的上限为 10，可让完整视频通过一次模型调用处理。

安装

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+，并且 ffmpeg 必须位于 PATH 中。

快速开始

# 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

你可以用它做的三件事

1. 不看视频也能总结演讲内容

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

vidgrid 每秒采样一帧，使用 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 发送给 Claude，并让它根据镜头清单为视频片段排序或筛选。这正是 vidgrid 构建出来要实现的工作流。

竖屏与横屏

无论源视频的方向如何，vidgrid 都会保持网格为正方形（N×N）， 并保留每个单元格内源视频的宽高比。横屏源视频会生成宽幅拼图；竖屏源视频会生成高幅拼图。单元格绝不会被裁切。

双层字幕（默认）

默认模式会为大模型提供两种相关输入：渲染后的网格图像，以及单独的 Whisper 转录文本。模型会根据每个单元格上显示的时间戳将两者关联起来。

这比把字幕直接烧录到图像中更好，因为：

1. 帧的像素可以保留给实际内容
2. 文本以词元形式呈现，比烧录成像素保真度更高
3. 网格保持整洁，便于分享

如果需要独立的图像（适合分享或离线分析），可添加 --burn-captions。

字幕文件格式

vidgrid 可读取和写入三种字幕格式。--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（纯文本时间戳，每行一个单词）：

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 的单元格， 这样大模型就能无歧义地引用任意帧。

限制与注意事项

• 视频时长硬性上限为 5 分钟。 超出时长的视频会被拒绝。可使用 ffmpeg -ss START -t 300 input.mp4 chunk.mp4 将视频切分。
• 不进行场景检测。 v1 严格按每秒 1 帧均匀采样。不去重、不偏移——间隔始终正好为 1 秒。
• 可变帧率视频可能存在不足一帧的定位偏差（≤1 帧），对于 1fps 采样来说可以接受。
• 网格越大，可读性越差。 5×5 网格的单元格宽约 300px；显示人物和物体尚可，但显示密集文本或代码时效果一般。建议使用 3×3。
• 大模型集成使用官方 SDK（anthropic、openai、google-genai），除非你通过 extras 主动请求，否则不会安装。

相关项目

• IG-VLM — 证明网格方法可行的研究论文
• llm-video-frames — Simon Willison 的逐帧方法
• vcsi — 不使用大模型的联系表生成工具
• byjlw/video-analyzer — whisper + 顺序帧

vidgrid 的差异化特点：1 个单元格 = 1 秒、单元格带编号、简单的命令行、 一个包中集成多家大模型提供商。

许可证

MIT。随附的 Source Sans 3 字体根据 SIL OFL 1.1 许可。