# Claude-Video Detail Modes Explained: efficient vs balanced vs token-burner vs transcript

> Understand Claude-Video detail modes: efficient, balanced, token-burner, and transcript. Learn how each mode controls frame extraction for optimal video analysis and transcript generation.

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

---

**The four `--detail` modes in Claude-Video control how many frames are extracted from a video: `efficient` uses keyframes only, `balanced` (default) uses scene-aware sampling, `token-burner` keeps all scene-change frames up to 250, and `transcript` skips frames entirely to return only the Whisper transcript.**

Claude-Video's **watch** skill offers granular control over visual frame extraction through the `--detail` flag. Each mode determines the underlying frame-selection engine, the resulting token budget, and whether video analysis prioritizes speed, coverage, or audio-only content. Understanding these differences ensures you choose the right trade-off between information density and API cost.

## How Detail Modes Map to Frame Engines

The `DETAILS` configuration in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) defines four string constants that drive distinct behavior in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). Here's how each mode operates at the code level:

### `efficient` Mode: Keyframe-Only Extraction

- **Engine label:** `"keyframes"`  
- **Behavior:** Selects only the most essential frames—typically major scene-change moments.  
- **Frame budget:** Lowest among visual modes; minimizes token consumption by aggressively filtering duplicates.  

Use `efficient` when you need rapid, low-cost summaries and can tolerate sparse visual coverage.

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

```

### `balanced` Mode: Scene-Aware Sampling (Default)

- **Engine label:** `"scene-aware frames"`  
- **Behavior:** Samples frames more densely than `efficient` while respecting the user-specified frame cap.  
- **Frame budget:** Moderate; the default `DEFAULT_DETAIL` value.  

This mode is defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) as the fallback when no `--detail` argument is provided, and confirmed by [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py) lines 7-13.

```bash
watch https://example.com/video.mp4               # uses balanced by default

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

```

### `token-burner` Mode: Maximum Visual Coverage

- **Engine label:** Scene-aware engine with **disabled or dramatically raised frame cap**  
- **Behavior:** Retains **all** scene-change frames, subject to a hard warning limit of 250 frames: `if len(frames) > 250`  
- **Frame budget:** Highest; deliberately trades token efficiency for comprehensive visual context.  

Select `token-burner` when the analysis demands maximum visual fidelity and you accept higher API costs.

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

```

### `transcript` Mode: Audio-Only Analysis

- **Engine label:** *None* (frame extraction skipped entirely)  
- **Behavior:** Returns only the Whisper-generated transcript or captions. If no transcript is available, the code **falls back to `balanced` frames**.  
- **Frame budget:** Zero (unless fallback occurs).  

Ideal for audio-centric workflows or when visual content is irrelevant.

```bash
watch https://example.com/video.mp4 --detail transcript

```

## Configuration and Environment Overrides

The `frame_cap(detail)` function in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (lines 51-73) maps each mode to its numeric frame budget. You can override the default mode without passing `--detail` on every command:

```bash
export WATCH_DETAIL=efficient
watch https://example.com/video.mp4      # runs in efficient mode

```

Environment precedence is validated in [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py).

## Core Implementation Files

| File | Purpose |
|------|---------|
| [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) | Defines `DETAILS` list, `DEFAULT_DETAIL = "balanced"`, and `frame_cap(detail)` budget mapping |
| [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) | Parses `--detail` argument, selects engine label, applies caps, and issues 250-frame warnings |
| [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py) | Unit tests for default mode and environment variable overrides |
| [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) | Reports `watch_detail: "balanced"` as the configured default |

## Summary

- **`efficient`** → keyframe engine, minimal tokens, fastest execution  
- **`balanced`** → scene-aware engine, moderate coverage, **default** behavior  
- **`token-burner`** → all scene-change frames, up to 250, maximum token usage  
- **`transcript`** → Whisper audio only, with `balanced` fallback when unavailable  

Each mode is implemented in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and executed through [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), giving you precise control over Claude-Video's visual analysis pipeline.

## Frequently Asked Questions

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

Claude-Video defaults to **`balanced`** mode. This is hard-coded as `DEFAULT_DETAIL = "balanced"` in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and verified by test assertions in [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py).

### Will `token-burner` mode ever exceed 250 frames?

No. The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) implementation enforces a hard warning threshold: `if len(frames) > 250`. While the mode disables the standard frame cap, the 250-frame safety limit prevents runaway token consumption.

### Can I use `--detail transcript` if the video has no audio track?

Yes, but the behavior changes. When no Whisper transcript is available, the code automatically falls back to **`balanced`** frame extraction. You will receive visual frames instead of an empty response.

### How do I permanently change my default detail mode?

Set the `WATCH_DETAIL` environment variable to any valid mode (`efficient`, `balanced`, `token-burner`, or `transcript`). This overrides `DEFAULT_DETAIL` without modifying the source code or passing `--detail` on every command.