# Efficient vs Balanced vs Token-Burner Detail Modes in Claude-Video

> Understand Claude-Video's efficient balanced and token burner detail modes. Learn how frame budgets and algorithms impact keyframe extraction for video analysis.

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

---

**The efficient, balanced, and token-burner detail modes in Claude-Video's watch skill differ primarily in their frame budgets and extraction algorithms—efficient limits output to 50 keyframes using a fast keyframe engine, balanced caps at 100 scene-aware frames, and token-burner removes the cap entirely to capture every scene change.**

The `watch` skill in the bradautomates/claude-video repository processes video content by extracting visual frames for AI analysis. The `detail` parameter controls both the quantity of frames extracted and the algorithm used to select them, allowing you to trade processing speed against visual completeness.

## Frame Budgets and Extraction Engines

The three modes share a common configuration system but apply different constraints on frame extraction. 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 maps each mode to a specific budget:

```python

# https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py#L65-L73

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

```

### Efficient Mode (50 Frames, Keyframe Engine)

**Efficient mode** prioritizes speed over coverage. It applies a hard cap of 50 frames and uses a fast keyframe extraction engine that selects only the most visually salient frames. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the code explicitly branches to use `extract_keyframes()` when this mode is active:

```python

# https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L198-L215

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

    frames, frame_meta = extract_scene_or_uniform(...)

```

Use this mode for quick previews where processing speed matters more than capturing every visual detail.

### Balanced Mode (100 Frames, Scene-Aware)

**Balanced mode** serves as the default configuration (`DEFAULT_DETAIL = "balanced"`). It increases the frame budget to 100 frames while using the scene-aware extraction engine. This engine samples frames based on detected scene changes, providing better visual coverage than keyframe selection while maintaining reasonable performance.

The mode is recommended for general-purpose video analysis where you need a representative sample without consuming excessive tokens.

### Token-Burner Mode (Unlimited Frames, Scene-Aware)

**Token-burner mode** removes the frame cap entirely (`None`), allowing the scene-aware engine to keep every detected scene-change frame across the entire video duration. This produces the richest visual context but generates significantly more tokens.

The CLI includes a warning threshold when this mode produces excessive frames:

```python

# https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L319-L322

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

```

Use this mode when you need deep visual analysis and token limits are not a concern.

## Implementation in the Source Code

The configuration logic resides in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), which defines the default mode and frame caps. The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) CLI entry point parses the `--detail` argument and selects the appropriate extraction engine:

```python

# https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L36-L40

ap.add_argument(
    "--detail",
    choices=["transcript", "efficient", "balanced", "token-burner"],
    help="Fidelity/speed dial: transcript (no frames), efficient (fast keyframes, cap 50), "
         "balanced (scene, cap 100), token-burner (scene, uncapped).",
)

```

The environment variable `WATCH_DETAIL` can also override the default without modifying CLI commands.

## Practical Usage Examples

Select a detail mode via the `--detail` flag when invoking the watch skill:

```bash

# Fast preview with maximum 50 keyframes

watch https://example.com/video.mp4 --detail efficient

# Default scene-aware sampling with 100-frame cap

watch https://example.com/video.mp4 --detail balanced

# Uncapped scene extraction for maximum detail

watch https://example.com/video.mp4 --detail token-burner

```

To inspect the current configuration programmatically:

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

cfg = get_config()
detail = cfg["detail"]          # e.g., "balanced"

cap = frame_cap(detail)        # Returns 100, or None for token-burner

print(f"Detail mode: {detail}, frame cap: {cap}")

```

## Summary

- **Efficient mode** uses a fast keyframe engine and limits output to **50 frames**, optimal for quick previews.
- **Balanced mode** is the default, using the **scene-aware engine** with a **100-frame cap** for general-purpose analysis.
- **Token-burner mode** uses the scene-aware engine with **no frame cap**, capturing every scene change for maximum visual context.
- The modes are configured in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).
- Unit tests in [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py) and [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py) validate the default settings and engine selection logic.

## Frequently Asked Questions

### What is the default detail mode in Claude-Video?

The default mode is **balanced**. This is defined by the `DEFAULT_DETAIL = "balanced"` constant in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). You can override this default by setting the `WATCH_DETAIL` environment variable or passing the `--detail` flag to the CLI.

### Which extraction engine does each mode use?

**Efficient mode** uses the `extract_keyframes()` function for fast keyframe selection, while **balanced** and **token-burner** modes both use `extract_scene_or_uniform()`. The distinction is made in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) where the code checks `if detail == "efficient"` to branch between the two engines.

### Why is the unlimited mode called "token-burner"?

The name reflects its behavior of generating a large number of frames—potentially hundreds depending on video length and scene complexity—which increases token consumption significantly. The source code includes a warning when this mode selects more than 250 frames to alert users to the high token cost.

### Can I use the detail modes without the CLI?

Yes. The configuration is accessible via the Python API by importing `get_config()` and `frame_cap()` from [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). The detail mode setting propagates through the configuration dictionary and affects the extraction logic when calling the watch skill's functions directly.