Usage

Human Workflow

vidtrace extract /path/to/bug.mp4

Human mode prints progress and a concise final summary.

Progress is shown as numbered steps with bars for bundle creation, metadata, frames, OCR, transcript, timeline, and completion. JSON mode suppresses this text so stdout remains parseable.

Agent Workflow

vidtrace extract /path/to/bug.mp4 --json
vidtrace extract /path/to/bug.mp4 --resume --json
vidtrace extract /path/to/bug.mp4 --index /tmp/vidtrace-evidence.veclite --stash --json

Use --resume / --resume-from to continue a partial extraction. Use --index and --stash to wire the new bundle into evidence search or the fcheap vault in the same run.

Agents can print the built-in operating guide before extraction:

vidtrace docs agent

With --json, stdout contains JSON only. Agents should read output_dir from the summary and inspect:

• metadata.json
• timeline.json
• ocr/ocr_all_frames.txt
• transcript/*.json
• selected frames/frame_*.png

Under --json, every non-zero exit — including usage and validation errors (exit 2) — writes {"ok":false,"error":"..."} to stdout and leaves stderr empty. Always decode stdout, not stderr, to recover the failure reason. The output_dir field is the entry-point for every downstream command (validate, index, investigate, compare, analyze, studio).

Validate the bundle before deeper analysis:

vidtrace validate "$output_dir" --json

Index and search timestamped evidence:

vidtrace index "$output_dir" --db /tmp/vidtrace-evidence.veclite --json
vidtrace search /tmp/vidtrace-evidence.veclite "clicking a ticket does not work" --json
vidtrace clip from-evidence --db /tmp/vidtrace-evidence.veclite --query "clicking a ticket does not work" --pad 2 --json

One-shot investigate from a raw video:

vidtrace investigate --video /path/to/bug.mp4 \
  --query "clicking a ticket does not work" \
  --codebase /path/to/app \
  --connect \
  --json

Index several bundles into one database (a shell glob expands to multiple paths):

vidtrace index /tmp/vidtrace-real/bug_artifacts_* --db /tmp/vidtrace-evidence.veclite --json

For semantic and hybrid search, also build an embedding index with a running Ollama server, then search with --mode:

vidtrace index "$output_dir" --db /tmp/vidtrace-evidence.veclite --embed ollama --embed-model nomic-embed-text --json
vidtrace search /tmp/vidtrace-evidence.veclite "a task click does nothing" --mode hybrid --embed ollama --embed-model nomic-embed-text --json

Keyword search remains the default and needs no embedder. vidtrace doctor reports whether Ollama is installed.

One database can index many bundles. Narrow a search to a single bundle, source video, evidence source, or time window:

vidtrace search /tmp/vidtrace-evidence.veclite "clicking a ticket does not work" \
  --bundle "$output_dir" \
  --min-time 60 --max-time 90 \
  --json

If you have a pre-v0.17.0 evidence database (created by an older vidtrace index), migrate it to the single-collection layout. Running it on a modern database is a no-op, so it is safe to run unconditionally:

vidtrace migrate-evidence /tmp/vidtrace-evidence.veclite --json

Create a handoff from video evidence to code search:

vidtrace investigate "$output_dir" \
  --query "clicking a ticket does not work" \
  --codebase /path/to/app \
  --json

Run real codebase search via fcheap connect (vecgrep) and get file:line code matches alongside video evidence:

vidtrace investigate "$output_dir" \
  --query "clicking a ticket does not work" \
  --codebase /path/to/app \
  --connect \
  --json

Resolve code matches onto the code graph with codemap for symbol resolution, callers, and blast radius:

vidtrace investigate "$output_dir" \
  --query "clicking a ticket does not work" \
  --codebase /path/to/app \
  --connect \
  --codemap \
  --json

Add --codemap-annotate to pin a source="vidtrace" annotation on each resolved symbol so later code-graph queries can join back to the evidence. --codemap requires --connect and degrades gracefully when codemap is not installed (the failure is recorded in codemap_error).

Stash a bundle to the fcheap vault for sharing or archival:

vidtrace stash save "$output_dir" --name "OPG-15070 bug" --tag bug --json

List, inspect, restore, and search stashes:

vidtrace stash list --tool vidtrace --json
vidtrace stash info <stash-id> --json
vidtrace stash restore <stash-id> --to /tmp/restored --json
vidtrace stash search "login fails" --json

Investigate a stashed bundle without a local copy:

vidtrace investigate --stash <stash-id> --query "clicking a ticket does not work" --json

vidtrace doctor reports whether fcheap, vecgrep, and codemap are installed. All stash, connect, and codemap features degrade gracefully with a clear error when the tools are missing.

Cut clips, make GIFs, and stitch videos from timestamp ranges:

vidtrace clip cut /path/to/video.mp4 --label "issue1=0:18-3:40" --label "issue2=3:40-4:05" --json
vidtrace clip gif /path/to/video.mp4 --label "issue1=0:18-3:40" --fps 10 --width 480 --json
vidtrace clip stitch clip1.mp4 clip2.mp4 --name summary --json

Timestamps support SS, MM:SS, and HH:MM:SS. Use --range for unnamed clips or --label LABEL=START-END for named clips. Add --stash --tag intel to stash clips to fcheap after cutting. A clips.json manifest is written to each output directory. See Clip for the full subcommand reference.

Then compare the ticket with extracted evidence:

vidtrace compare "$output_dir" --ticket ticket.md --json
vidtrace analyze "$output_dir" --ticket ticket.md

Open a bundle in the studio:

vidtrace studio "$output_dir"

Use up/down or k/j to move through timeline entries. Press m for metadata, o to open the selected frame, r to reveal it in Finder on macOS, and c to copy a concise evidence summary when clipboard tooling is available. Press q to exit. See Studio for the review workflow.

Studio is compact by default. It shows timeline and selected evidence side by side when the terminal is wide enough, and stacks them on narrow terminals.

Documentation Site

Build the VitePress documentation site:

task site

The build output is docs/.vitepress/dist, which is the Vercel output directory.

Common Options

vidtrace extract /path/to/bug.mp4 \
  --fps 1 \
  --ocr-lang eng \
  --whisper-lang en \
  --model small \
  --out ~/Downloads \
  --name bug

Flag	Default	Purpose
--fps	1	Frames extracted per second
--ocr-lang	eng	Tesseract language list
--whisper-lang	en	Whisper audio language
--model	small	Whisper model
--out	~/Downloads	Parent output directory
--name	input basename	Artifact bundle name prefix
--json	false	Machine-readable run summary

Local Real Video

A local sample may exist at ~/Downloads/bug.mp4. Do not commit it or generated artifact bundles.

bin/vidtrace extract ~/Downloads/bug.mp4 \
  --out /tmp/vidtrace-real \
  --name bug \
  --json

Development Wrappers

task extract VIDEO=/path/to/bug.mp4
task agent VIDEO=/path/to/bug.mp4
task run -- validate /path/to/bundle --json
task run -- index /path/to/bundle --db /tmp/vidtrace-evidence.veclite --json
task run -- search /tmp/vidtrace-evidence.veclite "ticket click" --json
task run -- investigate /path/to/bundle --query "ticket click" --codebase /path/to/app --json
task run -- investigate /path/to/bundle --query "ticket click" --codebase /path/to/app --connect --json
task run -- stash save /path/to/bundle --name "bug-evidence" --json
task site

Use task agent when testing the JSON automation contract.