Claude Video Detail Modes Explained: Trade‑offs Between Transcript, Efficient, Balanced, and Token‑Burner Presets

The transcript, efficient, balanced, and token-burner detail modes trade visual coverage against speed and token cost, with frame budgets ranging from 0 to unlimited frames.

The claude-video project provides a watch skill that downloads videos, extracts frames, and optionally generates transcripts. Four detail presets control how aggressively the tool samples visual content from the source video. Understanding these trade-offs helps you optimize for token budgets, processing time, and analytical depth.

How Detail Modes Work in claude-video

The detail mode is selected via the --detail CLI flag defined in skills/watch/scripts/watch.py (lines 35‑40). The extraction logic branches based on this selection around lines 104‑110, routing to either fast keyframe extraction or scene‑aware sampling.

Mode Comparison Overview

Mode	Frame Budget	Extraction Strategy	Typical Output
transcript	0 frames	Skips extraction entirely	Text only
efficient	≤ 50 frames	Fast keyframe sampling	Quick visual summary
balanced	≤ 100 frames	Scene‑aware uniform distribution	Solid coverage across duration
token‑burner	Unlimited	Scene‑aware, no cap	Exhaustive frame collection

Transcript Mode: Zero Visual Cost

transcript bypasses frame extraction completely. The tool downloads the video, runs Whisper transcription if no caption exists, and returns only the spoken text.

• Frame budget: 0 (hard‑coded skip)
• Token cost: Minimal (text tokens only)
• Speed: Fastest path; no ffmpeg frame decoding
• Use case: Rapid content review, accessibility workflows, strict token budgets

watch https://example.com/video.mp4 --detail transcript

This mode is ideal when you need to verify quotes, generate summaries, or process long archives where visual analysis is unnecessary.

Efficient Mode: Fast Keyframe Sampling

efficient extracts only keyframes—frames where ffmpeg detects scene changes. This provides a lightweight visual timeline without heavy computation.

• Frame cap: 50 frames (default, from frame_cap() in config.py line 34)
• Extraction method: extract_keyframes() in frames.py
• CPU/I/O: Low; leverages ffmpeg's built‑in scene detection
• Coverage gaps: May miss gradual changes or scenes without hard cuts

watch https://example.com/video.mp4 --detail efficient

Choose this mode for short videos, preliminary scans, or when you need a thumbnail‑style overview without token overhead.

Balanced Mode: Scene‑Aware Distribution

balanced uses the same scene‑detection engine as efficient but adds temporal uniformity logic to ensure frames spread across the entire video duration. This prevents clustering at the beginning of content with many early scene changes.

• Frame cap: 100 frames (default, from config.py line 34)
• Extraction method: extract_scene_or_uniform() in frames.py
• CPU/I/O: Moderate; requires parsing scene timestamps plus redistribution math
• Warning trigger: For videos > 10 minutes, the script warns that coverage may appear "thin" (watch.py lines 26‑34)

watch https://example.com/video.mp4 --detail balanced

This is the default mode when no --detail argument is provided. It suits general‑purpose analysis where you need representative visuals without excessive token consumption.

Token‑Burner Mode: Unrestricted Visual Capture

token‑burner removes the frame cap entirely, allowing the scene‑aware engine to extract every detected scene change regardless of count.

• Frame cap: None (unlimited)
• Warning threshold: > 250 frames triggers a console warning (watch.py lines 19‑24)
• CPU/I/O: High; unbounded storage and processing requirements
• Token cost: Potentially hundreds of image tokens per video

watch https://example.com/video.mp4 --detail token-burner

Reserve this mode for archival preservation, forensic analysis, or short clips where complete visual documentation outweighs cost concerns.

Key Trade‑Offs at a Glance

Metric	transcript	efficient	balanced	token‑burner
Frames extracted	0	≤ 50	≤ 100	Unlimited (often > 250)
Processing speed	Instant	Very fast	Moderate	Slow (scales with content)
Token consumption	Minimal	Low‑moderate	Moderate	High
Visual fidelity	None	Coarse, cut‑focused	Evenly distributed	Exhaustive
Best for	Text‑only workflows	Quick previews	General analysis	Deep archival work

Customizing Frame Limits and Behavior

You can override preset caps without changing modes using additional flags:

# Raise balanced cap to 200 frames

watch https://example.com/video.mp4 --detail balanced --max-frames 200

# Force specific sampling rate (ignores scene detection)

watch https://example.com/video.mp4 --fps 1

# Preserve specific timestamps regardless of mode

watch https://example.com/video.mp4 --detail efficient --timestamps 30,60,90

The --max-frames parameter feeds directly into the frame_cap() logic in config.py, while --timestamps bypasses extraction entirely to use user‑specified frames.

Summary

• transcript gives you spoken content with zero visual tokens—fastest and cheapest.
• efficient samples keyframes up to 50 frames for lightweight visual context.
• balanced distributes up to 100 frames evenly across the timeline for representative coverage.
• token‑burner removes all limits, capturing every scene change at maximum fidelity and cost.

Choose based on your token budget, video length, and whether you need comprehensive visual evidence or just directional context.

Frequently Asked Questions

What happens if token‑burner extracts too many frames?

The watch.py script prints a warning when extraction exceeds 250 frames (lines 19‑24), alerting you to high upcoming token usage. Processing continues unless you interrupt it. Consider using --max-frames to impose a manual ceiling if the warning appears.

Can I use balanced mode on very long videos?

Yes, but the script warns that frame distribution may appear sparse for videos exceeding 10 minutes (watch.py lines 26‑34). For long content, either accept thinner visual coverage or switch to token‑burner with budget awareness.

How do the caps actually get enforced?

The frame_cap() function in skills/watch/scripts/config.py (line 34) maps mode names to integer limits. This value is passed to extraction functions in frames.py, which truncate or subsample output to respect the cap. token‑burner explicitly passes None to disable limiting.

Is there a way to preview how many frames will extract before running?

Not directly, but you can estimate: efficient typically yields 10‑30 keyframes for standard content, while balanced fills toward its 100‑frame cap. For token‑burner, run with --detail efficient first to gauge scene density, or check the 10‑minute warning logic to anticipate sparse coverage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}