vidin

vidin

動画を、コーディングエージェントが実際に読み取れる形式に変換します。

Claude Code、Codex などが受け付けるのは画像であり、動画ではありません。そのため、画面録画で届いたバグ報告は、誰かが動画を見て、何が起きたかを手入力するまで活用できません。vidin は代わりに動画を分析し、注釈付きのキーフレームとテキストによるタイムラインに変換して、MCP 経由でエージェントに提供します。

20秒の録画から、6枚のフレームを出力します。返金パネル、500ダイアログ、再試行トースト、復旧の各場面を枠で囲み、タイムスタンプを付けます。（この動画はvidinの合成テスト用データです。）

• 1秒に1フレームではなく、イベント駆動です。 画面が変化し、その後静止したタイミングでフレームを保持します。誰かが3分間画面を読んでいても、コストはほとんどかかりません。実際のUIイベントはすべて記録されます。
• 高速です。 1080pの3分間の録画を、MシリーズのMacで約4秒で処理します。1時間の動画でも、必要なのは時間だけで、RAMはほとんど必要ありません。
• 実行は1コマンドです。 npx @teunlao/vidin — マシンに必要なのはffmpegだけです。sharp、ヘッドレスブラウザー、ネイティブ画像ライブラリは不要です。
• エージェントのコンテキストに合わせています。 MCPツールは最初にテキストレポートとコンタクトシートを返し、重要だと判明した場面だけ詳細なフレームを返します。
• シークできるタイムスタンプです。 エージェントが「エラーは00:41.2に表示されます」と伝えれば、元のファイルですぐにその場面に移動できます。

クイックスタート

brew install ffmpeg        # + yt-dlp, only if you'll pass URLs

Claude Codeに組み込みます。

claude mcp add vidin -- npx -y @teunlao/vidin mcp

または、.mcp.json / ~/.codex/config.tomlに相当する設定を使います。

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

または、シェルから直接実行します。

npx @teunlao/vidin ~/Desktop/bug.mov       # → ./.vidin/bug/
npm i -g @teunlao/vidin                    # or put `vidin` on PATH for good
vidin https://example.com/screencast.mp4   # downloaded with yt-dlp
vidin zoom bug.mov --from 00:41 --to 00:45 --fps 6
vidin probe bug.mov

出力内容

out/
  REPORT.md        the entry point: timeline table, what changed where, what to open
  manifest.json    the same, machine readable
  sheets/          the whole video as labelled 3x3 grids (~1.3k tokens each)
  frames/          full-detail annotated frames

各フレームには、前に保持したフレームから変化した領域を囲む赤い破線の枠と、フレーム番号、元の動画でのタイムスタンプ、前のフレームからの間隔、フレームを保持した理由、画面の変化量を示す下部バーが付いています。

MCPツール

エージェントが適切な順序でコンテキストを使えるように設計された4つのツールです。

ツール	機能
analyze_video	動画 → ディスク上のフレーム。テキストレポートとコンタクトシート画像1枚を返します
get_frames	番号または時間範囲を指定して詳細なフレームを取得します。1回の呼び出しでコンテキストが埋め尽くされないよう、上限があります
zoom_clip	狭い時間範囲をより高いフレームレートで再抽出します。2枚のフレームだけでは説明できない場面に使います
probe_video	長さ／解像度／fps／音声を低コストで確認します

想定する流れは、分析 → シートを見る → タイムラインを読む → 2、3枚のフレームを開く → その間の場面がまだ不明瞭ならズームする、です。どの秒が重要かを知る前にすべてを開くと、コンテキストを消費してしまいます。

プロファイルと調整

プロファイル	用途
bug-report	デフォルト。誰かが画面を録画し、バグを説明して、録画を終了した場合
dense	少しの変化も重要な短い動画（24 fpsで分析、最大80フレーム）
walkthrough	長時間の録画。フレーム数を減らし、アンカー間隔を広げます
cheap	コンテキストが本当に限られている場合に最小限の負荷で使います（1092pxで12フレーム）

プロファイルを変更せずに調整できます。--max-frames、--sensitivity（イベントとみなす画面の割合。値を下げるとフレーム数が増えます）、--fps、--width、--quality、--no-annotate、--no-sheets。

フレームを分割するのではなく選択する理由

1秒に1枚スクリーンショットを撮ると、3分間で180フレームになりますが、その約90％は同じ内容です。人が読んだり、考えたり、マウスを動かしたりしていたためです。こうした重複フレームのコストはそれほどかかりませんが、実際に何かが起きた数少ないフレームを 埋もれさせ、エージェントはどのフレームかを見つけるためにすべてを確認しなければなりません。フレーム選択は、コスト問題に見せかけたシグナル対ノイズの問題です。

vidin はイベント駆動型です。動画をダウンスケールした RGB で 12 fps で走査し、実際に何かが起きたときだけフレームを保持します。

• 変化は直前のサンプルではなく、直近の 保持された フレームと比較して測定されます。 そのため、ゆっくりとした変化はしきい値以下に隠れることなく蓄積されます。
• フレームは変化の最中ではなく、変化の後に取得されます。 動きが始まっても、すぐには何も出力されません。セレクターは画面が静止するのを待ち、落ち着いたフレームを保持します。クリック後の状態が得られるため、アニメーションのブレを含みません。
• 色も変化としてカウントされます。 明るさではなく、チャンネルごとに比較します。フィールドが赤くなったり、灰色のパネル上に緑のトースト通知が表示されたりしても、輝度はほとんど変わりませんが、バグ報告でまさに重要なのはこうした変化です。
• マウスの動きにはコストがかかりません。 特別扱いではなく、計算上そうなります。解析解像度ではポインターはイベントしきい値より一桁小さいためです。以前はポインターを認識するサブシステムがありましたが、実際の録画で測定したところ、どの判断も変わらなかったため削除されました。
• ガードレールがあります。 最小間隔、長い静止区間をまたぐアンカーフレーム、長いアニメーション中の定期サンプル、そしてデフォルトで40フレームのハード上限があります。上限に達すると、タイムラインの両端を残しつつ、情報量の少ないフレームから先に削除します。

フレームがどの経路をたどった場合でも、次の2つの不変条件が成り立ちます。

• 何も黙って破棄されません。 比較の基準は、フレームを保持した場合にのみ進みます。変化した画面を出力せずに基準へ取り込む経路はありません。そうすると、後続の比較は一度も見ることのない状態との差を測ることになり、変化を復元できなくなるためです。
• 注釈は実際に見える隣接フレームを説明します。 フレーム上限によってタイムラインの中間部分が間引かれた後、残った各フレームの変化率とボックスは、その前に来るフレームとの比較で再計算されます。

動作の仕組み

ffmpeg ─raw RGB @12fps, 400px─ selector ──timestamps+regions── ffmpeg ──annotated WebP
         one decode pass,         event state machine            drawbox/drawtext
         streamed                 in plain TypeScript            per frame

デコードでは、一度に2フレームずつストリーム処理します。セレクターはさらに、間引き後に差分を再計算できるよう、保持したフレームのダウンスケール済みバッファーも保持します。メモリー使用量は動画の長さではなくフレーム上限で決まり、デフォルト設定では約32 MBです。描画はすべて ffmpeg フィルターで行うため、package.json に画像ライブラリはありません。

開発

開発には Bun を使用します。ランタイムコード自体は node: API に準拠しているため、公開済みパッケージは npx が動作するあらゆる環境で実行できます。

git clone https://github.com/teunlao/vidin && cd vidin && bun install
bun test

フィクスチャは、スクリプトで定義されたタイムラインを持つ合成スクリーン録画です。パネル、エラーダイアログ、トースト通知、復旧、そしてポインターだけが動く2つの区間が含まれています。テストスイートでは、段階的に発生する各イベントから静止したフレームが正確に1つ生成され、ポインターの動きだけではフレームが生成されないことを検証します。test/regressions.test.ts は独自のクリップを作成し、レビューで見つかったすべての不具合を再現するテストを固定するため、修正したバグが再発しません。

まだ対応していない機能

• 音声の文字起こし。 ナレーションは、バグ報告の中で最も有用な情報です。 実装予定：ローカルの Whisper（whisper.cpp または mlx-whisper）で、フレームのタイムラインに対応した transcript.md を生成します。
• 保持したフレームに対する OCR。これにより、エージェントはビジョントークンをまったく消費せずに、エラーメッセージを検索できます。
• ポインターの位置とクリックは意図的に報告しません。 実際の録画で描画した照準マークを検証したところ、正解率は半分ほどでした。増えていく DevTools のリクエスト一覧が、ポインターとまったく同じように画面を下へ移動するためです。誤ったマーカーを付けると、五分五分の確率で「ユーザーはここを指していた」と断定してしまいますが、ポインターはフレーム内に明瞭に表示されています。
• 横スクロールは検出しません。縦スクロールは検出します。
• 小さな要素には調整が必要です。 デフォルトのイベント閾値は画面の 0.4% なので、それより小さいプログレスバーやバッジは、それ単体ではイベントとして扱われません。--sensitivity 0.2 または --profile dense を指定すれば検出できますが、フレーム数は増えます。