How Claude-Video's Efficient, Balanced, and Token-Burner Detail Modes Differ

Claude-Video's three detail modes trade speed against frame count and visual fidelity: efficient uses fast keyframe-only extraction capped at 50 frames; balanced runs scene-change detection with a 100-frame cap; token-burner removes the cap entirely to capture every scene-change frame.

The watch command in bradautomates/claude-video processes videos by extracting representative frames for AI analysis. The detail mode you select controls which extraction engine runs, how many frames are collected, and ultimately how many tokens your video analysis will consume. Understanding these differences helps you optimize for speed, cost, or comprehensive visual coverage.

Frame Extraction Engines and Caps

Each detail mode maps to a specific combination of extraction logic and frame budget. These values are hardcoded in skills/watch/scripts/config.py through the frame_cap() function.

Detail Mode	Extraction Engine	Default Cap	Frame Selection Strategy
efficient	extract_keyframes	50 frames	Uses yt-dlp-derived scene-change keyframes only—no full-frame analysis
balanced	extract_scene_or_uniform	100 frames	Runs ffmpeg scene-change detection to find meaningful boundaries, fills gaps with uniform frames if needed
token-burner	extract_scene_or_uniform	unlimited (None)	Same detector as balanced but keeps every scene-change frame regardless of count

The frame_cap() function in skills/watch/scripts/config.py (lines 66-71) returns these values directly: 50 for efficient, 100 for balanced, and None for token-burner and transcript modes.

Efficient Mode: Speed-Optimized Keyframe Extraction

Efficient mode is designed for rapid video previews with minimal token usage. It delegates frame selection entirely to the video's existing keyframe index.

In skills/watch/scripts/watch.py (lines 204-210), the efficient branch calls:

extract_keyframes(video_file, max_frames=detail_budget)

This method relies on yt-dlp-derived scene-change keyframes without running additional video analysis. Because it never invokes ffmpeg for scene detection, efficient mode completes significantly faster than the alternatives.

# Quick preview, maximum 50 keyframes

watch https://youtu.be/xyz --detail efficient

Use efficient mode when you need fast turnaround on long videos or when only a rough visual summary is required.

Balanced Mode: Scene-Aware Sampling with Moderate Coverage

Balanced mode is the default (DEFAULT_DETAIL in config.py). It activates the more sophisticated extract_scene_or_uniform engine from skills/watch/scripts/frames.py.

The scene-aware extractor:

1. Runs ffmpeg's scene-change detector to identify meaningful visual transitions
2. Keeps frames at detected scene boundaries
3. If the scene count falls below the cap, interpolates uniformly-spaced frames to reach the target of 100 frames

In watch.py (lines 214-225), balanced mode passes detail_budget=100 to constrain output:

extract_scene_or_uniform(
    video_file,
    max_frames=detail_budget,  # 100 for balanced

    duration_hint=duration
)

# Default behavior—moderate coverage with scene intelligence

watch https://youtu.be/xyz

# Explicit equivalent:

watch https://youtu.be/xyz --detail balanced

Balanced mode suits most use cases where you need representative coverage without excessive token consumption.

Token-Burner Mode: Maximum Visual Fidelity, Unlimited Frames

Token-burner mode removes the frame cap entirely to capture every detected scene change. It uses the same extract_scene_or_uniform engine as balanced but passes None as the budget.

From watch.py lines 214-225, when detail == "token-burner":

detail_budget = None  # No cap applied

# ...

extract_scene_or_uniform(
    video_file,
    max_frames=detail_budget,  # None = unlimited

    duration_hint=duration
)

The extraction keeps every scene-change frame detected by ffmpeg. For videos with frequent cuts—music videos, fast-paced tutorials, or montages—this can yield hundreds of frames.

watch.py includes a runtime warning (lines 19-24) that triggers when token-burner produces more than 250 frames, alerting users to potential high image-token costs.

# Comprehensive coverage—no frame limit

watch https://youtu.be/xyz --detail token-burner

Use token-burner when visual completeness matters more than token economy, such as detailed content analysis or archival documentation.

Configuration and Override Behavior

The detail mode flows through a consistent configuration pipeline in watch.py:

1. Environment variable: WATCH_DETAIL sets the default
2. CLI override: --detail argument takes precedence
3. Budget calculation: detail_budget = max_frames - cue_frames (cues subtract from your cap)
4. Engine dispatch: efficient → extract_keyframes; balanced/token-burner → extract_scene_or_uniform

You can also override caps manually regardless of mode:

# Balanced mode with custom 200-frame cap

watch https://youtu.be/xyz --detail balanced --max-frames 200

# Token-burner with artificial limit (cap still applies)

watch https://youtu.be/xyz --detail token-burner --max-frames 150

Performance and Cost Comparison

Factor	Efficient	Balanced	Token-Burner
Processing speed	Fastest	Moderate	Slowest (more frames to encode)
Frame count typical	≤50	≤100	50-500+
Scene intelligence	None (keyframe-only)	Yes	Yes
Token cost	Lowest	Moderate	Highest
Best for	Quick previews, long videos	General analysis	Detailed review, short dense videos

Summary

• Efficient mode (extract_keyframes, 50-frame cap): Fastest option using pre-indexed keyframes without scene analysis.

• Balanced mode (extract_scene_or_uniform, 100-frame cap): Default scene-aware extraction that intelligently samples video content.

• Token-burner mode (extract_scene_or_uniform, no cap): Maximum frame capture for comprehensive visual analysis at higher token cost.

The frame_cap() function in skills/watch/scripts/config.py and the dispatch logic in skills/watch/scripts/watch.py (lines 204-225) implement these behaviors, with runtime warnings protecting against accidental high-frame outputs.

Frequently Asked Questions

What happens if I use token-burner on a very long video?

Token-burner keeps every scene-change frame without limit. For long videos with frequent cuts, this can exceed 250 frames and trigger a runtime warning in watch.py. The analysis will proceed, but your API costs will scale with frame count. Consider using --max-frames to impose a manual cap.

Can I change the default frame caps?

The caps are defined in skills/watch/scripts/config.py (lines 66-71) within the frame_cap() function. To modify defaults permanently, edit this file or set WATCH_DETAIL environment variable and use --max-frames for per-run adjustments.

Why does balanced mode sometimes use uniform frames instead of scene detection?

The extract_scene_or_uniform engine in skills/watch/scripts/frames.py prioritizes scene-change frames but fills gaps with uniform sampling when the detected scene count falls below your cap. This ensures you receive the full budget of frames for comprehensive coverage even in visually static videos.

Is efficient mode always faster than balanced?

Yes. Efficient mode relies on existing keyframe metadata from yt-dlp without invoking ffmpeg scene detection. Balanced and token-burner both run the ffmpeg scene-change detector, which adds processing time proportional to video length and complexity.

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