Efficient, Balanced, and Token-Burner Detail Modes in Claude-Video: A Technical Comparison

Claude-Video's three detail modes trade off processing speed against frame density, with efficient mode extracting up to 50 keyframes, balanced mode capturing up to 100 scene-change frames, and token-burner mode keeping every detected scene without limits.

The open-source claude-video repository provides a watch command for AI-powered video analysis that supports three distinct detail modes—efficient, balanced, and token-burner—each designed for different use cases ranging from quick previews to comprehensive frame-by-frame analysis. These modes determine how frames are extracted from video sources and directly impact both processing time and token consumption when sending visual data to Claude.

What Are Claude-Video Detail Modes?

Detail modes in claude-video control the frame-extraction engine and the maximum frame budget used when processing video content. According to the source code in skills/watch/scripts/config.py, the frame_cap() function assigns specific limits to each mode: 50 frames for efficient, 100 frames for balanced, and None (unlimited) for token-burner.

The mode selection determines whether the tool uses fast keyframe indexing or computationally expensive scene-change detection, directly affecting both the temporal granularity of the analysis and the cost of API calls.

The Three Detail Modes Explained

Efficient Mode (Keyframe Extraction)

Efficient mode prioritizes speed by leveraging existing video metadata rather than analyzing frame content. In skills/watch/scripts/watch.py (lines 204-210), this mode invokes the extract_keyframes function, which uses yt-dlp-derived scene-change keyframes exclusively.

• Frame cap: 50 frames maximum
• Engine: Keyframe-only extraction (extract_keyframes)
• Performance: Fastest option; no full-frame analysis required
• Best for: Quick previews, metadata scanning, or short video summaries

This mode never runs ffmpeg-based scene detection, making it ideal when you need rapid results and can sacrifice granular visual detail.

Balanced Mode (Scene-Aware with Cap)

Balanced mode offers a middle ground by running actual scene-change detection while maintaining reasonable token limits. As implemented in skills/watch/scripts/watch.py (lines 214-225), this mode calls extract_scene_or_uniform with a hard cap of 100 frames.

• Frame cap: 100 frames maximum
• Engine: Scene-aware extraction (extract_scene_or_uniform)
• Performance: Moderate; requires ffmpeg-based scene detection
• Best for: General-purpose analysis where you need meaningful scene boundaries without excessive token usage

When scene detection produces fewer frames than the cap, the engine fills gaps with uniformly spaced frames to maximize coverage. This is the default mode when WATCH_DETAIL is unset or --detail is not specified.

Token-Burner Mode (Unlimited Scene Detection)

Token-burner mode maximizes visual fidelity by removing all frame limits. It uses the same extract_scene_or_uniform engine as balanced mode but passes None as the detail_budget, instructing the extractor to keep every detected scene-change frame regardless of count.

• Frame cap: Unlimited (no cap)
• Engine: Scene-aware extraction without limits
• Performance: Slowest; generates hundreds of frames for long videos
• Best for: Deep analysis of short clips or when maximum visual context is required

The source code includes a runtime warning (lines 19-24 in watch.py) that triggers when this mode yields more than 250 frames, alerting users to potentially high image-token costs.

How Detail Modes Work Under the Hood

The selection logic follows a clear architectural flow through the codebase:

1. Configuration loading: get_config() in config.py reads the WATCH_DETAIL environment variable or falls back to DEFAULT_DETAIL ("balanced")
2. Argument parsing: The --detail CLI flag can override the configuration value
3. Budget calculation: The system calculates detail_budget by applying the mode-specific cap from frame_cap(), reduced by any user-supplied cue timestamps
4. Engine dispatch:
   • If detail == "efficient", the system calls extract_keyframes with max_frames = detail_budget
   • For balanced or token-burner, it calls extract_scene_or_uniform with the same budget parameter; when detail_budget is None (token-burner), the engine preserves every detected scene

The skills/watch/scripts/frames.py module implements both extraction strategies: extract_keyframes simply indexes existing keyframes, while extract_scene_or_uniform runs ffmpeg's scene-change detector and optionally interpolates uniform frames when operating under a cap.

Usage Examples

Run the watch command with your preferred detail mode using the --detail flag:

# Fast preview using keyframes only (max 50 frames)

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

# Standard analysis with scene detection (max 100 frames)

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

# Comprehensive analysis with unlimited frames

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

Override the default caps manually while keeping the scene-detection engine:

# Balanced mode with custom frame limit

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

Set a persistent default via environment variable:

export WATCH_DETAIL=efficient
watch https://youtu.be/xyz

Summary

• Efficient mode uses extract_keyframes for speed, capping at 50 frames and relying solely on existing video keyframes.
• Balanced mode employs extract_scene_or_uniform with a 100-frame limit, running ffmpeg scene detection for meaningful boundaries.
• Token-burner mode utilizes the same scene detection but sets detail_budget to None, preserving every scene-change frame regardless of quantity.
• Configuration resides in skills/watch/scripts/config.py, while dispatch logic lives in skills/watch/scripts/watch.py (lines 204-225).
• Balanced is the default mode, but you can override via WATCH_DETAIL environment variable or --detail CLI argument.

Frequently Asked Questions

Which detail mode should I use for long videos?

For videos longer than 10 minutes, efficient mode prevents timeout issues and excessive token costs by limiting extraction to 50 keyframes. If you need specific scene analysis on long content, use balanced mode with a custom --max-frames value rather than token-burner, which could generate hundreds of frames and significantly increase API costs.

Can I override the default frame limits without changing modes?

Yes. While each mode has internal defaults defined in frame_cap() (50 for efficient, 100 for balanced, unlimited for token-burner), you can pass --max-frames to set a hard ceiling regardless of mode. The system calculates detail_budget as the minimum of your mode's cap and any user-supplied maximum.

Why does token-burner mode trigger a warning?

When token-burner mode generates more than 250 frames, skills/watch/scripts/watch.py prints a runtime warning (lines 19-24) because each frame consumes image tokens when sent to Claude's API. This alert prevents accidental high-cost operations when processing videos with frequent scene changes or extended duration.

What happens if I don't specify a detail mode?

The system defaults to balanced mode. According to skills/watch/scripts/config.py, the DEFAULT_DETAIL constant is set to "balanced", and get_config() uses this value when the WATCH_DETAIL environment variable is unset and no --detail argument is provided.

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