# Maximum Read Dimension Limit (1998px) in Claude Video: Implementation and Rationale

> Discover the 1998px maximum read dimension limit in claude-video. Learn why this constraint prevents processing failures and controls image token costs for Claude's multimodal Read tool.

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

---

**The 1998px maximum read dimension limit is hardcoded in the `claude-video` repository to ensure every extracted video frame stays within Claude's multimodal Read tool constraints, preventing processing failures and keeping image token costs predictable.**

The `claude-video` repository provides video processing capabilities for Claude AI interactions. Within its frame extraction pipeline, a strict **maximum read dimension limit of 1998px** governs how video frames are scaled before ingestion. This constraint, defined in the watch skill's frame processing module, directly impacts how video content is prepared for Claude's vision capabilities.

## Where the 1998px Limit Is Defined

The height cap is implemented as a module-level constant in the frame extraction script.

### The MAX_READ_DIMENSION Constant

In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) at lines 30-32, the repository defines:

```python
MAX_READ_DIMENSION = 1998

```

This constant represents the maximum allowable height in pixels for any frame extracted from video content. The value is deliberately set two pixels below 2000 to ensure compatibility with Claude's image processing pipeline while providing a small safety margin.

## How the Limit Is Enforced

The constraint is applied through FFmpeg scaling filters during the frame extraction process.

### The _scale_filter Function

The private helper `_scale_filter()` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) constructs an FFmpeg filter string that incorporates the 1998px ceiling:

```python
def _scale_filter(resolution: int) -> str:
    return (
        f"scale=w='min({resolution},iw)':h='min({MAX_READ_DIMENSION},ih)':"
        "force_original_aspect_ratio=decrease:force_divisible_by=2"
    )

```

This filter string performs three critical operations:

- **Width control**: Uses `min({resolution},iw)` to respect the user-specified width (default 512px, optional 1024px) without upscaling beyond the source
- **Height enforcement**: Applies `min({MAX_READ_DIMENSION},ih)` to cap height at 1998px regardless of source resolution
- **Aspect ratio preservation**: `force_original_aspect_ratio=decrease` ensures the frame scales down uniformly without distortion
- **Codec compatibility**: `force_divisible_by=2` guarantees dimensions meet JPEG and H.264 encoding requirements

## Why the 1998px Cap Exists

The dimension limit exists to maintain compatibility with Claude's multimodal capabilities and manage computational costs.

### Claude Read Tool Compatibility

According to the skill contract documented in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) at lines 205-207, frames are "clamped to a maximum 1998px tall for Claude Read compatibility." Claude's vision model imposes strict pixel count limits on ingested images. Exceeding these limits triggers runtime errors or causes the Read tool to reject the image entirely.

### Token Cost Management

Image tokens in Claude's API are roughly proportional to pixel count. Uncapped high-resolution frames from 4K or 8K video sources would generate excessive token costs and latency. The 1998px height limit ensures predictable token usage regardless of source video resolution, protecting users from unexpected API charges.

### Runtime Safety

By enforcing the constraint at the FFmpeg level during extraction, the skill prevents pipeline failures that would occur if oversized images reached the Claude API. This fail-fast approach validates frame dimensions before API transmission.

## Working with the Dimension Limit

The 1998px cap operates automatically during frame extraction. You can verify its application through the following patterns.

### Extract Frames with Automatic Height Capping

When calling `extract()` from `skills.watch.scripts.frames`, the height limit applies automatically regardless of source video resolution:

```python
from pathlib import Path
from skills.watch.scripts.frames import extract

video_path = "sample.mp4"
out_dir = Path("frames")
fps = 1.0

frames = extract(
    video_path,
    out_dir,
    fps=fps,
    resolution=512,         # Target width; height capped at 1998px

    max_frames=100,
)

print(f"Extracted {len(frames)} frames, each ≤ 1998px tall")

```

### Inspect the Scaling Filter Directly

To verify the exact FFmpeg parameters that enforce the limit:

```python
from skills.watch.scripts.frames import _scale_filter, MAX_READ_DIMENSION

print(f"Max dimension constant: {MAX_READ_DIMENSION}")
print(f"Filter for 512px width: {_scale_filter(512)}")

# Output: scale=w='min(512,iw)':h='min(1998,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2

```

## Summary

- **Location**: The 1998px limit is defined as `MAX_READ_DIMENSION = 1998` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)
- **Enforcement**: The `_scale_filter()` function builds FFmpeg scaling commands that cap height while preserving aspect ratio using `force_original_aspect_ratio=decrease`
- **Purpose**: Ensures compatibility with Claude's multimodal Read tool and controls image token costs proportional to pixel count
- **Behavior**: Width remains configurable (512px or 1024px), but height never exceeds 1998px regardless of source video resolution

## Frequently Asked Questions

### Can I override the 1998px limit for higher resolution analysis?

No, the limit is hardcoded as a constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) because it reflects Claude Read tool's maximum supported image dimensions. Modifying this value would result in API errors when frames are submitted to Claude. The constraint protects your workflow from runtime failures.

### Does the 1998px limit apply to width or height?

The limit applies specifically to **height** as implemented in the `_scale_filter()` function. The width is controlled separately via the `resolution` parameter (defaulting to 512px), but the height cap of 1998px acts as a hard ceiling regardless of how tall the source video frames are.

### What happens if a video frame exceeds 1998px without this limit?

Without the scaling filter, Claude's Read tool would either reject the image outright with a dimension error or process it at significantly higher token costs. The FFmpeg pipeline would extract native-resolution frames from 4K or 8K sources, potentially generating images with 3000+ pixel heights that exceed Claude's multimodal input specifications.

### Is this limit specific to the claude-video repository or a general Claude constraint?

The limit is a **Claude platform constraint** that the `claude-video` repository respects. The 1998px value aligns with Claude's maximum image dimension requirements for the Read tool. The repository implements this check client-side to prevent failed API calls and provide clear documentation in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) about the preprocessing behavior.