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

> Discover claude-video's maximum resolution clamping behavior. Learn how it ensures Claude Read compatibility by limiting frame height to 1998 pixels with configurable width.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-05

---

**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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py):

```python
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This function constructs an ffmpeg scaling filter that simultaneously respects user preferences and Claude Read's limitations:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 308-311), the output displays:

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

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

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

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.