# Efficient, Balanced, and Token-Burner Detail Modes in Claude-Video: A Technical Comparison

> Explore Claude-Video's efficient balanced and token-burner modes. Understand the tradeoffs between speed and frame density to choose the best settings for your video processing needs.

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

---

**Claude-Video's three detail modes trade off processing speed against frame density, with efficient mode extracting up to 50 keyframes, balanced mode capturing up to 100 scene-change frames, and token-burner mode keeping every detected scene without limits.**

The open-source `claude-video` repository provides a `watch` command for AI-powered video analysis that supports three distinct **detail modes**—efficient, balanced, and token-burner—each designed for different use cases ranging from quick previews to comprehensive frame-by-frame analysis. These modes determine how frames are extracted from video sources and directly impact both processing time and token consumption when sending visual data to Claude.

## What Are Claude-Video Detail Modes?

Detail modes in `claude-video` control the **frame-extraction engine** and the **maximum frame budget** used when processing video content. According to the source code in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the `frame_cap()` function assigns specific limits to each mode: 50 frames for efficient, 100 frames for balanced, and `None` (unlimited) for token-burner.

The mode selection determines whether the tool uses fast keyframe indexing or computationally expensive scene-change detection, directly affecting both the temporal granularity of the analysis and the cost of API calls.

## The Three Detail Modes Explained

### Efficient Mode (Keyframe Extraction)

**Efficient mode** prioritizes speed by leveraging existing video metadata rather than analyzing frame content. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 204-210), this mode invokes the `extract_keyframes` function, which uses `yt-dlp`-derived scene-change keyframes exclusively.

- **Frame cap**: 50 frames maximum
- **Engine**: Keyframe-only extraction (`extract_keyframes`)
- **Performance**: Fastest option; no full-frame analysis required
- **Best for**: Quick previews, metadata scanning, or short video summaries

This mode never runs ffmpeg-based scene detection, making it ideal when you need rapid results and can sacrifice granular visual detail.

### Balanced Mode (Scene-Aware with Cap)

**Balanced mode** offers a middle ground by running actual scene-change detection while maintaining reasonable token limits. As implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 214-225), this mode calls `extract_scene_or_uniform` with a hard cap of 100 frames.

- **Frame cap**: 100 frames maximum
- **Engine**: Scene-aware extraction (`extract_scene_or_uniform`)
- **Performance**: Moderate; requires ffmpeg-based scene detection
- **Best for**: General-purpose analysis where you need meaningful scene boundaries without excessive token usage

When scene detection produces fewer frames than the cap, the engine fills gaps with uniformly spaced frames to maximize coverage. This is the **default mode** when `WATCH_DETAIL` is unset or `--detail` is not specified.

### Token-Burner Mode (Unlimited Scene Detection)

**Token-burner mode** maximizes visual fidelity by removing all frame limits. It uses the same `extract_scene_or_uniform` engine as balanced mode but passes `None` as the `detail_budget`, instructing the extractor to keep every detected scene-change frame regardless of count.

- **Frame cap**: Unlimited (no cap)
- **Engine**: Scene-aware extraction without limits
- **Performance**: Slowest; generates hundreds of frames for long videos
- **Best for**: Deep analysis of short clips or when maximum visual context is required

The source code includes a runtime warning (lines 19-24 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)) that triggers when this mode yields more than 250 frames, alerting users to potentially high image-token costs.

## How Detail Modes Work Under the Hood

The selection logic follows a clear architectural flow through the codebase:

1. **Configuration loading**: `get_config()` in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) reads the `WATCH_DETAIL` environment variable or falls back to `DEFAULT_DETAIL` ("balanced")
2. **Argument parsing**: The `--detail` CLI flag can override the configuration value
3. **Budget calculation**: The system calculates `detail_budget` by applying the mode-specific cap from `frame_cap()`, reduced by any user-supplied cue timestamps
4. **Engine dispatch**: 
   - If `detail == "efficient"`, the system calls `extract_keyframes` with `max_frames = detail_budget`
   - For `balanced` or `token-burner`, it calls `extract_scene_or_uniform` with the same budget parameter; when `detail_budget` is `None` (token-burner), the engine preserves every detected scene

The [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) module implements both extraction strategies: `extract_keyframes` simply indexes existing keyframes, while `extract_scene_or_uniform` runs ffmpeg's scene-change detector and optionally interpolates uniform frames when operating under a cap.

## Usage Examples

Run the `watch` command with your preferred detail mode using the `--detail` flag:

```bash

# Fast preview using keyframes only (max 50 frames)

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

# Standard analysis with scene detection (max 100 frames)

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

# Comprehensive analysis with unlimited frames

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

```

Override the default caps manually while keeping the scene-detection engine:

```bash

# Balanced mode with custom frame limit

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

```

Set a persistent default via environment variable:

```bash
export WATCH_DETAIL=efficient
watch https://youtu.be/xyz

```

## Summary

- **Efficient mode** uses `extract_keyframes` for speed, capping at 50 frames and relying solely on existing video keyframes.
- **Balanced mode** employs `extract_scene_or_uniform` with a 100-frame limit, running ffmpeg scene detection for meaningful boundaries.
- **Token-burner mode** utilizes the same scene detection but sets `detail_budget` to `None`, preserving every scene-change frame regardless of quantity.
- Configuration resides in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), while dispatch logic lives in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 204-225).
- Balanced is the default mode, but you can override via `WATCH_DETAIL` environment variable or `--detail` CLI argument.

## Frequently Asked Questions

### Which detail mode should I use for long videos?

For videos longer than 10 minutes, **efficient mode** prevents timeout issues and excessive token costs by limiting extraction to 50 keyframes. If you need specific scene analysis on long content, use **balanced mode** with a custom `--max-frames` value rather than token-burner, which could generate hundreds of frames and significantly increase API costs.

### Can I override the default frame limits without changing modes?

Yes. While each mode has internal defaults defined in `frame_cap()` (50 for efficient, 100 for balanced, unlimited for token-burner), you can pass `--max-frames` to set a hard ceiling regardless of mode. The system calculates `detail_budget` as the minimum of your mode's cap and any user-supplied maximum.

### Why does token-burner mode trigger a warning?

When **token-burner mode** generates more than 250 frames, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) prints a runtime warning (lines 19-24) because each frame consumes image tokens when sent to Claude's API. This alert prevents accidental high-cost operations when processing videos with frequent scene changes or extended duration.

### What happens if I don't specify a detail mode?

The system defaults to **balanced mode**. According to [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the `DEFAULT_DETAIL` constant is set to `"balanced"`, and `get_config()` uses this value when the `WATCH_DETAIL` environment variable is unset and no `--detail` argument is provided.