bug2context

bug2context

バグの画面録画を、AI エージェントが実際に読める、構造化された時系列コンテキストに変換します。

スクリーンショットでは経緯がわかりません。バグは瞬時に発生し、静止画には時間軸がなく、ログやナレーションはまったく別の場所にあります。LLM は動画を扱えません。このツールは録画をひとつの Markdown の時系列にまとめます。重要なフレーム、画面上のテキスト、デバイスログ、音声ナレーションを、すべて同じ時刻で記録します。

• SDK 不要。 誰かが WhatsApp で送ってきた動画を含め、あらゆる動画で動作します。
• ローカル優先。 データがマシンの外に出ることはありません。アカウントも API キーもクラウドも不要です。
• MCP ネイティブ。 Claude Code がツールとして呼び出すので、ファイルを指定するだけです。

uvx bug2context               # guided menu
uvx bug2context process bug.mp4 --out bundle/

引数なしで実行するとメニューが開き、Android デバイスの録画、手元にある動画の処理、以前のバンドルの一覧表示から選べます。出力先は ~/.bug2context/ で、MCP サーバーはここを参照します。すべての機能は以下のフラグから利用できます。フラグを覚えておく手間を省くためのメニューです。

出力内容

- `[00:00]` 🖼 `frames/frame_001_00-00.png` — start of recording
      OCR: Cart 2 items
- `[00:04]` 🖼 `frames/frame_002_00-04.png` — screen changed
      OCR: Applying discount..
- `[00:04]` 📋 W/DiscountEngine: rate field missing
- `[00:06]` 🖼 `frames/frame_003_00-06.png` — screen changed
      OCR: TypeError: cannot read 'rate'
- `[00:06]` 📋 E/RideService: NullPointerException at RideRequest.kt:142
- `[00:06]` 📋 F/AndroidRuntime: FATAL EXCEPTION: main
- `[00:06]` 🎙 "ahí está, explota al aplicar el descuento"

実行結果の全体はexamples/report.mdをご覧ください。

bundle/
├── report.md    the chronology above
├── frames/      the key frames, named by timestamp
└── meta.json    the same data, structured, for programmatic use

インストール

PATH 上に ffmpeg が必要です（brew install ffmpeg）。

uvx --from 'bug2context[ocr]' bug2context          # OCR: Apple Vision on macOS, tesseract elsewhere
uvx --from 'bug2context[ocr,audio]' bug2context    # plus spoken narration

または、ソースからインストールします。

git clone https://github.com/emanueld92/bug2context
cd bug2context
uv sync --extra ocr --extra audio

各ステージは省略可能で、利用できない場合も静かに処理が続行されます。OCR バックエンドがなくてもフレームは取得でき、音声トラックがなくても視覚的なタイムラインは生成されます。

Claude Code から使う

claude mcp add bug2context -- uvx --from 'bug2context[ocr]' bug2context-mcp

ローカルクローンから実行する場合は、こちらを使います：uvx --from /path/to/bug2context bug2context-mcp。

あとは、*「このバグの動画を分析して：~/Desktop/crash.mp4」*と頼むだけです。

ツール	用途
analyze_bug_video	動画 → 時系列レポート（テキストを直接返します）
get_frame	エージェントが確認できるよう、フレームを1枚画像として取得します
list_bundles	以前に処理したバンドルを新しい順に一覧表示します

バンドルのデフォルトの保存先は ~/.bug2context/<video>-<timestamp>/ です。

Android：画面と logcat を1つのコマンドで記録

uv run bug2context record --seconds 60 --package com.example.app --out bundle/

録画中にバグを再現してください。両方のストリームはホスト側の同一タイムスタンプを起点とします。この基準時刻により、クラッシュを示すフレームの隣にスタックトレースを配置できます。

--package を指定してください。 実機では、ログレベルによるフィルタリングだけでは不十分です。2分間のキャプチャで W/E/F 行が7,634行ありましたが、テスト対象アプリのものは1行もなく、すべて AppOpsControllerImpl、GNSSMGT などのログでした。アプリのプロセスに絞ると35行になりました。クラッシュレポートが目的なので、クラッシュタグ（AndroidRuntime、DEBUG）はプロセスにかかわらず保持されます。

ログはフィルタリングせずに取得し、その後で対象を絞るため、アプリがクラッシュして再起動しても、終了時のログが記録されます。同じ内容が連続するログは (×N) の件数を付けて1つにまとめます。フレームワークのログは15件ずつ連続して出ることがあります。

ログファイルをすでにお持ちの場合は、任意の動画に結合できます。

uv run bug2context process bug.mp4 --logcat logcat.txt --log-tag RideService

-v time と -v threadtime の両方を読み取ります。--log-levels のデフォルトは WEF、--log-max-lines のデフォルトは80です。重要度順に並べるため、上限を設けてもクラッシュのログが起動時のログに埋もれることはありません。対象のプロセスがわかっている場合は、--log-pid で絞り込めます。デバイスの時計と録画機の時計がずれている場合、--log-offset で全体を N 秒ずらせます。--video-started-at を指定しない場合は、最初のログエントリが基準時刻になります。

screenrecord は3分で上限に達するため、record はそれ以上の録画を拒否します。黙って途中で切れた動画を返すことはありません。Ctrl-C で録画を安全に早期終了できます。ローカルの adb を終了すると ffprobe が開けないファイルが残るため、まずデバイス上でファイルを確定します。

10分を超える動画は、切り詰めるための ffmpeg コマンドとともに拒否されます（--max-duration 0 で上書きできます）。長さに応じて大きくなるのは時間だけですが、処理量は長さに比例します。デコードだけでも実時間の約3分の1かかります。

ナレーション

uv run bug2context process bug.mp4 --transcribe --language es

デフォルトでは無効です。初回使用時にモデルをダウンロードする必要があり、最も時間のかかるステージですが、ほとんどの録画には音声ナレーションがありません。音声トラックがない場合、または音声トラックが −50 dB より小さい場合は自動的にスキップされます。whisper は無音からでも自信ありげな文章を作り出すため、このガードは速度だけでなく出力品質を守るためのものです。

フレームの選択方法

ffmpeg は候補を多めに生成します（シーンの切り替わりと一定間隔の両方を使うため、ゆっくり変化する画面も見逃しません）。その後、知覚ハッシュで類似フレームをまとめます。--max-frames は結果の上限を設定し、最初のフレームを必ず残したうえで、最も変化の大きいフレームを選びます。

フラグ	デフォルト	備考
--scene-threshold	0.08	シーンの切り替わりを判定する ffmpeg のシーンスコア
--interval-seconds	1.0	シーンの切り替わりがない場合に強制的にサンプルする間隔
--max-frames	auto	2 秒につき 1 フレーム、20〜40 フレーム
--phash-distance	4	この値未満の場合、フレームを重複とみなします
--ocr-upscale	2	OCR の前に拡大します。幅が 1600 px を超える場合はスキップします

OCR のエンドツーエンドの実測時間：

ソース	結果	時間
合成映像 3 分、1080×1920	19 フレーム	8.5 s
Android のキャプチャ、2 分、720×1612 @ 約 12 fps	候補 118 件 → 20 フレーム	16 s
macOS のキャプチャ、90 s、2880×1864 @ 60 fps	候補 97 件 → 18 フレーム	86 s

認識したテキストはフレームの内容ごとに ~/.cache/bug2context/ にキャッシュされるため、設定を変えて同じ動画を再実行した場合、実際に変化した部分だけを処理します。44 s のクリップでは、キャッシュなしで 9.0 s、キャッシュありで 3.3 s と実測され、出力は同一でした。同じ動画を 2 回抽出するとフレームはバイト単位で同一になるため、安全にキャッシュできます。リセットするにはディレクトリを削除してください。

Retina デスクトップの録画は時間がかかりますが、これを避ける方法はありません。5.4 メガピクセルで 60 fps をデコードするコスト（26 s）に加え、Vision ではサイズに関係なく 1 フレームあたり約 1.6 s かかるためです。こうした動画はおおむね実時間と同じ処理時間を見込んでください。スマートフォンのキャプチャなら、処理時間は大幅に短くなります。

--ocr-upscale について：再圧縮された 1080×1920 のフレームでは、スタックトレースが 1× で Null PointerSxception Ride Requestkt14 と読み取られましたが、3× では正しく NullPointerException Ride Request kt 142 と認識されました。再圧縮がひどいソースでは値を大きくしてください。動画は WhatsApp の動画ではなく、ファイルとして送ってもらうよう依頼してください。フレームあたり 5760×3728 の画像を生成する処理では、測定可能な改善がなかったため、幅がすでに 1600 px 以上のフレームでは拡大をスキップします。

OCR はテキストではなくノイズとみなされる行も除外します。たとえば »、.lll (100 4、読み取りを誤ったステータスバーの時刻などです。実際のキャプチャでは、レポートの 210 行のうち 41 行を除外し、実際のテキストは除外しませんでした。失敗を示しているように見える行は、決して除外されません。

既知の制限事項

知覚ハッシュは視覚的な構造を比較します。ナビゲーション、ダイアログ、エラーバナーは検出できますが、ほかのレイアウトが同一のままテキストだけが少し変わった場合は検出できません。1080×1920 での実測では、ハッシュサイズにかかわらず、そうした差はノイズフロア内に収まるため、--phash-distance の値を変えても区別できません。

OCR でも解決できません。OCR は重複排除を通過したフレームに対して実行されるため、すでにまとめられた画面は読み取られません。すべての候補を読み取る方法では、3 分の動画で 48〜59 s かかり、処理時間の予算を超えることが実測されています。バグが同一画面上の小さなテキストの変化である場合は、テキストがフレーム内でより大きな割合を占めるように、切り抜いて録画するか、低い解像度で録画してください。

開発

uv sync --extra ocr
uv run pytest -q

テストは 183 件です。テストスイートで誰かのスマートフォンを録画すべきではないため、デバイス録画は意図的にモック化しています。スイートをオフラインで実行できるよう、Whisper は BUG2CONTEXT_TEST_WHISPER=1 でオプトインします。

ライセンス

MIT — LICENSE を参照してください。