# Claude Video `--detail` Transcript vs Frame-Based Modes: A Complete Guide

> Explore Claude Video's --detail transcript vs frame-based modes. Understand the trade-offs in speed token usage and visual context for efficient video analysis.

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

---

**The `--detail` flag in `bradautomates/claude-video` controls whether the `watch` skill processes only textual content (skipping video download) or extracts visual frames from the video, with four distinct modes offering different trade-offs between speed, token usage, and visual context.**

The `watch` skill in the `bradautomates/claude-video` repository provides intelligent video analysis for Claude, allowing users to process YouTube URLs and local video files. Understanding the difference between `--detail transcript` and the frame-based modes is essential for optimizing both performance and cost when analyzing video content.

## Understanding the `--detail` Flag

The `--detail` argument accepts four values defined in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 35-40: `transcript`, `efficient`, `balanced`, and `token-burner`. This parameter determines the processing pipeline, download behavior, and frame extraction strategy used by the tool.

Each mode serves a specific use case, ranging from pure text analysis to comprehensive visual inspection, with implementation logic residing primarily in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

## Transcript-Only Mode (`--detail transcript`)

Transcript mode prioritizes speed and token efficiency by avoiding video download and frame extraction entirely, focusing solely on spoken content.

### How It Works

When `--detail transcript` is specified, the tool **does not download the video** unless the user also provides specific timestamps via `--timestamps`. The pipeline follows this sequence:

1. **Caption fetching**: The tool attempts to retrieve existing captions using `yt-dlp` via the `fetch_captions` function
2. **Caption parsing**: Available captions are parsed using `parse_vtt` and formatted via `format_transcript`
3. **Whisper fallback**: If captions are unavailable and Whisper fallback is enabled, the tool performs an **audio-only download** by setting `audio_only = True`, then transcribes the audio
4. **Frame bypass**: No frames are extracted, resulting in a markdown report containing only the transcript section and a note indicating frames were skipped

This mode is ideal when you need only the spoken content and want to eliminate the token costs associated with image analysis.

### Implementation Details

The logic controlling this behavior appears in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) line 111:

```python
audio_only = detail == "transcript" and not cue_timestamps

```

Frame extraction is explicitly bypassed based on the condition in lines 96-100:

```python
if detail != "transcript" and video_path and detail_budget != 0:
    # Frame extraction logic executes here

```

## Frame-Based Modes (`efficient`, `balanced`, `token-burner`)

The three visual modes download the full video (unless timestamps force audio-only retrieval) and extract representative frames using different engines and budget constraints.

### Efficient Mode

**`--detail efficient`** uses **keyframes** (I-frames) via the `extract_keyframes` function, providing the fastest visual processing with minimal token consumption.

- **Engine**: Cheap extraction of existing keyframes from the video stream
- **Frame cap**: Approximately 50 frames (controlled by `max_frames` default)
- **Use case**: Long videos where you need basic visual context without excessive token usage

### Balanced Mode

**`--detail balanced`** employs **scene-aware frame extraction** using `extract_scene_or_uniform`, offering better visual coverage than efficient mode.

- **Engine**: Scene-change detection to capture meaningful visual transitions
- **Frame cap**: Approximately 100 frames by default
- **Use case**: Standard analysis requiring moderate visual detail and reasonable token costs

### Token-Burner Mode

**`--detail token-burner`** maximizes visual detail by removing frame limits while using the same scene-detection engine as balanced mode.

- **Engine**: Scene-aware extraction via `extract_scene_or_uniform`
- **Frame cap**: Uncapped (`max_frames = None`)
- **Use case**: Short, content-dense videos where maximum visual context justifies higher token consumption

### Common Frame Processing Pipeline

All frame-based modes share additional processing steps defined in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py):

1. **Budget calculation**: The `auto_fps` and `auto_fps_focus` functions (lines 22-59) calculate appropriate FPS targets based on video duration
2. **Timestamp integration**: Frames specified via `--timestamps` are always extracted and counted against the cap
3. **Deduplication**: Near-duplicate frames are removed using `dedupe_perceptual` unless `--no-dedup` is specified

The engine selection logic in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 96-100 determines whether to call `extract_keyframes` (for `efficient`) or `extract_scene_or_uniform` (for `balanced` and `token-burner`).

## Practical Usage Examples

Choose your mode based on whether you need spoken content only or visual analysis:

```bash

# Transcript-only: fastest, no video download, text only

watch https://youtube.com/watch?v=example --detail transcript

# Efficient: keyframes only, ~50 frame limit

watch https://youtube.com/watch?v=example --detail efficient

# Balanced: scene detection, ~100 frame limit

watch https://youtube.com/watch?v=example --detail balanced

# Token-burner: scene detection, unlimited frames

watch https://youtube.com/watch?v=example --detail token-burner

# Combine transcript mode with specific timestamps

watch https://youtube.com/watch?v=example --detail transcript \
    --timestamps "00:12,01:05,02:30"

```

## Summary

- **`--detail transcript`** skips video download and frame extraction, processing only captions or audio transcription via `fetch_captions` and `format_transcript`, making it the most token-efficient option.

- **Frame-based modes** (`efficient`, `balanced`, `token-burner`) all download the full video and extract visual frames, differing primarily in their extraction engines (`extract_keyframes` vs `extract_scene_or_uniform`) and frame budget caps.

- The `efficient` mode uses keyframes with a ~50 frame cap, `balanced` uses scene detection with a ~100 frame cap, and `token-burner` uses scene detection without caps.

- All modes respect `--timestamps` inputs, and frame-based modes apply perceptual deduplication via `dedupe_perceptual` unless disabled.

## Frequently Asked Questions

### Does transcript mode download any video data?

Transcript mode avoids video download entirely unless you provide timestamps via `--timestamps`. As implemented in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) line 111, the tool sets `audio_only = True` only when captions are unavailable and Whisper fallback is enabled, downloading just the audio stream rather than the full video file.

### Which mode should I use for long videos?

For long videos where token conservation matters, use `--detail efficient` to extract only keyframes with a ~50 frame cap, or `--detail transcript` if you only need the spoken content. The `efficient` mode's use of `extract_keyframes` provides visual context without the computational overhead of scene detection.

### Can I combine timestamps with transcript mode?

Yes. Supplying `--timestamps` forces the tool to download video segments even in transcript mode. According to the logic in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), when `cue_timestamps` is present, the `audio_only` flag remains false, allowing frame extraction at your specified timestamps while still skipping the full frame analysis pipeline.

### What happens if captions are unavailable in transcript mode?

If captions are unavailable and Whisper fallback is enabled, the tool downloads only the audio track and processes it through Whisper for transcription. This fallback ensures you still receive textual content without incurring the bandwidth and processing costs of full video download and frame extraction.