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

> Understand how frame resolution impacts Claude token usage. Learn the formula width x height / 750 and discover how higher resolutions rapidly consume context window tokens.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: technical-guide
- Published: 2026-08-07

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (line 32) defines the `--resolution` argument with a default value of 512:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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:

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

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

```

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

```bash
/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:

```python

# 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) warns when high-resolution frame combinations threaten to exhaust the token budget before processing begins.