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

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 at lines 30-32, the repository defines:

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 constructs an FFmpeg filter string that incorporates the 1998px ceiling:

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

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:

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
• 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 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 about the preprocessing behavior.

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