# How Claude-Video's Efficient, Balanced, and Token-Burner Detail Modes Differ

> Explore Claude-Video's detail modes: Efficient, Balanced, and Token-Burner. Understand how these options balance speed, frame count, and visual fidelity for your video analysis needs.

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

---

**Claude-Video's three detail modes trade speed against frame count and visual fidelity:** **efficient** uses fast keyframe-only extraction capped at 50 frames; **balanced** runs scene-change detection with a 100-frame cap; **token-burner** removes the cap entirely to capture every scene-change frame.

The `watch` command in [bradautomates/claude-video](https://github.com/bradautomates/claude-video) processes videos by extracting representative frames for AI analysis. The **detail mode** you select controls which extraction engine runs, how many frames are collected, and ultimately how many tokens your video analysis will consume. Understanding these differences helps you optimize for speed, cost, or comprehensive visual coverage.

## Frame Extraction Engines and Caps

Each detail mode maps to a specific combination of extraction logic and frame budget. These values are hardcoded in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) through the `frame_cap()` function.

| Detail Mode | Extraction Engine | Default Cap | Frame Selection Strategy |
|-------------|-------------------|-------------|--------------------------|
| **efficient** | `extract_keyframes` | 50 frames | Uses yt-dlp-derived **scene-change keyframes** only—no full-frame analysis |
| **balanced** | `extract_scene_or_uniform` | 100 frames | Runs **ffmpeg scene-change detection** to find meaningful boundaries, fills gaps with uniform frames if needed |
| **token-burner** | `extract_scene_or_uniform` | **unlimited** (`None`) | Same detector as balanced but keeps **every scene-change frame** regardless of count |

The `frame_cap()` function in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (lines 66-71) returns these values directly: `50` for efficient, `100` for balanced, and `None` for token-burner and transcript modes.

## Efficient Mode: Speed-Optimized Keyframe Extraction

**Efficient mode** is designed for rapid video previews with minimal token usage. It delegates frame selection entirely to the video's existing keyframe index.

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 204-210), the efficient branch calls:

```python
extract_keyframes(video_file, max_frames=detail_budget)

```

This method relies on **yt-dlp-derived scene-change keyframes** without running additional video analysis. Because it never invokes ffmpeg for scene detection, efficient mode completes significantly faster than the alternatives.

```bash

# Quick preview, maximum 50 keyframes

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

```

Use efficient mode when you need fast turnaround on long videos or when only a rough visual summary is required.

## Balanced Mode: Scene-Aware Sampling with Moderate Coverage

**Balanced mode** is the default (`DEFAULT_DETAIL` in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py)). It activates the more sophisticated `extract_scene_or_uniform` engine from [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

The scene-aware extractor:

1. Runs ffmpeg's scene-change detector to identify meaningful visual transitions
2. Keeps frames at detected scene boundaries
3. If the scene count falls below the cap, interpolates uniformly-spaced frames to reach the target of 100 frames

In [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 214-225), balanced mode passes `detail_budget=100` to constrain output:

```python
extract_scene_or_uniform(
    video_file,
    max_frames=detail_budget,  # 100 for balanced

    duration_hint=duration
)

```

```bash

# Default behavior—moderate coverage with scene intelligence

watch https://youtu.be/xyz

# Explicit equivalent:

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

```

Balanced mode suits most use cases where you need representative coverage without excessive token consumption.

## Token-Burner Mode: Maximum Visual Fidelity, Unlimited Frames

**Token-burner mode** removes the frame cap entirely to capture **every detected scene change**. It uses the same `extract_scene_or_uniform` engine as balanced but passes `None` as the budget.

From [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 214-225, when `detail == "token-burner"`:

```python
detail_budget = None  # No cap applied

# ...

extract_scene_or_uniform(
    video_file,
    max_frames=detail_budget,  # None = unlimited

    duration_hint=duration
)

```

The extraction keeps every scene-change frame detected by ffmpeg. For videos with frequent cuts—music videos, fast-paced tutorials, or montages—this can yield **hundreds of frames**.

[`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) includes a runtime warning (lines 19-24) that triggers when token-burner produces more than 250 frames, alerting users to potential high image-token costs.

```bash

# Comprehensive coverage—no frame limit

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

```

Use token-burner when visual completeness matters more than token economy, such as detailed content analysis or archival documentation.

## Configuration and Override Behavior

The detail mode flows through a consistent configuration pipeline in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py):

1. **Environment variable**: `WATCH_DETAIL` sets the default
2. **CLI override**: `--detail` argument takes precedence
3. **Budget calculation**: `detail_budget = max_frames - cue_frames` (cues subtract from your cap)
4. **Engine dispatch**: `efficient` → `extract_keyframes`; `balanced`/`token-burner` → `extract_scene_or_uniform`

You can also override caps manually regardless of mode:

```bash

# Balanced mode with custom 200-frame cap

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

# Token-burner with artificial limit (cap still applies)

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

```

## Performance and Cost Comparison

| Factor | Efficient | Balanced | Token-Burner |
|--------|-----------|----------|--------------|
| **Processing speed** | Fastest | Moderate | Slowest (more frames to encode) |
| **Frame count typical** | ≤50 | ≤100 | 50-500+ |
| **Scene intelligence** | None (keyframe-only) | Yes | Yes |
| **Token cost** | Lowest | Moderate | Highest |
| **Best for** | Quick previews, long videos | General analysis | Detailed review, short dense videos |

## Summary

- **Efficient mode** (`extract_keyframes`, 50-frame cap): Fastest option using pre-indexed keyframes without scene analysis.

- **Balanced mode** (`extract_scene_or_uniform`, 100-frame cap): Default scene-aware extraction that intelligently samples video content.

- **Token-burner mode** (`extract_scene_or_uniform`, no cap): Maximum frame capture for comprehensive visual analysis at higher token cost.

The `frame_cap()` function in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and the dispatch logic in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 204-225) implement these behaviors, with runtime warnings protecting against accidental high-frame outputs.

## Frequently Asked Questions

### What happens if I use token-burner on a very long video?

Token-burner keeps every scene-change frame without limit. For long videos with frequent cuts, this can exceed 250 frames and trigger a runtime warning in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py). The analysis will proceed, but your API costs will scale with frame count. Consider using `--max-frames` to impose a manual cap.

### Can I change the default frame caps?

The caps are defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (lines 66-71) within the `frame_cap()` function. To modify defaults permanently, edit this file or set `WATCH_DETAIL` environment variable and use `--max-frames` for per-run adjustments.

### Why does balanced mode sometimes use uniform frames instead of scene detection?

The `extract_scene_or_uniform` engine in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) prioritizes scene-change frames but fills gaps with uniform sampling when the detected scene count falls below your cap. This ensures you receive the full budget of frames for comprehensive coverage even in visually static videos.

### Is efficient mode always faster than balanced?

Yes. Efficient mode relies on existing keyframe metadata from yt-dlp without invoking ffmpeg scene detection. Balanced and token-burner both run the ffmpeg scene-change detector, which adds processing time proportional to video length and complexity.