# Claude Video Detail Modes Explained: Efficient vs Balanced vs Token-Burner vs Transcript

> Explore Claude video detail modes: Efficient, Balanced, Token-Burner, and Transcript. Understand trade-offs in token usage, latency, and visual context for optimal video processing.

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

---

**The `--detail` flag in bradautomates/claude-video offers four distinct processing modes—efficient, balanced, token-burner, and transcript—that trade off token consumption, processing latency, and visual context richness by controlling how frames are extracted from video content.**

The open-source `bradautomates/claude-video` repository provides a video analysis pipeline that preprocesses media before sending it to Claude. Central to this pipeline is the frame extraction logic defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), where the `frame_cap()` function determines how aggressively to sample visual content based on the selected detail mode.

## Efficient Mode: Key-Frame Extraction for Low-Token Analysis

**Efficient mode** minimizes token usage by employing a key-frame engine that selects only the strongest scene-change frames. In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the logic at lines 66-68 implements this by returning a conservative frame cap when `detail == "efficient"`, typically resulting in 30 or fewer frames regardless of video length.

This mode is ideal for quick runs or cost-sensitive operations where you need only a rough visual summary. However, the aggressive sampling may miss subtle scene changes, potentially omitting important visual context that appears between major transitions.

```bash

# Run with efficient detail mode for minimal token consumption

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

```

## Balanced Mode: Scene-Aware Sampling for General Use

**Balanced mode** serves as the default configuration and implements a scene-aware engine that samples frames more densely while maintaining reasonable limits. According to lines 70-71 in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), this mode strikes a middle ground, typically extracting approximately 100 frames for a five-minute clip.

When the configuration is missing or invalid, the system falls back to balanced mode automatically. This provides sufficient visual coverage for most analysis tasks without the excessive token costs associated with more aggressive sampling strategies.

```bash

# Use balanced mode for general-purpose analysis (default behavior)

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

```

## Token-Burner Mode: Exhaustive Visual Coverage

**Token-burner mode** disables frame caps entirely, keeping every detected scene-change frame to maximize visual fidelity. As implemented in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) at lines 72-73, the `frame_cap()` function returns `None` for this mode, allowing the extraction engine to process an unlimited number of frames.

The main orchestration script in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 319-322) includes a safeguard that warns users when more than 250 frames are selected, as this can lead to heavy token consumption and potential model context limit issues. Use this mode only when exhaustive visual detail is critical, such as analyzing dense slide presentations or complex visual narratives.

```bash

# Extract maximum frames for thorough visual analysis

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

```

## Transcript Mode: Audio-Only Analysis

**Transcript mode** bypasses frame extraction entirely, processing only the audio stream to generate text transcripts without visual context. The pipeline short-circuits at lines 111-113 in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) when `detail == "transcript"`, resulting in zero visual frames unless explicitly overridden with the `--timestamps` flag.

This mode is optimal for dialogue-centric content where spoken information carries the primary value, offering maximum token efficiency. However, if the video contains essential visual cues like on-screen text, charts, or scene-specific details, this information will be lost entirely.

```bash

# Process audio only for minimal token usage

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

# Combine transcript mode with specific frame timestamps

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

```

## Technical Implementation and Frame Pipeline

The frame extraction architecture spans three core files within the repository. The [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) module implements the actual extraction logic shared across all detail modes, while [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) orchestrates the pipeline selection and applies the 250-frame warning for token-burner mode. Configuration defaults and environment overrides are validated in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), ensuring that invalid detail parameters fall back to balanced mode safely.

## Summary

- **Efficient mode** minimizes costs with ≤30 key frames but risks missing subtle visual changes.
- **Balanced mode** provides the default scene-aware sampling (~100 frames for 5-minute content) suitable for general analysis.
- **Token-burner mode** captures all scene changes with no upper limit, triggering warnings at >250 frames due to high token consumption.
- **Transcript mode** eliminates frame extraction entirely for audio-only processing, conserving maximum tokens while sacrificing visual context.

## Frequently Asked Questions

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

The system defaults to **balanced** mode when the `--detail` flag is omitted or when an invalid configuration is detected. This fallback behavior is implemented in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), ensuring consistent behavior even with missing environment variables or corrupted settings files.

### How many frames does token-burner mode typically extract?

Token-burner mode extracts **every detected scene-change frame** with no artificial cap, often exceeding 250 frames for longer videos. According to the source code in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the system issues a warning when frame counts exceed 250 to alert users about potential token limit issues.

### Can I combine transcript mode with specific frame timestamps?

Yes. While transcript mode skips automatic frame extraction, you can use the `--timestamps` flag to specify exact seconds where frames should be captured. This hybrid approach allows you to maintain low token usage for the majority of the video while retaining visual context at critical moments specified in the command.

### Which detail mode uses the least tokens?

**Transcript mode** consumes the fewest tokens by completely bypassing frame extraction, sending only the audio transcript to the model. **Efficient mode** offers the lowest token usage among modes that include visual analysis, typically processing 30 or fewer frames compared to balanced mode's ~100 or token-burner's unlimited extraction.