Squish

@getsquish/squish

让 AI 随机访问视频。概览、缩放、引用。 Squish 不会强迫模型从头到尾观看片段，而是将连续视频转换为可寻址的视觉 + 音频活动图——一种 Agent 可以浏览、重访并逐步细化的地图。带时间戳的联系表是这一原语的首个实现：由帧组成的网格，每个单元格都标有绝对时间码，并与同一时间线对齐的全局归一化音频活动带。活动带显示的是能量，而非含义：不提供转录、声音分类或情绪推断。所有操作都在你的机器上运行——一次调用即可取代整个 download → ffmpeg → extract → montage 工作流，即使你有 shell，也建议优先使用它。还可通过托管连接器在 Claude Desktop / claude.ai 中使用：添加 https://api.getsquish.app/mcp，无需安装——此方式会在 Squish 服务端处理你提供的公开视频 URL，而非本地处理（远程 MCP 文档，隐私说明）。由 getsquish.app 的创作者打造。

Agent 不会消费视频——它们会浏览视频。 实际运行示例：通过检索34 帧，而非 3,088 帧（概览 → 缩放 → 再缩放），将一个场景切换锁定到 0.2 秒。一天内在 5 个客户端和 3 种口述方式中实测验证——Claude Desktop 自行完成了多轮循环，精确到亚秒级，无需预先教授。

演示本身就是这个原语。 一段介绍联系表的 76 秒视频——以及同一段视频作为一张联系表呈现。一个需要点击播放按钮；另一个只需阅读：

▶ 观看 — 76 秒，线性播放

阅读 — 一张表，随机访问

为什么有效

AI 通过镜头观察，而非直接获得答案——Squish 调整镜头，模型负责解读。 视频是连续的；推理是稀疏的。大多数问题只涉及时间线中的一小部分。Squish 将时间线转换为可寻址的地图，让 Agent 检索所需的视觉证据，而不必重放所有内容——联系表不是输出，而是导航层。音频活动可以帮助找出视觉上相似的帧之间的候选时间段；最终仍由帧决定发生了什么。窗口（start/end）是可调宽窄的镜头；密度是可调粗细的镜头；循环则是不断移动镜头，直到答案清晰可见。

安装

npm install -g @getsquish/squish     # or one-shot: npx -y @getsquish/squish <video>

要求： Node ≥ 20 · ffmpeg + ffprobe 必须位于 PATH 中 （macOS brew install ffmpeg · Ubuntu sudo apt-get install ffmpeg）。

用你熟悉的视频试试

准备一段你已经知道答案的视频片段。让 AI 找出一个具体时刻，但不要把原始视频给它：

1. 运行 npx -y @getsquish/squish clip.mov --json。
2. 将返回的图表交给视觉模型，并提出一个关于时间的问题：门什么时候打开？物体第一次出现是什么时候？异常音频活动出现在哪里，附近的帧显示了什么？
3. 让模型根据帧时间码或音频频段选择一段可疑范围。
4. 再次运行 Squish，使用 --start / --end，然后对照源视频片段验证答案。

索引提供线索；放大的视觉证据予以确认。音频频段可以定位活动，但无法告诉你说了什么或是什么发出了声音。

OpenAI Build Week 2026

Build Week 扩展为 Squish 现有的导航循环添加了音频引导的候选片段选择功能。活动开始前，Squish 已能生成带时间戳的联系表，并支持按绝对时间使用 start/end 缩放。Build Week 添加了覆盖整个片段的归一化音频活动频段、绝对时间的 audio.samples[]、瞬态／高频保留功能、测试，以及利用该信号决定接下来应检查哪些画面的 Agent 工作流。

演示将两层证明分别呈现：

• 叙事证明： 展示经所有者授权的私人摄像头视频片段及相关凭证，但不分发源视频片段。
• 可复现证明： 公开仓库包含生成的样例及其源文件，位于 examples/audio-navigation/。

git clone https://github.com/getsquish/squish.git
cd squish
./examples/audio-navigation/generate-sample.sh
npx -y @getsquish/[email protected] examples/audio-navigation/sample.mp4 --json --out /tmp/squish-overview
npx -y @getsquish/[email protected] examples/audio-navigation/sample.mp4 \
  --density 6x6 --start 11.5 --end 13.5 --json --out /tmp/squish-zoom

概览中的活动频段提供邻近范围线索。密集视觉图表确认了那个短暂出现的粉色标记。公开版 0.3.1 在整个源视频片段中使用同一个参考尺度；它不会让不同文件的音量级别具有全局可比性。

CLI

squish clip.mov                       # sheets land beside the input
squish clip.mov --density 5x5 --json  # denser grid + machine-readable output
squish clip.mov --start 1:00 --end 1:30 --density 5x5   # zoom into a range

输出：<basename>.sheet-N.jpg —— 带时间码的帧网格，上方有一条细窄的音频活动频段。默认密度为 3×3，可还原发生了什么；4x4–6x6 可还原如何发生。--out <dir> 用于选择目标位置。没有音轨的视频仍可正常处理，并会标记为 NO AUDIO TRACK。

--start / --end 接受秒数（90），也接受与图表标注完全一致的时间码（1:30、1:07.3），并将运行范围限定在该区间内。时间码始终相对于源视频的绝对时间，因此可以反复缩放：概览 → 找到一段范围 → 使用 --start/--end 重新运行 → 获取更精细的时间码 → 再次深入查看。短时间窗口会标注亚秒级时间码（1:07.3），以便区分相邻单元格。

使用 --json 时，stdout 是一个对象（固定契约——解析 contract 以检测不兼容变更）：

{
  "input": "/abs/path/clip.mov",
  "duration": 20.275,
  "frames": 9,
  "sheets": 1,
  "files": ["/abs/path/clip.sheet-1.jpg"],
  "audio": {
    "present": true,
    "normalization": "clip_peak",
    "window": { "start": 0, "end": 20.275 },
    "samples": [
      { "time": 0.106, "level": 0.08 },
      { "time": 0.317, "level": 1 }
    ]
  },
  "warnings": [],
  "contract": "squish-cli-v0"
}

示例缩短了 audio.samples；实际输出会为每张图表生成等间隔的活动包络。样本时间是源视频中的绝对秒数。级别范围为 0..1，按整个片段中的峰值归一化，包括窗口化运行，因此不同缩放范围仍可比较。退出码 0 表示成功 · 1 表示失败（消息写入 stderr）。临时帧始终会清理。窗口化运行还会在 duration 后回显 "window": { "start": …, "end": … }（解析后的边界，单位为秒）；未请求窗口时则不包含该键。

MCP 服务

squish mcp        # stdio server

一个工具，squish_video —— { video_path, density?, start?, end?, out_dir? } → CLI 契约（包括 audio），并额外包含 timecodes[][]（每张图表中的每一帧对应一个时间码；短窗口使用 m:ss，亚秒级时使用 m:ss.d），标记为 "contract": "squish-mcp-v0"。start/end 接受秒数或图表时间码，并用于驱动下方的导航循环。

可与 Claude Code、Claude Desktop、Cursor、Hermes 以及任何 stdio MCP 客户端配合使用：

{
  "mcpServers": {
    "squish": { "command": "npx", "args": ["-y", "@getsquish/squish", "mcp"] }
  }
}

远程 MCP — 官方 AI 应用，无需安装

通过网络使用同一工具，适用于只接受连接器 URL 的客户端： Claude Desktop / claude.ai → Settings → Connectors → Add custom connector → https://api.getsquish.app/mcp。该端点会获取公开的 video_url（不使用共享文件系统），返回有效期约 24 h 的表格链接，并内嵌第一张表格；start/end 的作用与本地工具完全相同。

无密钥调用使用小规模匿名免费通道；添加 Authorization: Bearer API 密钥（与托管 API使用相同的密钥和额度，可在 getsquish.app/api-keys 创建），即可解锁按额度计费的任务，并在每个结果中查看额度。任何能发送该请求头的客户端都可使用密钥——Claude Code、mcp-remote、SDK 客户端，或由组织管理员将密钥附加为请求头的 Claude Team/Enterprise 连接器；消费者连接器对话框仅支持 OAuth。完整参考：远程 MCP 文档。

导航循环

1. 概览 — 调用 squish_video（MCP）或 squish clip.mov --json（CLI），并使用视觉能力查看表格。单元格按时间顺序排列：从左到右、从上到下。
2. 导航 — 找出重要区域；每个单元格都带有绝对时间码。将音频峰值视为候选区间，而非对声音来源的判断。
3. 缩放 — 仅在仍有不确定性的地方，根据找到的时间码设置 start/end 再次调用：对更窄的时间窗口生成更密集的表格，地址仍为绝对地址。
4. 重复，直到答案可以直接观察到——如果只需关注一个范围，就不要以高密度重新读取整个片段。
5. 引用绝对时间戳（“在 0:07 时，压机落下”）。

隐私

CLI 和本地 MCP 服务会在你的设备上处理所有内容——绝不会上传任何内容，而且所有密度均免费。以下两种方式会有意通过 Squish 传输媒体：托管 API（需主动上传，使用预付额度；从未购买过的账户每天可免费使用一定额度）和远程 MCP 端点（服务会获取你的公开 video_url；任务结束时删除源文件，表格约 24 h 后过期）。

本地 CLI/MCP 软件包提供音频活动信息。这是 RMS 风格的能量包络，不提供音频播放、转录、说话人分离、声音识别或情绪推断。在各自的发行说明另有说明之前，Web 应用、托管 API 和远程 MCP 均仅支持视觉处理。

---

此存储库

这是引擎——Squish 的 CLI + MCP 接口，以 @getsquish/squish 的名称发布到 npm。这是从私有单体仓库精选并优先镜像导出的版本（私有单体仓库仍是唯一真实来源）；此处的历史从首次公开发布开始。有关变更流程，请参阅 CONTRIBUTING.md。

本存储库有意不包含以下内容：

• getsquish.app Web 应用（PWA）——使用相同的核心规划器，浏览器作为操作界面；
• 托管 API（api.getsquish.app）及其远程 MCP 端点（/mcp，官方应用连接器）——付费通道：主动上传 / 服务获取 URL、预付额度、未付费账户每天可免费使用一定额度，以及连接器的小规模匿名免费通道；
• 品牌素材——Squish 名称、徽标、吉祥物和 OG 图片均为保留资产。

src/            CLI (main/args) · engine (probe → plan → extract → compose → write) · MCP server · sheet renderer
src/core/       pure planners shared with the web app: density · sampling · grid layout · timecode format
tests/          node:test suite + a real-MCP-client e2e
skills/         agent skills — `npx skills add getsquish/squish` installs video-navigation

许可证

Apache-2.0（附带 NOTICE）。Squish 名称、徽标、吉祥物和 getsquish.app 品牌素材不受本存储库许可。