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

The three detail modes in bradautomates/claude-video differ by frame extraction engine, frame cap limits, and scene detection depth—efficient uses keyframe-only extraction capped at 50 frames, balanced uses scene-aware detection capped at 100 frames, and token-burner removes all caps for maximum visual coverage.

When processing video with the watch command in the bradautomates/claude-video repository, you can select from three distinct video processing detail modes that trade off speed, frame count, and token consumption. Each mode invokes a different extraction engine and imposes specific constraints on how many frames are analyzed and sent to the language model.

Frame Extraction Engines and Frame Caps

The watch command determines how to sample your video based on the --detail argument, which maps to specific extraction functions and hard limits defined in the configuration layer.

Efficient Mode: Keyframe-Only Extraction

Efficient mode prioritizes speed and minimal token usage by extracting only existing keyframes from the video container.

• Engine: extract_keyframes function in skills/watch/scripts/frames.py
• Frame Cap: 50 frames (defined in skills/watch/scripts/config.py)
• Behavior: Uses yt-dlp-derived scene-change keyframes without running full-frame analysis, making it the fastest option for quick previews

In watch.py lines 204-210, when detail == "efficient", the code calls extract_keyframes with max_frames = detail_budget, which defaults to 50 based on the frame_cap() function.

Balanced Mode: Scene-Aware Detection

Balanced mode offers a middle ground by detecting actual scene changes and optionally filling gaps with uniform frames to hit a target count.

• Engine: extract_scene_or_uniform function in skills/watch/scripts/frames.py
• Frame Cap: 100 frames (defined in skills/watch/scripts/config.py)
• Behavior: Runs an ffmpeg-based scene-change detector to identify meaningful boundaries, then interpolates uniform frames if needed to reach the cap

This is the default mode when WATCH_DETAIL is unset, as specified by DEFAULT_DETAIL = "balanced" in the configuration. Lines 214-225 in watch.py dispatch to this engine for both balanced and token-burner modes.

Token-Burner Mode: Unlimited Scene Coverage

Token-burner mode maximizes visual fidelity by removing frame limits entirely, keeping every detected scene-change frame regardless of quantity.

• Engine: extract_scene_or_uniform (same as balanced)
• Frame Cap: Unlimited (None returned by frame_cap())
• Behavior: Same scene-detection algorithm as balanced, but detail_budget is None, so the engine keeps every detected scene-change frame without interpolation

When this mode generates more than 250 frames, watch.py lines 19-24 emit a runtime warning alerting users to high image-token costs.

Source Code Implementation

The architectural flow that determines video processing behavior spans three key files:

Configuration Layer (skills/watch/scripts/config.py):

• The frame_cap() function returns 50 for "efficient", 100 for "balanced", and None for "token-burner" and "transcript"
• DEFAULT_DETAIL sets the fallback to "balanced"

Dispatch Logic (skills/watch/scripts/watch.py):

• Configuration is loaded via get_config(), reading WATCH_DETAIL from environment variables
• The detail_budget variable is calculated by subtracting user-supplied cue timestamps from max_frames
• For efficient mode, the budget is passed to extract_keyframes
• For balanced and token-burner, the budget is passed to extract_scene_or_uniform; when None (token-burner), the engine preserves every detected frame

Extraction Engines (skills/watch/scripts/frames.py):

• extract_keyframes: Pulls pre-existing keyframes using yt-dlp metadata
• extract_scene_or_uniform: Runs ffmpeg scene detection and applies uniform sampling only if a cap is specified

Performance and Token Cost Trade-offs

Each mode represents a distinct optimization point:

• Efficient: Fastest execution, lowest token cost, best for quick video summaries or long content where only major visual changes matter
• Balanced: Moderate processing time, moderate token cost, optimal for standard video analysis where scene context is important but not exhaustive
• Token-burner: Highest processing time, potentially massive token consumption (hundreds of frames), suitable for detailed forensic analysis or short clips requiring frame-by-frame scrutiny

Usage Examples

Run the watch command with explicit detail modes to control extraction behavior:

# Fast preview with max 50 keyframes

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

# Standard analysis with scene detection capped at 100 frames

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

# Comprehensive coverage with unlimited frame extraction

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

Override default caps while maintaining the extraction engine:

# Balanced engine with custom frame limit

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

Summary

• Efficient mode uses extract_keyframes with a 50-frame cap, relying on existing video keyframes for maximum speed.
• Balanced mode uses extract_scene_or_uniform with a 100-frame cap, running ffmpeg scene detection for meaningful frame selection.
• Token-burner mode uses the same scene detection as balanced but sets detail_budget to None, removing frame limits entirely.
• Configuration caps are defined in skills/watch/scripts/config.py, while dispatch logic resides in skills/watch/scripts/watch.py lines 204-225.
• Token-burner triggers a warning when yielding more than 250 frames to alert users to high API costs.

Frequently Asked Questions

What is the default detail mode if I don't specify --detail?

The default detail mode is balanced, as defined by DEFAULT_DETAIL = "balanced" in skills/watch/scripts/config.py. You can override this by setting the WATCH_DETAIL environment variable or passing the --detail argument explicitly.

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

When token-burner mode generates more than 250 frames, watch.py lines 19-24 print a warning because each frame is encoded as an image token sent to the language model. Hundreds of frames can consume significant API quota and processing time, so the warning alerts users before incurring unexpected costs.

Can I use efficient mode but increase the frame cap?

No, the frame cap for efficient mode is hardcoded to 50 in the frame_cap() function within skills/watch/scripts/config.py. If you need more frames, you must switch to balanced mode (100 frames) or use --max-frames with balanced/token-burner modes, which use the scene-aware extraction engine rather than pure keyframe extraction.

Do balanced and token-burner use different scene detection algorithms?

No, both modes use the identical extract_scene_or_uniform function in skills/watch/scripts/frames.py. The only difference is the detail_budget parameter passed to this function: balanced passes a numeric cap (100), while token-burner passes None, causing the engine to preserve every detected scene-change frame without interpolation.

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