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

Claude-Video’s watch command offers three detail modes—efficient, balanced, and token-burner—that trade off processing speed and frame count by switching between keyframe-only extraction and scene-aware analysis with configurable caps.

The bradautomates/claude-video repository provides a video processing tool that extracts frames from videos for AI analysis. These three detail modes determine how the watch command samples visual content, directly impacting both the token cost and the comprehensiveness of the video summary.

What Are Detail Modes in Claude-Video?

Detail modes control the frame extraction strategy used when processing a video URL. According to the source code in skills/watch/scripts/watch.py, the --detail flag selects between three distinct engines, each designed for different use cases ranging from quick previews to maximum visual fidelity.

Technical Implementation of Each Mode

The implementation splits the three modes into two extraction engines: keyframe extraction for efficient mode, and scene-aware extraction for balanced and token-burner modes.

Efficient Mode: Keyframe-Only Extraction

Efficient mode is optimized for speed and minimal token usage. In skills/watch/scripts/watch.py lines 204-210, when detail == "efficient", the system calls extract_keyframes from skills/watch/scripts/frames.py. This engine uses yt-dlp to extract existing scene-change keyframes from the video container without running full-frame analysis.

The default frame cap for this mode is 50 frames, defined in skills/watch/scripts/config.py by the frame_cap() function. This makes efficient mode ideal for quick previews of long videos where only major scene changes matter.

Balanced Mode: Scene-Aware with Cap

Balanced mode is the default setting (controlled by DEFAULT_DETAIL in config.py). It provides moderate coverage by running an ffmpeg-based scene-change detector via extract_scene_or_uniform in skills/watch/scripts/frames.py.

As implemented in watch.py lines 214-225, balanced mode uses the frame_cap() setting of 100 frames. The scene-aware engine detects meaningful scene boundaries, then optionally fills remaining slots with uniformly-spaced frames to hit the target count. This offers better coverage than efficient mode while maintaining reasonable token costs.

Token-Burner Mode: Unlimited Scene Analysis

Token-burner mode maximizes visual detail by removing frame limits entirely. It uses the same extract_scene_or_uniform engine as balanced mode, but passes None as the detail_budget parameter, resulting in no frame cap. According to config.py, frame_cap("token-burner") returns None.

This mode keeps every detected scene-change frame, which can generate hundreds of frames for long videos. The system includes a runtime warning in watch.py lines 19-24 that triggers if token-burner yields more than 250 frames, alerting users to potentially high image-token costs.

Configuration and Frame Caps

The frame limits are centralized in skills/watch/scripts/config.py. The frame_cap() function maps each mode to its budget:

• "efficient": returns 50
• "balanced": returns 100
• "token-burner": returns None (unlimited)

Users can override the default mode via the WATCH_DETAIL environment variable or the --detail CLI argument. Additionally, the --max-frames flag can adjust the cap for any mode, though token-burner ignores the cap unless explicitly constrained.

Usage Examples

Run the watch command with different detail modes using the --detail flag:

# Fast preview using existing keyframes only (max 50)

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

# Default scene-aware extraction (max 100 frames)

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

# Maximum detail with no frame limit

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

Override caps while keeping the scene-aware engine:

# Balanced engine with custom cap of 200

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

Choosing the Right Detail Mode

Select efficient when you need rapid results and only require key scene changes. Choose balanced for general-purpose video analysis where moderate coverage suffices. Reserve token-burner for short, complex videos where every visual detail matters, keeping in mind that processing time and token costs scale with frame count.

Summary

• Efficient mode uses extract_keyframes with a 50-frame cap for maximum speed by sampling only existing keyframes.
• Balanced mode runs extract_scene_or_uniform with a 100-frame cap, combining scene detection with uniform sampling for moderate coverage.
• Token-burner mode uses the same scene-aware engine but sets detail_budget to None, capturing every scene-change frame without limits.
• Configuration resides in skills/watch/scripts/config.py, while dispatch logic lives in skills/watch/scripts/watch.py lines 204-225.
• Token-burner triggers a warning if it extracts more than 250 frames to prevent unexpected high costs.

Frequently Asked Questions

How do I set the default detail mode for all Claude-Video operations?

Set the WATCH_DETAIL environment variable to "efficient", "balanced", or "token-burner" in your shell configuration. If not set, the system defaults to "balanced" as defined in skills/watch/scripts/config.py under DEFAULT_DETAIL.

Can I use token-burner mode but limit the total frames?

Yes. While token-burner has no default cap, you can enforce a limit using the --max-frames argument. When provided, this value becomes the detail_budget passed to extract_scene_or_uniform, overriding the None value returned by frame_cap("token-burner").

Why does token-burner mode warn about high frame counts?

The warning mechanism in watch.py lines 19-24 activates when token-burner extracts more than 250 frames. Since each frame consumes image tokens when sent to the AI, this alert prevents users from accidentally incurring high API costs on long videos with frequent scene changes.

What happens if a video has fewer scene changes than the frame cap?

If the scene-aware engine detects fewer scenes than the cap allows, balanced mode fills the remaining slots with uniformly-spaced frames to reach the target count. Efficient mode simply returns fewer frames since it only extracts existing keyframes and does not interpolate additional frames.

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