Maximum Resolution Clamping Behavior in claude-video for Claude Read Compatibility

The claude-video tool clamps extracted video frames to a maximum height of 1998 pixels while allowing configurable width limits via the --resolution flag, ensuring all images render correctly in Claude Read.

The bradautomates/claude-video repository processes video content for AI analysis, but must respect Claude Read's hard limits on image dimensions. To maintain compatibility, the tool automatically scales down frames that exceed safe viewing thresholds while preserving aspect ratios.

How Resolution Clamping Works

When extracting frames from video files, claude-video applies a two-axis clamping strategy that protects against oversized images while giving users control over quality.

The 1998-Pixel Height Ceiling

Claude Read cannot render images taller than 1998 pixels. The codebase enforces this constraint through the MAX_READ_DIMENSION constant defined in skills/watch/scripts/frames.py:

MAX_READ_DIMENSION = 1998  # px

This value represents an absolute ceiling. Regardless of the source video's resolution or the user's width preferences, the extraction pipeline never produces frames exceeding 1998 pixels in height.

The Dynamic Width Limit

While height is fixed, width is configurable through the --resolution command-line argument (defaulting to 512 pixels). The actual width constraint uses the minimum of the requested resolution and the source video's intrinsic width, preventing upscaling artifacts.

Technical Implementation in frames.py

The clamping logic resides in the _scale_filter() function within skills/watch/scripts/frames.py. This function constructs an ffmpeg scaling filter that simultaneously respects user preferences and Claude Read's limitations:

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

The filter string performs three critical operations:

• Width clamping: min({resolution},iw) ensures the output never exceeds the requested resolution or the original video width
• Height clamping: min({MAX_READ_DIMENSION},ih) caps height at 1998 pixels regardless of source material
• Divisibility constraint: force_divisible_by=2 guarantees dimensions satisfy ffmpeg codec requirements for many video formats

When the watch script executes, it reports the effective limits to the user. In skills/watch/scripts/watch.py (lines 308-311), the output displays:

print(f"- **Frame size:** max {resolution}px wide, max {MAX_READ_DIMENSION}px tall")

Practical Usage Examples

Default Behavior (512px Width)

Running the watch skill without custom resolution parameters applies the 512-pixel default width while maintaining the 1998-pixel height ceiling:

python -m skills.watch.scripts.watch https://youtu.be/example

The tool outputs:

- **Frame size:** max 512px wide, max 1998px tall

Custom Width Configuration

Increase the width limit to 1024 pixels (or any value up to the source width) while the height remains clamped:

python -m skills.watch.scripts.watch https://youtu.be/example --resolution 1024

This generates:

- **Frame size:** max 1024px wide, max 1998px tall

Programmatic Filter Generation

Import the scaling logic directly for custom processing pipelines:

from skills.watch.scripts.frames import _scale_filter

resolution = 1200
ffmpeg_filter = _scale_filter(resolution)
print(ffmpeg_filter)

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

Claude Skill Invocation

When using the /watch skill inside Claude Code, the same constraints apply:

/watch https://youtu.be/example --resolution 800

The skill extracts frames no wider than 800 pixels and no taller than 1998 pixels, ensuring every image loads successfully in the Claude Read interface.

Summary

• Height is hard-limited to 1998 pixels via MAX_READ_DIMENSION in skills/watch/scripts/frames.py to ensure Claude Read compatibility
• Width is user-configurable through the --resolution flag (default 512px) but never exceeds the source video's intrinsic width
• Aspect ratio preservation is enforced through ffmpeg's force_original_aspect_ratio=decrease parameter
• Codec compatibility is maintained by forcing output dimensions to be divisible by 2
• Runtime transparency occurs through status messages in skills/watch/scripts/watch.py that confirm the active constraints

Frequently Asked Questions

Why is the height limit exactly 1998 pixels?

The 1998-pixel value represents Claude Read's maximum supported image height. According to the bradautomates/claude-video source code, images exceeding this dimension fail to render in the Claude Read interface, so the tool proactively scales down taller content to ensure accessibility.

Can I increase the width beyond 512 pixels?

Yes. The --resolution flag accepts any positive integer up to the source video's width. The width limit is soft-capped by the original video dimensions (iw in ffmpeg terminology), preventing artificial upscaling that would reduce quality.

What happens if my video is taller than 1998 pixels?

The _scale_filter() function automatically scales the video down proportionally until the height reaches 1998 pixels or less. The force_original_aspect_ratio=decrease parameter ensures the scaling maintains the original proportions, so width decreases proportionally to accommodate the height constraint.

Why does the filter force dimensions to be divisible by 2?

The force_divisible_by=2 requirement satisfies ffmpeg's internal constraints for many video codecs, particularly those using chroma subsampling (such as YUV420p). This prevents encoding errors and ensures the extracted frames remain compatible with standard image processing pipelines.

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