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

Claude-Video's three detail modes—efficient, balanced, and token-burner—trade off between processing speed and frame extraction density, with each mode using a different extraction engine and frame cap to control token consumption.

The bradautomates/claude-video repository provides a watch command that processes video URLs through Claude's vision capabilities, and selecting the right efficient, balanced, or token-burner detail mode determines how many frames are extracted and how many tokens are consumed during analysis.

Frame Extraction Engines and Frame Caps

Each detail mode maps to a specific frame budget and extraction strategy defined in skills/watch/scripts/config.py.

• Efficient mode uses extract_keyframes with a maximum of 50 frames (frame_cap("efficient") returns 50). This engine relies on yt-dlp-derived scene-change keyframes only, making it the fastest option because it never runs full-frame analysis.

• Balanced mode uses extract_scene_or_uniform with a 100-frame cap (frame_cap("balanced") returns 100). This runs an ffmpeg-based scene-change detector to identify meaningful boundaries, then fills gaps with uniformly-spaced frames if needed to hit the target count.

• Token-burner mode uses the same extract_scene_or_uniform engine as balanced, but frame_cap("token-burner") returns None, meaning no frame limit is applied. Every detected scene-change frame is kept, which can generate hundreds of frames for long videos.

Source Code Implementation

Configuration Defaults

In skills/watch/scripts/config.py, the frame_cap() function (lines 66-71) maps each detail string to its respective limit: 50 for efficient, 100 for balanced, and None for token-burner. The default mode is controlled by the DEFAULT_DETAIL variable set to "balanced", which can be overridden via the WATCH_DETAIL environment variable or the --detail CLI argument.

Engine Selection Logic

The dispatch logic resides in skills/watch/scripts/watch.py. Lines 204-210 handle the efficient branch by calling extract_keyframes with the budget derived from detail_budget. For balanced and token-burner modes (lines 214-225), the code calls extract_scene_or_uniform, passing the same budget parameter. When detail_budget is None—which occurs for token-burner—the extraction engine keeps every detected scene frame without capping.

A runtime warning triggers at lines 19-24 when token-burner yields more than 250 frames, alerting users that image-token costs may be substantial.

Performance Characteristics

Efficient mode prioritizes speed using existing video keyframe indexes, making it ideal for quick previews where visual completeness is less critical than latency.

Balanced mode offers moderate coverage suitable for most use cases; its scene-aware detection ensures meaningful frames are captured while the 100-frame cap prevents excessive token usage.

Token-burner mode maximizes visual fidelity by capturing every scene change regardless of count, consuming significantly more processing time and API tokens, appropriate only when comprehensive frame analysis is required.

Usage Examples

# Fast, low-frame preview (max 50 keyframes)

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

# Moderate coverage – scene-change frames, capped at 100

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

# Full scene coverage – no frame cap (may generate hundreds of frames)

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

Override specific caps while retaining the extraction engine:

# Balanced mode but force a higher cap

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

Summary

• Efficient mode extracts only existing keyframes (max 50) using extract_keyframes, providing the fastest processing with minimal token usage.
• Balanced mode uses scene-aware detection (extract_scene_or_uniform) capped at 100 frames, offering a middle ground between speed and detail.
• Token-burner mode employs the same scene detection as balanced but imposes no frame limit, potentially extracting hundreds of frames and triggering a warning if the count exceeds 250.
• Configuration resides in skills/watch/scripts/config.py, while dispatch logic operates in skills/watch/scripts/watch.py according to the detail_budget calculation.

Frequently Asked Questions

What is the default detail mode in Claude-Video?

Claude-Video defaults to balanced mode as defined by the DEFAULT_DETAIL variable in skills/watch/scripts/config.py. You can override this globally by setting the WATCH_DETAIL environment variable, or per-command using the --detail flag.

How many frames does token-burner mode typically extract?

Token-burner mode has no frame cap, so it extracts every scene-change frame detected by the ffmpeg-based analyzer. For long videos with frequent scene changes, this can produce several hundred frames. The application emits a warning when exceeding 250 frames to alert you of potentially high token costs.

Can I override the frame cap in efficient or balanced mode?

Yes. While frame_cap() in config.py defines defaults (50 for efficient, 100 for balanced), you can supply the --max-frames argument to the watch command to set a custom limit. This value becomes detail_budget in watch.py and is passed to the respective extraction engine.

Which detail mode should I use for long videos?

For long videos, efficient mode is recommended when you need quick summaries, as it limits extraction to 50 keyframes and avoids heavy CPU processing. Use balanced for standard analysis where scene context matters but token costs must remain controlled. Reserve token-burner only for short clips requiring exhaustive visual analysis, as unlimited frames become prohibitively expensive on long content.

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