Squish

@getsquish/squish

AI に動画をランダムアクセスさせます。概要を把握し、拡大し、引用できます。 モデルにクリップを最初から最後まで見せる代わりに、Squish は連続した動画を、エージェントが移動し、再確認し、段階的に精度を高められる アドレス可能な視覚＋音声アクティビティマップ に変換します。この基本機能の 最初の実装 が、タイムスタンプ付きコンタクトシートです。各セルに絶対タイムコードを表示したフレームのグリッドと、同じタイムラインにそろえた、グローバルに正規化された音声アクティビティ帯で構成されます。この帯が示すのはエネルギーであり、意味ではありません。文字起こし、音の分類、感情の推定は行いません。すべてお使いのマシン上で動作します。また、1 回の呼び出しで、ダウンロード → ffmpeg → 抽出 → モンタージュという一連の処理を置き換えられるため、シェルが使える場合でもこちらをお使いください。ホステッドコネクター経由で Claude Desktop / claude.ai でも動作します。https://api.getsquish.app/mcp を追加するだけで、インストールは不要です。ただし、この方法では公開動画 URL をローカルではなく Squish のサーバーで処理します（リモート MCP のドキュメント、プライバシーの違い）。getsquish.app の開発チームがお届けします。

エージェントが動画を消費するのではなく、動画の中を移動します。 実際の実行例：概要 → 拡大 → 拡大の手順で、3,088 フレームではなく 34 フレームを取得し、シーンの切り替わりを 0.2 秒の精度で特定しました。1 日で 5 つのクライアントと 3 つの音声モデルを使って実証済みです。Claude Desktop は教えられることなく、自ら複数ラウンドのループを完了し、1 秒未満の精度で特定しました。

デモは、この基本機能そのものです。 コンタクトシートについて解説する 76 秒の動画と、同じ動画を 1 枚のコンタクトシートにしたものです。片方は再生ボタンが必要ですが、もう片方は読むだけです。

▶ 視聴 — 76 秒、直線的

読む — 1 枚のシートでランダムアクセス

これが機能する理由

AI は答えではなくレンズを通して見る — Squish がレンズを調整し、モデルが解釈します。 動画は連続的ですが、推論はまばらです。多くの質問が対象とするのは、タイムラインのごく一部です。Squish はタイムラインをアドレス可能なマップに変換するため、エージェントはすべてを再生する代わりに、必要な視覚的証拠を取得できます。コンタクトシートは出力ではなく、ナビゲーションレイヤーです。音声アクティビティから、見た目が似たフレーム間の候補区間を見つけられる場合がありますが、何が起きたかを判断するのはあくまでフレームです。ウィンドウ（start／end）は広げたり狭めたりするレンズ、密度は粗くしたり細かくしたりするレンズ、ループは答えが観察できるまで動かすレンズです。

インストール

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

要件： Node ≥ 20 · PATH 上に ffmpeg と ffprobe があること （macOS の場合は brew install ffmpeg · Ubuntu の場合は sudo apt-get install ffmpeg）。

見慣れた動画で試す

答えをすでに知っているクリップを用意します。元の動画を渡さずに、AI に特定の瞬間を探すよう依頼します。

1. npx -y @getsquish/squish clip.mov --json を実行します。
2. 返されたシートをビジョンモデルに渡し、タイミングに関する質問をします。ドアが開くのはいつですか？物体が初めて現れるのはいつですか？異常な音声活動があるのはどこで、その付近のフレームには何が映っていますか？
3. フレームのタイムコードまたは音声帯をもとに、モデルに疑わしい範囲を選ばせます。
4. --start / --end を指定して Squish を再実行し、元のクリップと照合して答えを確認します。

インデックスが候補を示し、拡大した視覚的証拠がそれを裏付けます。音声帯から活動の場所は特定できますが、何が話されたのか、何が音を立てたのかは分かりません。

OpenAI Build Week 2026

Build Week の拡張機能では、Squish の既存のナビゲーションループに、音声を手がかりとした候補選択が追加されました。イベント前の Squish は、すでにタイムスタンプ付きのコンタクトシートを生成し、絶対時間での start/end 拡大に対応していました。Build Week では、動画全体の正規化された音声活動帯、絶対時間の audio.samples[]、トランジェント／高周波の保持、テスト、および次にビジョンで調べる場所を信号から判断するエージェントのワークフローが追加されました。

デモでは、2 つの証拠レイヤーを分けています。

• **ナラティブの証拠：**所有者の許可を得た非公開のカメラ映像を、証拠とともに提示しますが、元の映像は配布しません。
• **再現可能な証拠：**公開リポジトリには、生成されたフィクスチャとそのソースが 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 秒未満のタイムコード（1:07.3）が表示されるため、隣接するセルを区別できます。

--json を指定すると、標準出力に 1 つのオブジェクトが出力されます（固定されたコントラクトです。互換性を損なう変更を検出するには 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（メッセージは標準エラー出力）です。一時フレームは必ずクリーンアップされます。範囲を指定した実行では、duration の後に "window": { "start": …, "end": … }（解決済みの境界、秒数）も出力されます。範囲を指定していない場合、このキーはありません。

MCP サーバー

squish mcp        # stdio server

ツールは 1 つ、squish_video — { video_path, density?, start?, end?, out_dir? } → CLI コントラクト（audio を含む）に加えて timecodes[][]（各シートの各フレームに 1 つ。短い範囲では m:ss、1 秒未満なら 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時間有効なシートリンクと、インライン表示された最初のシートを返します。また、start／end はローカルツールと同じように動作します。

キーなしの呼び出しは、小規模な匿名の無料枠を利用します。ホステッド APIと同じキーとクレジット（getsquish.app/api-keysで発行）を使う Authorization: Bearer API キーを指定すると、クレジット制のジョブを利用でき、すべての結果でクォータを確認できます。ヘッダーを送信できるあらゆるクライアントでキーを使用できます。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 サーバーは、すべての処理をお使いのマシン上で行います。何もアップロードされず、すべての密度設定が無料です。次の2つの方法では、意図的にメディアを Squish 経由で処理します。ホステッド API（意図的なアップロード、前払いクレジット、購入履歴のないアカウント向けの毎日の無料枠あり）と、リモート MCP エンドポイント（サーバーが公開された video_url を取得し、ジョブ完了時に元ファイルを削除します。シートは約24時間後に期限切れになります）です。

音声のアクティビティは、ローカル CLI／MCP パッケージで利用できます。これは RMS 形式のエネルギー包絡線であり、音声再生、文字起こし、話者分離、音の認識、感情推定には対応していません。ウェブアプリ、ホステッド API、リモート MCP は、それぞれのリリースノートで別途発表されるまでは、映像のみを扱います。

---

このリポジトリについて

これはエンジンで、Squish の CLI と MCP のインターフェースです。npm では @getsquish/squish として公開されています。非公開モノレポ（引き続き唯一の正本）から厳選してミラー優先でエクスポートされており、ここでの履歴は最初の一般公開リリースから始まります。変更の流れについては、CONTRIBUTING.mdをご覧ください。

意図的にこのリポジトリに含まれていないもの：

• getsquish.app のウェブアプリ（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 のブランドアセットは、このリポジトリのライセンス対象ではありません。