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

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 (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 implements this constraint through a combination of a dedicated constant and FFmpeg scaling filters.

Constant Definition: At line 30 of frames.py, the height limit is explicitly defined:

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:

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:

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:

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:

>>> 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 (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 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. 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.

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