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

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

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

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

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

# 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 module implements the actual extraction logic shared across all detail modes, while 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, 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, 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, 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.

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