Default Frame Caps for Claude Video Detail Modes: A Complete Guide

Claude Video applies specific frame caps to control processing costs: 50 frames for "efficient" mode, 250 frames for "balanced" mode, unlimited frames for "token-burner" mode, and zero frames for "transcript" mode.

The bradautomates/claude-video repository provides intelligent video processing capabilities with configurable detail modes that determine how many key frames are extracted from source material. Understanding the default frame caps for each Claude Video detail mode helps developers optimize token usage and processing time when analyzing video content.

Where Frame Caps Are Defined

The frame_cap function in skills/watch/scripts/config.py (lines 65–72) maps each detail mode to its default frame budget. This configuration drives how many key frames the extraction engine preserves during processing, with the skills/watch/scripts/watch.py module consuming these values to enforce limits during execution.

Default Frame Caps by Detail Mode

Claude Video supports four distinct detail modes, each with a specific default frame cap hardcoded in the source configuration:

Efficient Mode: 50 Frames The "efficient" detail mode caps processing at 50 frames, selecting only the most essential scene-change frames to minimize token consumption and processing time.

Balanced Mode: 250 Frames As the default mode when no detail is specified, "balanced" provides a 250-frame cap that offers richer visual context while maintaining reasonable computational costs.

Token-Burner Mode: Unlimited The "token-burner" mode returns None from the frame_cap function, effectively placing no limit on frame extraction. This preserves every detected scene-change frame regardless of quantity, maximizing context at the expense of higher token usage.

Transcript Mode: No Frames The "transcript" detail mode sets the frame cap to None, indicating no frames are extracted. The processor skips visual analysis entirely and returns only the automatically generated text transcript.

Implementation in the Source Code

In skills/watch/scripts/config.py, the frame_cap function implements this mapping logic:

from skills.watch.scripts.config import frame_cap

# Retrieve default caps for each mode

print(frame_cap('efficient'))     # Output: 50

print(frame_cap('balanced'))      # Output: 250

print(frame_cap('token-burner'))  # Output: None

print(frame_cap('transcript'))    # Output: None

When frame_cap returns an integer, the extraction engine in skills/watch/scripts/watch.py limits the frame list to that count. When it returns None, the engine either processes all detected frames (token-burner) or skips frame extraction entirely (transcript).

Overriding Default Frame Caps

You can override these defaults through command-line arguments or environment variables, which take precedence over the hardcoded values in skills/watch/scripts/config.py.

Using the CLI:

# Use default balanced mode (250 frames)

claude-video watch https://youtu.be/example

# Request efficient mode (50 frames)

claude-video watch https://youtu.be/example --detail efficient

# Set custom cap regardless of mode

claude-video watch https://youtu.be/example --max-frames 100

Using environment variables:

export WATCH_DETAIL=efficient
export WATCH_MAX_FRAMES=75
claude-video watch https://youtu.be/example

The WATCH_MAX_FRAMES environment variable and --max-frames flag allow you to specify hard numeric limits that supersede the default mode-based caps.

Summary

• Mode-specific defaults: 50 frames for efficient, 250 for balanced, unlimited (None) for token-burner, and zero (None) for transcript mode.
• Configuration location: Default mappings reside in skills/watch/scripts/config.py within the frame_cap function.
• Runtime customization: Use --max-frames or WATCH_MAX_FRAMES to override defaults; use --detail or WATCH_DETAIL to select modes.
• Token-burner behavior: Returns None to preserve all scene-change frames without limitation.
• Transcript behavior: Returns None to disable frame extraction entirely, processing only audio-to-text.

Frequently Asked Questions

How do I override the default frame cap for a specific detail mode?

Use the --max-frames flag when invoking the watch command or set the WATCH_MAX_FRAMES environment variable. This numeric value takes precedence over the default caps returned by the frame_cap function in skills/watch/scripts/config.py.

What happens if I set the detail mode to "token-burner"?

The token-burner mode returns None from frame_cap, which signals the frame extraction engine in skills/watch/scripts/watch.py to preserve every detected scene-change frame without limitation. This maximizes visual context but significantly increases token consumption and processing time.

Can I use transcript mode and still extract frames?

No. The transcript detail mode explicitly sets the frame cap to None in skills/watch/scripts/config.py, which instructs the processor to skip frame extraction entirely. Only the generated text transcript is returned, with no visual analysis performed.

Which file contains the default frame cap constants?

The default mappings reside in skills/watch/scripts/config.py inside the frame_cap function (approximately lines 65–72). This function is imported and invoked by skills/watch/scripts/watch.py during the video processing pipeline to determine how many frames to extract.

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