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

> Understand Claude Video detail modes: Efficient (50 keyframes), Balanced (100 scene-aware frames), and Token-Burner (no cap). Optimize frame extraction for your needs.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-07-11

---

**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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), selecting `efficient` triggers the `extract_keyframes` engine from [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py):

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) routes both `balanced` and `token-burner` to the same extraction engine:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) computes the available `detail_budget` by accounting for any cue-timestamp frames:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) implements a safety warning when frame counts exceed 250:

```python
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:

```bash

# 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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), while extraction logic is dispatched from [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), while frame limits are defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).