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

> Discover default frame caps for Claude Video detail modes: efficient 50, balanced 250, token-burner unlimited, and transcript zero. Optimize your video processing costs.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: getting-started
- Published: 2026-07-13

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the `frame_cap` function implements this mapping logic:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).

Using the CLI:

```bash

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

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) during the video processing pipeline to determine how many frames to extract.