Claude Video Detail Modes Explained: Efficient, Balanced, and Token-Burner

The three Claude Video detail modes control how many frames are extracted from video—efficient caps at 50 keyframes, balanced caps at 100 scene-aware frames (default), and token-burner removes the cap entirely to capture every scene change.

The bradautomates/claude-video repository provides a CLI tool for processing video content with Claude AI. The Claude Video detail modes determine the frame extraction strategy, directly impacting token consumption and analysis depth. These modes are configured via the --detail flag and implemented in the configuration and frame extraction modules.

Efficient Mode: Fast Keyframe Extraction (50 Frame Cap)

The efficient mode prioritizes speed and minimal token usage by extracting only sharp scene-change keyframes.

How It Works

In skills/watch/scripts/watch.py, selecting efficient triggers the extract_keyframes engine from skills/watch/scripts/frames.py. This detector quickly identifies keyframes without analyzing scene context beyond sharp transitions.

The frame budget is strictly capped at 50 frames according to the frame_cap function in skills/watch/scripts/config.py:

def frame_cap(detail: str) -> int | None:
    if detail == "efficient":   return 50
    if detail == "balanced":    return 100
    if detail == "token-burner":return None   # uncapped

When to Use Efficient Mode

Use this mode for short clips or when you need a quick overview with minimal tokens. The hard cap of 50 frames prevents excessive processing while maintaining visual context through key transitions.

Balanced Mode: Scene-Aware Sampling (Default, 100 Frame Cap)

The balanced mode provides broader coverage by mixing scene-change detection with uniform sampling, making it suitable for general-purpose video analysis.

Implementation Details

As the default mode (DEFAULT_DETAIL = "balanced" in skills/watch/scripts/config.py), balanced uses the extract_scene_or_uniform engine rather than simple keyframe detection. This engine analyzes scene context while maintaining a 100-frame hard cap to control costs.

The dispatch logic in skills/watch/scripts/watch.py routes both balanced and token-burner to the same extraction engine:

if detail == "efficient":
    frames, frame_meta = extract_keyframes(...)
else:  # balanced or token-burner

    frames, frame_meta = extract_scene_or_uniform(...)

Frame Budget Calculation

Before extraction, watch.py computes the available detail_budget by accounting for any cue-timestamp frames:

detail_budget = max_frames if max_frames is None else max(0, max_frames - len(cue_frames))

For balanced mode, max_frames resolves to 100 via the frame_cap lookup.

Token-Burner Mode: Uncapped Scene Extraction

The token-burner mode removes frame limits entirely, capturing every scene-aware frame detected by the extract_scene_or_uniform engine.

Unlimited Frame Budget

When detail is set to token-burner, the frame_cap function returns None, signaling no upper limit. This allows the extraction engine to keep all detected scene changes, which can result in hundreds of frames for long or complex videos.

Warning System for High Frame Counts

Because uncapped extraction can consume significant tokens, skills/watch/scripts/watch.py implements a safety warning when frame counts exceed 250:

if detail == "token-burner" and len(frames) > 250:
    print("> **Warning:** token-burner detail selected {len(frames)} frames …")

This alert helps users understand when they are approaching token-intensive territory.

Practical Usage Examples

Command Line Interface

Run the watch command with the --detail flag to specify your mode:

# Efficient – fast keyframes, max 50 frames

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

# Balanced – default, scene-aware, max 100 frames

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

# Token-burner – uncapped scene-aware frames

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

Programmatic Configuration Access

Inspect the default detail mode and frame caps programmatically:

from skills.watch.scripts.config import get_config, frame_cap

# Check default configuration

cfg = get_config()
print(cfg["detail"])          # → "balanced"

# Inspect caps for each mode

print(frame_cap("efficient"))    # 50

print(frame_cap("balanced"))     # 100

print(frame_cap("token-burner")) # None (no cap)

Summary

• Efficient mode uses extract_keyframes with a 50-frame cap for fast, token-minimal analysis.
• Balanced mode (default) uses extract_scene_or_uniform with a 100-frame cap for general-purpose scene coverage.
• Token-burner mode removes caps entirely (None), keeping all scene-aware frames and warning when exceeding 250 frames.
• Configuration resides in skills/watch/scripts/config.py, while extraction logic is dispatched from skills/watch/scripts/watch.py.
• Frame budgets are calculated by subtracting cue frames from the mode's maximum before extraction begins.

Frequently Asked Questions

What is the default detail mode in Claude Video?

Balanced is the default mode. The DEFAULT_DETAIL = "balanced" constant in skills/watch/scripts/config.py ensures that unless overridden via the --detail flag or environment variables, the tool extracts scene-aware frames with a 100-frame cap.

How does token-burner mode affect Claude API costs?

Token-burner mode removes the frame cap entirely, allowing extract_scene_or_uniform to return unlimited frames. Since Claude charges per token and each frame consumes tokens based on resolution, this mode can significantly increase API costs. The system prints a warning when more than 250 frames are extracted to alert you to potential high token usage.

Can I use efficient mode for long videos?

While technically possible, efficient mode limits extraction to 50 keyframes via extract_keyframes, which may provide insufficient coverage for very long videos. For content over several minutes, balanced mode (100 frames) or token-burner mode (unlimited) typically provides better analysis granularity, though at higher token costs.

Where is the frame extraction logic implemented?

The extraction engines are implemented in skills/watch/scripts/frames.py, which provides extract_keyframes for efficient mode and extract_scene_or_uniform for balanced and token-burner modes. The dispatch logic and budget calculations reside in skills/watch/scripts/watch.py, while frame limits are defined in skills/watch/scripts/config.py.

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