How Frame Resolution Affects Token Usage in Claude: A Technical Guide

Claude calculates image tokens using the formula (width × height) ÷ 750, meaning that doubling the frame resolution quadruples the token count per frame and can rapidly exhaust the model's context window.

Frame resolution directly determines token consumption when Claude processes video content through the bradautomates/claude-video repository. The watch skill extracts frames from videos and scales them according to user-specified dimensions before sending them to Claude's API. Understanding how frame resolution affects token usage in Claude is essential for balancing visual fidelity against the model's strict context limits.

The Anthropic Image Token Formula

Claude applies a deterministic pixel-area formula to every image it processes. According to the repository's README.md at line 91, the calculation is:

image tokens = (width × height) ÷ 750

With the default configuration of 512 px width and an auto-scaled height of approximately 288 px (maintaining aspect ratio for 720p-style content), each frame consumes roughly 197 tokens. This baseline establishes the minimum cost for video analysis.

The Quadratic Cost of Higher Resolution

Increasing frame resolution does not yield a linear increase in token usage—it scales quadratically with pixel area. As documented in skills/watch/SKILL.md (lines 242-245), doubling the width from 512 px to 1024 px increases the token count to approximately 800 tokens per frame, effectively quadrupling the cost.

For a typical 80-frame video, the difference is substantial:

• At 512 px: 50,000–80,000 image tokens
• At 1024 px: 200,000+ image tokens

This exponential growth can rapidly consume Claude's available context window, leaving insufficient room for the model's response or conversation history.

Technical Implementation in claude-video

Parsing the Resolution Flag

The CLI entry point in skills/watch/scripts/watch.py (line 32) defines the --resolution argument with a default value of 512:

ap.add_argument("--resolution", type=int, default=512,
                help="Frame width in pixels (default 512)")

FFmpeg Scaling Logic

The actual resizing occurs in skills/watch/scripts/frames.py within the _scale_filter function (lines 42-44). This function constructs an FFmpeg filter that clamps the width to the requested resolution while capping the height at 1998 px:

def _scale_filter(resolution: int) -> str:
    # Clamp width to the requested resolution and height to a safe maximum.

    return f"scale=w='min({resolution},iw)':h='min({MAX_READ_DIMENSION},ih)':"

The resulting dimensions from this filter determine the final token count when Claude applies its (w × h)/750 formula.

Token Budget Protection

To prevent accidental context exhaustion, watch.py includes a warning mechanism at line 323 that alerts users when a large token burn is imminent based on the combination of frame count and selected resolution.

Practical Usage Examples

Basic invocation with default resolution (≈197 tokens/frame):

/watch https://youtu.be/abc123 "Summarize the key points"

High-resolution mode for fine-grained text (≈4× tokens/frame):

/watch https://youtu.be/abc123 --resolution 1024 "Explain the code shown on the screen"

Programmatic integration showing how the resolution parameter flows through the system:

# In watch.py (excerpt)

args = ap.parse_args()

# Later, when calling the frames extractor:

subprocess.run([
    "python", str(FRAMES_SCRIPT),
    video_path,
    out_dir,
    "--resolution", str(args.resolution),
    "--fps", str(fps),
])

Summary

• Claude calculates image tokens using (width × height) ÷ 750, making token costs directly proportional to pixel area.
• The default 512 px width in claude-video yields approximately 197 tokens per frame.
• Doubling the resolution to 1024 px quadruples token usage to roughly 800 tokens per frame.
• The _scale_filter function in frames.py implements FFmpeg scaling to enforce requested dimensions while respecting maximum safe heights.
• Users should select the minimum resolution that captures necessary visual detail to preserve Claude's context window for analysis and response.

Frequently Asked Questions

How does Claude calculate tokens for video frames?

Claude applies the formula (width × height) ÷ 750 to each frame independently. For example, a 512 × 288 px frame generates approximately 197 tokens. This calculation occurs after the claude-video tool scales the frame via FFmpeg according to the --resolution parameter.

What is the default frame resolution in claude-video?

The default width is 512 px, with height auto-scaled to maintain aspect ratio (typically around 288 px). This default is defined in skills/watch/scripts/watch.py at line 32 and produces roughly 197 tokens per frame according to the repository's README.

Why does doubling the frame width quadruple token usage?

Because token count depends on total pixel area (width × height), not linear dimensions. When you double the width while maintaining aspect ratio, the height also doubles, resulting in four times the total pixels. As noted in skills/watch/SKILL.md, increasing width from 512 px to 1024 px raises token counts from approximately 197 to 800 per frame.

How can I avoid exceeding Claude's context window when processing videos?

Use the lowest resolution that still captures necessary detail—typically 512 px for general content, reserving 1024 px only for fine text or code. The watch skill at line 323 of watch.py warns when high-resolution frame combinations threaten to exhaust the token budget before processing begins.

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