# Why the Claude Video Tool Caps Maximum Resolution at 1998px Height for Claude Read Compatibility

> Discover why the Claude video tool limits resolution to 1998px height for Claude Read compatibility. Learn about critical visual input constraints.

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

---

**The maximum height is capped at 1998 pixels because Claude's Read tool cannot display images taller than 1998px**, and the video-watch skill automatically scales frames to ensure every extracted image remains compatible with the model's visual input constraints.

The `bradautomates/claude-video` repository provides a video-watching skill that extracts frames as JPEG images for Claude to analyze. To ensure seamless integration with Claude's image rendering capabilities, the tool enforces a strict height limit on all extracted frames. This safeguard prevents processing errors and guarantees that every generated frame can be successfully displayed within the chat interface.

## The Claude Read Constraint Behind the 1998px Limit

Claude's **Read** tool imposes a hard limit on image dimensions, rejecting or truncating any visual input exceeding 1998 pixels in height. Rather than risk failed frame processing or truncated visual data, the `claude-video` skill proactively clamps all output to this boundary. According to the source documentation in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (line 205), extracted images are deliberately clamped to ensure **Claude Read compatibility**.

## How the Frame Extraction Logic Enforces the Height Cap

The frame extraction module located at [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) implements this constraint through a combination of a dedicated constant and FFmpeg scaling filters.

**Constant Definition**: At line 30 of [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), the height limit is explicitly defined:

```python
MAX_READ_DIMENSION = 1998          # <-- height limit for Claude Read

```

**FFmpeg Scaling Filter**: Lines 42-46 construct a scaling filter that preserves aspect ratio while enforcing the maximum height:

```python
f"scale=w='min({resolution},iw)':h='min({MAX_READ_DIMENSION},ih)':"
"force_original_aspect_ratio=decrease:force_divisible_by=2"

```

This filter ensures that even if the source video contains ultra-high resolution frames, the output JPEGs never exceed 1998px tall.

## Code Examples: Working with the Resolution Cap

**Default Resolution Usage**: When running the watch script with default settings, the height limit is automatically applied:

```bash
watch.py --detail balanced https://example.com/video

```

The script executes three steps:

1. Computes the scaling filter using `MAX_READ_DIMENSION = 1998`
2. Runs FFmpeg with the constrained filter, producing JPEGs no taller than 1998px
3. Passes the valid image paths to Claude for display

**Custom Width with Height Protection**: You can increase the width without risking compatibility:

```bash
watch.py --detail balanced --resolution 1024 https://example.com/video

```

Even with the width set to 1024px, the height remains capped at 1998px because the scaling filter contains `h='min(1998,ih)'`.

**Inspecting the Limit Programmatically**:

```python
>>> from skills.watch.scripts.frames import MAX_READ_DIMENSION
>>> print(MAX_READ_DIMENSION)
1998

```

## Summary

- The **1998px height limit** is a hard constraint imposed by Claude Read, not an arbitrary design choice
- The **`MAX_READ_DIMENSION`** constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (line 30) defines this boundary
- **FFmpeg scaling filters** automatically preserve aspect ratio while enforcing the height cap through the `min(1998,ih)` parameter
- All extracted JPEGs are guaranteed compatible with Claude's image display capabilities, preventing processing failures

## Frequently Asked Questions

### What happens if a video frame exceeds 1998px height?

The FFmpeg scaling filter automatically downscales the frame to fit within 1998px while maintaining the original aspect ratio. Frames taller than the limit are resized using the `force_original_aspect_ratio=decrease` parameter, ensuring they never trigger Claude Read's rejection mechanism.

### Where is the 1998px height limit defined in the codebase?

The constant is defined in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) at line 30 as `MAX_READ_DIMENSION = 1998`. This value is imported and used throughout the frame extraction pipeline, including the scaling filter construction at lines 42-46.

### Does increasing the resolution width affect the height constraint?

No. The width parameter is configurable via the `--resolution` flag, but the height remains independently capped at 1998px. The scaling logic uses `h='min(1998,ih)'` regardless of the width setting, allowing higher horizontal resolution without breaking Claude Read compatibility.

### Is the 1998px limit configurable?

The current implementation hardcodes the value as `MAX_READ_DIMENSION = 1998` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py). While the width resolution is user-configurable, the height cap is fixed to ensure guaranteed compatibility with Claude Read's image rendering constraints as documented in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md).