Bug video evidence, timestamped.

From recording to a citable second

1. RecordA screen recording of the bug.
2. ExtractFrames, OCR, transcript, timeline.
3. CiteA second, a frame, spoken words.
4. ConnectOptional file:line in the repo.

One command from a raw video

vidtrace investigate --video bug.mp4 \
  --query "ticket click does not work" \
  --json

{
  "ok": true,
  "query": "ticket click does not work",
  "mode": "keyword",
  "evidence": [
    {
      "time_seconds": 18.4,
      "frame": "frames/frame_0019.png",
      "ocr": "Tickets OPG-14010 Task element",
      "transcript": "I clicked here and it does not work."
    }
  ]
}

• extractvidtrace extract bug.mp4 --json
• searchvidtrace search evidence.veclite "ticket click" --json
• comparevidtrace compare bundle/ --ticket ticket.md --json
• studiovidtrace studio bundle/

Same bundle, three readers

• QA and support

  Turn a reporter video into timestamped evidence, then cut a clip or GIF for the ticket.

• Developers

  Stop guessing from vague notes. Open the frame, read the transcript, and jump to code.

• Coding agents

  Agents cannot watch a video. They can read timeline.json, OCR, and MCP tool results.

Questions

What does vidtrace actually do?

It takes a bug screen recording and writes a local evidence bundle: frames, per-frame OCR, a Whisper transcript, ffprobe metadata, and timeline.json that maps each frame to overlapping speech.

What runtime tools do I need?

ffmpeg, ffprobe, tesseract, and whisper. Run vidtrace doctor after install. Optional: Ollama, fcheap, vecgrep, and codemap.

Can coding agents use it?

Yes. Every mutating or query command supports --json. vidtrace mcp exposes read-only tools over stdio (validate, search, compare, analyze, investigate, timeline, frame, and more).

Does it upload my videos?

No. Extraction runs on your machine. Optional Ollama embeddings also stay local.

How do I install it?

Homebrew cask is the fastest path on macOS. Linux .deb and .rpm packages ship with each release. Or build from source with task build.

What is timeline.json?

The main agent-facing artifact. Each entry is a timestamp, a frame path, OCR text, overlapping transcript segments, and visual_delta when the UI changed.