# Claude-Video Detail Modes: Controlling Frame Extraction and Token Usage

> Explore Claude-Video detail modes: transcript, efficient, balanced, and token-burner. Control frame extraction and token usage for optimal video analysis.

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

---

**The four Claude-Video detail modes—**transcript**, **efficient**, **balanced**, and **token-burner**—control how many frames are extracted from video content, ranging from zero frames (audio-only) to unlimited scene-change detection.**

The `bradautomates/claude-video` repository provides a powerful `watch` command for processing video content through AI analysis. By leveraging the `--detail` flag, you can precisely manage the trade-off between comprehensive visual coverage and token consumption, ensuring optimal performance for your specific use case.

## The Four Claude-Video Detail Modes

The `--detail` option accepts four distinct modes, each implemented in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) as the `DETAILS` configuration set and mapped to specific frame budgets.

### Transcript Mode

**Transcript** mode skips frame extraction entirely, producing only a text transcript from captions or Whisper speech recognition. This mode sets the frame cap to `None`, resulting in zero frames processed.

Use this mode when you only need spoken content or want to minimize token usage for audio-heavy videos.

### Efficient Mode

**Efficient** mode extracts fast-keyframes only, using a strict budget of approximately 50 frames. This provides a quick visual preview without processing every scene change.

Choose this mode when speed matters more than granular visual detail, such as when generating rapid summaries of long videos.

### Balanced Mode

**Balanced** mode serves as the default detail setting when no `--detail` flag is specified. It performs scene-aware extraction targeting approximately 100 frames, providing a comprehensive visual summary without excessive token consumption.

This mode offers the best general-purpose solution, balancing coverage and cost for most video analysis tasks.

### Token-Burner Mode

**Token-burner** mode extracts **all** scene-change frames without imposing a cap, setting the limit to `None` (unlimited). This produces the most exhaustive visual coverage possible.

Activate this mode for very long videos where you need complete scene detection, accepting significantly higher token usage in exchange for maximum visual fidelity.

## Implementation and Source Code

The detail mode system is implemented across two core files in the `bradautomates/claude-video` repository.

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the CLI registers the four choices as valid arguments for the `--detail` flag. The entrypoint parses this value, determines the appropriate frame cap, and drives the extraction process according to the selected mode.

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 allowed set of modes (`DETAILS`) and maps each mode to its default frame budget. This centralized configuration ensures consistent behavior across the application.

## Configuring Default Detail Modes

You can set a global default detail mode to avoid specifying `--detail` with every command. The system respects the `WATCH_DETAIL` environment variable, allowing you to define your preferred mode for all sessions:

```bash
export WATCH_DETAIL=efficient

```

Alternatively, store persistent configuration in `~/.config/watch/.env`:

```bash
echo "WATCH_DETAIL=token-burner" >> ~/.config/watch/.env

```

If you provide an invalid value, the system gracefully falls back to `balanced` mode as implemented in the configuration loading logic within [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).

## Command-Line Usage Examples

Process videos with specific detail modes using the `--detail` flag:

```bash

# Transcript-only (no frames)

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

# Fast keyframe extraction (≈50 frames)

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

# Balanced extraction (≈100 frames, default behavior)

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

# Unlimited scene extraction (all frames)

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

```

These examples demonstrate how to invoke each mode directly from the command line.

## Summary

- **Claude-Video detail modes** control frame extraction via the `--detail` flag in the `watch` command.
- **Four modes** are available: `transcript` (0 frames), `efficient` (≈50 frames), `balanced` (≈100 frames, default), and `token-burner` (unlimited).
- **Configuration** is defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), while argument parsing occurs in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).
- **Global defaults** can be set via the `WATCH_DETAIL` environment variable or `~/.config/watch/.env` file.
- **Balanced** mode provides the optimal trade-off for most use cases, while **token-burner** offers exhaustive coverage at higher token cost.

## Frequently Asked Questions

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

The default detail mode is **balanced**, which extracts approximately 100 frames using scene-aware detection. If you omit the `--detail` flag or provide an invalid value, the system automatically falls back to this setting as defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).

### How do I reduce token usage when processing videos?

Use **transcript** mode to skip frame extraction entirely, processing only audio content. Alternatively, **efficient** mode limits extraction to approximately 50 fast-keyframes, significantly reducing tokens compared to the default balanced mode or token-burner mode.

### When should I use token-burner mode instead of balanced?

Choose **token-burner** mode when analyzing very long videos where you require exhaustive visual coverage of every scene change. Unlike **balanced** mode, which caps extraction at approximately 100 frames, token-burner has no frame limit, making it ideal for detailed forensic analysis or comprehensive visual indexing where token cost is not a constraint.

### Where are detail mode configurations stored in the source code?

The valid detail modes and their frame budgets are defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) within the `DETAILS` configuration mapping. CLI argument validation occurs in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), while environment variable overrides are processed in the configuration module's loading logic.