Understanding the Max 1998px Height Clamping Logic for Claude Read Compatibility in claude-video

The max 1998px height clamping logic ensures extracted video frames fit within Claude Read's internal image size limits, preventing rejection or costly down-scaling while optimizing token usage.

The bradautomates/claude-video repository implements a strict height limitation when extracting video frames to ensure seamless compatibility with Claude Read capabilities. This max 1998px height clamping logic for Claude Read compatibility acts as a protective boundary that prevents image processing failures and unexpected token cost inflation when the AI model ingests JPEG frames.

Why Claude Read Requires Height Constraints

Claude Read imposes an internal limitation on the maximum image height it can process—approximately 2000 pixels. When images exceed this threshold, the system either rejects them outright or forcefully down-scales them to comply with platform constraints.

Forced down-scaling introduces two significant penalties. First, it increases token usage because Claude tokenizes images based on their width multiplied by height dimensions. Second, it slows down model processing time due to the additional computational overhead required to handle oversized inputs. By proactively clamping frame heights to 1998 pixels, the claude-video skill preempts these issues before the images ever reach the API.

How the 1998px Limit Is Enforced in Code

The frame extraction logic resides in skills/watch/scripts/frames.py, where the height constraint is implemented as a hardcoded constant and applied through FFmpeg scaling filters.

The MAX_READ_DIMENSION Constant

At line 30 of skills/watch/scripts/frames.py, the code defines the ceiling value:

MAX_READ_DIMENSION = 1998

This constant establishes the absolute maximum height allowed for any extracted frame, sitting just below Claude Read's documented ~2000px upper boundary to ensure a safety margin.

FFmpeg Scaling Filter Implementation

The _scale_filter function (lines 44-46) incorporates this constant into the FFmpeg video filter graph:

def _scale_filter(resolution: int) -> str:
    # Width is limited to the requested resolution (default 512 px)

    # Height is limited to 1998 px to stay within Claude Read limits

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

When the main extraction script executes FFmpeg, it injects this filter to constrain dimensions during frame generation:

ffmpeg -i input.mp4 \
  -vf "fps=2.0,scale=w='min(512,iw)':h='min(1998,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2" \
  -q:v 4 frame_%04d.jpg

This command ensures the output width respects the user-specified resolution (defaulting to 512px) while the height never exceeds 1998px, maintaining aspect ratio integrity through force_original_aspect_ratio=decrease.

Benefits of the Max 1998px Height Clamping Logic for Claude Read Compatibility

The max 1998px height clamping logic for Claude Read compatibility delivers three critical advantages when processing video content:

• Guaranteed API Compatibility: Every generated JPEG conforms to Claude Read's image size specifications, eliminating rejection errors due to oversized inputs.
• Predictable Token Costs: By preventing accidental image dimension inflation, the clamp ensures tokenization calculations remain stable and avoid the cost penalties associated with high-resolution down-scaling.
• Aspect Ratio Preservation: The FFmpeg filter parameters maintain the original video proportions while enforcing the height ceiling, preventing distortion that would compromise frame readability.

Documentation and CLI References

The height limitation is explicitly documented across multiple project files to ensure users understand the constraint. The README.md at line 47 states: "JPEGs are 512 px wide by default and clamped to 1998 px tall for Claude Read compatibility."

Similarly, skills/watch/SKILL.md at line 205 confirms: "Extracted images are clamped to a maximum 1998 px height for Claude Read compatibility."

When running the watch script from skills/watch/scripts/watch.py, the CLI also displays the constraint to users: print(f"- **Frame size:** max {args.resolution}px wide, max 1998px tall"), reinforcing the limitation before processing begins.

Summary

• The max 1998px height clamping logic prevents Claude Read from rejecting or down-scaling oversized video frames extracted as JPEG images.
• The constant MAX_READ_DIMENSION = 1998 is defined in skills/watch/scripts/frames.py line 30 and applied via FFmpeg scaling filters at lines 44-46.
• This protective measure optimizes token usage by preventing the computational penalties associated with images exceeding approximately 2000 pixels in height.
• The constraint is documented in README.md, SKILL.md, and the CLI output of watch.py to ensure transparency for end users.

Frequently Asked Questions

What happens if video frames exceed Claude Read's height limit?

Claude Read either rejects images taller than approximately 2000 pixels or automatically down-scales them to fit within platform constraints. This forced down-scaling increases token consumption and processing latency, which the 1998px clamp specifically prevents by preprocessing frames to compliant dimensions before API submission.

Why was 1998px chosen instead of exactly 2000px?

The 1998px value provides a safety margin below Claude Read's approximate 2000px limit, accounting for potential rounding variations or minor implementation differences in the Claude vision pipeline. This buffer ensures that even edge-case frame extractions remain comfortably within acceptable bounds without risking rejection at the boundary threshold.

Does the height clamping affect the video width extraction?

No, width and height are controlled independently. While the height is hard-capped at 1998px via MAX_READ_DIMENSION, the width scales according to the user-specified resolution parameter (defaulting to 512px) through the min({resolution},iw) logic in the FFmpeg filter. The aspect ratio is preserved using force_original_aspect_ratio=decrease, ensuring frames resize proportionally within both constraints.

Where can I modify the maximum height limit if Claude's constraints change?

The height limit is defined as the MAX_READ_DIMENSION constant at line 30 of skills/watch/scripts/frames.py. To adjust the clamping value, modify this constant and update the corresponding documentation strings in skills/watch/scripts/watch.py, README.md, and skills/watch/SKILL.md to reflect the new Claude Read compatibility threshold.

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