# Claude Video Detail Modes: Efficient, Balanced, Token-Burner, and Transcript

> Explore Claude Video's detail modes: efficient, balanced, token-burner, and transcript. Understand their trade-offs in speed, token use, and visual context for optimal frame extraction.

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

---

**Claude Video's `--detail` flag controls frame extraction density through four modes—efficient, balanced, token-burner, and transcript—each trading off processing speed and token consumption against visual context richness.**

The `bradautomates/claude-video` repository implements a configurable video analysis pipeline that adapts to different computational budgets and accuracy requirements. The **Claude Video detail modes** determine how the [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script samples frames from video files before generating transcripts, directly impacting both API costs and analysis depth.

## How Detail Modes Work

The detail mode system centers on the `frame_cap()` function in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). This function returns specific frame limits based on the selected mode, while [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) orchestrates the extraction pipeline and handles mode-specific logic such as the transcript-only short-circuit.

## The Four Detail Modes Explained

### Efficient Mode (Key-Frame Sampling)

**Efficient mode** minimizes token usage by selecting only the strongest scene-change frames using a key-frame engine. In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), lines 66-68 implement this logic by returning a low frame cap when `detail == "efficient"`.

- **Frame count**: Often ≤30 frames regardless of video length
- **Best for**: Quick runs, short clips, or rough visual summaries where token cost is a primary concern
- **Trade-off**: May miss subtle scene changes due to sparse sampling

### Balanced Mode (Scene-Aware Sampling)

**Balanced mode** serves as the default configuration when no detail level is specified, employing a scene-aware engine that samples frames more densely while maintaining reasonable limits. The implementation in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (lines 70-71) sets a moderate cap for this mode.

- **Frame count**: Approximately 100 frames for a 5-minute clip
- **Best for**: General-purpose analysis requiring good visual coverage without excessive token consumption
- **Trade-off**: Uses more tokens and processing time than efficient mode, but provides substantially better visual context

### Token-Burner Mode (Maximum Visual Fidelity)

**Token-burner mode** prioritizes exhaustive visual analysis by retaining every detected scene-change frame. When `detail == "token-burner"`, the `frame_cap()` function in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (lines 72-73) returns `None`, effectively removing the frame cap and allowing unlimited extraction.

- **Frame count**: Can exceed 250 frames for longer videos; [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 319-322) issues a warning when this threshold is crossed
- **Best for**: Thorough analysis of visually complex content where missing any scene change would compromise results
- **Trade-off**: Heavy token consumption and increased processing latency; risks hitting model context limits

### Transcript Mode (Audio-Only Analysis)

**Transcript mode** bypasses frame extraction entirely, processing only the audio stream to generate text transcripts. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), lines 111-113 implement a short-circuit that skips visual analysis when `detail == "transcript"`, unless the user explicitly provides `--timestamps` cue points.

- **Frame count**: Zero visual frames (only cue-timestamps if provided via CLI)
- **Best for**: Dialogue-centric content where visual context is irrelevant and token conservation is critical
- **Trade-off**: Completely loses visual information such as on-screen text, slides, or scene context

## Command-Line Usage Examples

Execute these commands to leverage different detail modes based on your analysis requirements:

```bash

# Efficient mode for quick, low-token analysis

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

# Balanced mode (default) for general-purpose coverage

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

# Token-burner mode for exhaustive visual analysis

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

# Transcript mode for audio-only processing

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

# Transcript mode with specific timestamp frames

claude-video watch https://example.com/video.mp4 --detail transcript \
    --timestamps 10,45,120

```

## Summary

- **Efficient mode** uses key-frame sampling (≤30 frames) for minimal token consumption in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).
- **Balanced mode** provides scene-aware sampling (~100 frames/5min) as the default fallback when configuration is missing.
- **Token-burner mode** removes frame caps entirely, allowing unlimited scene-change detection but warning users at >250 frames in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).
- **Transcript mode** eliminates frame extraction completely through the short-circuit logic at lines 111-113 of [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).
- Select modes based on your token budget, video length, and whether visual context is essential for accurate analysis.

## Frequently Asked Questions

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

When the `--detail` flag is omitted, Claude Video defaults to **balanced mode**. This fallback is implemented in the configuration layer to ensure moderate frame sampling that balances token usage with visual coverage for general-purpose video analysis.

### How does token-burner mode handle extremely long videos?

Token-burner mode does not impose a hard frame limit in `frame_cap()`, allowing the scene-aware engine to extract every detected scene change. However, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 319-322) issues a warning when frame counts exceed 250, alerting users to potential token limit issues and increased processing costs.

### Can I extract specific frames while using transcript mode?

Yes. While transcript mode normally skips all frame extraction as implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 111-113), you can preserve specific visual context by providing the `--timestamps` argument with comma-separated seconds (e.g., `--timestamps 10,45,120`). This extracts frames only at the specified cue points while still bypassing automated scene detection.

### Which detail mode should I use for analyzing presentation slides?

For presentation videos where slide changes carry critical information, **token-burner mode** is recommended despite higher token costs. The mode ensures no slide transitions are missed by the scene-aware engine. If token budgets are constrained, **balanced mode** provides a reasonable middle ground, while **efficient mode** risks skipping rapid slide changes due to its sparse key-frame sampling.