vidtrace

Appearance

vidtraceBug video evidence, timestamped.

Turn screen recordings into structured evidence bundles that humans and coding agents can inspect. Local-first Go CLI — frames, OCR, transcripts, and a timeline that ties what was seen to what was said.

Install
Quick start
GitHub
vidtrace logo
⏱️

Timestamped evidence

Every frame, OCR block, and transcript segment is mapped to a second-accurate timeline. Cite what you saw and what was said by timestamp, not by vague notes.

See the bundle layout

🤖

Agent-ready JSON

Every command emits stable JSON. Agents read output_dir, then inspect metadata.json, timeline.json, OCR text, and selected frames — no TUI trapping.

Read the CLI contract

🖥️

Terminal Studio

Browse timeline entries, view OCR and transcript side-by-side, open frames, reveal in Finder, and copy concise evidence summaries — all keyboard-first.

Studio guide

🔎

Evidence search

Index bundles into a VecLite database and search by keyword, semantic, or hybrid mode. Filter by bundle, source video, evidence source, and time window.

Search workflow

🎫

Ticket comparison

Compare a ticket description against extracted video evidence with confidence scores and term hits. Generate Markdown analysis reports for handoff.

Analysis guide

✂️

Clip, GIF, stitch

Cut sub-clips at timestamp ranges, make lightweight GIFs for tickets and chat, and stitch clips into a summary video. Stash outputs to fcheap.

Clip commands

🔌

MCP server

Run a read-only Model Context Protocol server over stdio. Agents call validate, search, compare, analyze, and investigate tools with structured outputs.

MCP tools

🏠

Local-first

Runs entirely on your machine with ffmpeg, tesseract, and whisper. No cloud uploads. Optional Ollama for semantic search. MIT licensed.

Install guide

vidtrace — bash
$brew tap abdul-hamid-achik/tap && brew install --cask abdul-hamid-achik/tap/vidtraceclick to copy

From screen recording to citable evidence

One command turns a bug video into a structured, timestamped bundle.

🎥Bug videoscreen recording
→
⚙️extractffmpeg · tesseract · whisper
→
📦Evidence bundleframes · OCR · transcript · timeline
→
🔎search · analyzeindex · compare · investigate

Why vidtrace

Stop scrubbing through recordings. Start citing evidence.

Task
Without vidtrace
With vidtrace
Find the exact moment a bug occurs
Scrub through a 10-minute recording, guess timestamps
Jump to the timeline entry, OCR + transcript at that second
Share evidence in a ticket
Upload a huge video, write vague repro steps
Link a timestamped frame, paste OCR + transcript text
Hand off to a coding agent
Agent can't watch video; paste screenshots manually
Agent reads timeline.json, searches evidence, investigates code
Search across past bug videos
Re-watch every recording, no index
Index all bundles, keyword/semantic/hybrid search in seconds
Compare a ticket claim with the recording
Manual cross-reference, subjective assessment
vidtrace compare scores confidence with term hits
Cut a clip for a README or chat
Open a video editor, export, compress
vidtrace clip cut --label in one terminal command

Try it in one command

Extract, search, and investigate — all from the terminal.

Extract evidence

```bash vidtrace extract bug.mp4 --json ``` Produces frames, OCR, transcript, metadata, and timeline in a timestamped bundle directory.

Search evidence

```bash vidtrace index bundle/ --db evidence.veclite --json vidtrace search evidence.veclite "ticket click does not work" --json ``` BM25 keyword search by default, optional semantic and hybrid via Ollama.

Investigate to code

```bash vidtrace investigate bundle/ \ --query "ticket click does not work" \ --codebase ./app --connect --json ``` Video evidence plus real file:line code matches via vecgrep.

Compare a ticket

```bash vidtrace analyze bundle/ --ticket ticket.md vidtrace compare bundle/ --ticket ticket.md --json ``` Heuristic ticket-vs-video scoring with confidence and term hits.

Built for three audiences

Humans, developers, and coding agents — all from the same bundle.

QA & Support

Receive a bug video, extract timestamped evidence, cut clips and GIFs for tickets, and compare what the reporter said against what the recording shows.

Developers

Stop guessing from vague repro notes. Open the Studio, jump to the frame, read the transcript, and trace the evidence straight into a code fix.

Coding agents

Agents can't watch video. They can read JSON. vidtrace gives them timeline.json, OCR text, transcripts, an MCP server, and investigation handoffs.

v0.19.0
Latest release
11
CLI commands
5
Transcript formats
MIT
Open source

Frequently asked questions

Everything you need to know before installing.

It takes a screen recording of a bug and produces a structured evidence bundle: extracted frames (PNG), OCR text per frame, a Whisper transcript in 5 formats, ffprobe metadata, and a timeline.json that maps every frame to overlapping transcript segments. Everything is timestamped and citable.
ffmpeg, ffprobe, tesseract, and whisper. Run `vidtrace doctor` after install to verify. Optional tools: Ollama for semantic search, fcheap for bundle stashing, vecgrep for codebase search, codemap for structural code graph queries.
Yes. Every command emits stable JSON with `--json`. Agents read `output_dir` from stdout, then inspect `timeline.json`, `metadata.json`, OCR text, and selected frames. The MCP server (`vidtrace mcp`) exposes read-only tools over stdio for validate, search, compare, analyze, and investigate.
No. vidtrace is local-first. All extraction runs on your machine with ffmpeg, tesseract, and whisper. No cloud uploads. Optional Ollama embeddings also run locally.
The fastest path is Homebrew: `brew tap abdul-hamid-achik/tap && brew install --cask abdul-hamid-achik/tap/vidtrace`. Linux .deb and .rpm packages are also published. Or build from source with `task build`.
The main agent-facing artifact. It maps every extracted frame to its OCR text and any overlapping transcript segments, with second-accurate timestamps. It is the structured, citable evidence that replaces vague reproduction notes.
Yes. `vidtrace index` accepts multiple bundle paths (shell globs) and indexes them into one VecLite database. Search with keyword, semantic, or hybrid mode, filtered by bundle, source video, evidence source, and time window.

Start extracting evidence in minutes

Install with Homebrew or build from source. ffmpeg, tesseract, and whisper are the only runtime deps.

Install guideView on GitHub

Documentation ​

Start ​

  • Install — install the CLI and runtime media tools.
  • Usage — run human and agent workflows.
  • Analysis — compare tickets with extracted video evidence.
  • Studio — inspect a generated bundle in the terminal Studio.
  • Clip — cut clips, make GIFs, and stitch videos from timestamp ranges.

Reference ​

  • CLI Contract — command surface, flags, exit codes, and JSON output.
  • Artifact Schema — generated bundle layout and JSON schemas.
  • Testing — local, CI, smoke, and glyphrun verification.
  • Release — GitHub Actions, GoReleaser, and Homebrew tap publishing.
  • Documentation Site — VitePress and Vercel deployment.

Architecture ​