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

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 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.

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 line 111:

audio_only = detail == "transcript" and not cue_timestamps

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

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:

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 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:

# 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}