# How Claude‑Video's Resolution Scaling Works With the 1998px Maximum Dimension Limit

> Discover how Claude-video's resolution scaling works. Learn about the 1998px maximum dimension limit and how it preserves aspect ratio with configurable width.

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

---

**Claude‑video scales every extracted frame through a hard‑coded ffmpeg filter that caps height at 1998 px while letting users configure width via `--resolution`, preserving aspect ratio and enforcing even dimensions.**

The `bradautomates/claude‑video` repository processes video frames for vision‑model consumption. Its frame‑extraction pipeline in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) applies a consistent scaling policy across all output modes, ensuring no frame exceeds the 1998 px vertical limit regardless of source resolution.

---

## The `MAX_READ_DIMENSION` Ceiling

The scaling logic centers on a single 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                # hard‑coded height ceiling

```

This value is immutable and applies universally. The repository never exposes this limit as a user‑configurable parameter; it exists to protect downstream vision models from excessively tall inputs.

---

## The `_scale_filter()` Function

All frame scaling routes through `_scale_filter()` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 30‑46):

```python
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"
    )

```

The filter string encodes three constraints:
- **Width** – capped at the `resolution` parameter (CLI‑configurable, default 512)
- **Height** – capped at `MAX_READ_DIMENSION` (1998 px)
- **Aspect ratio** – preserved via `force_original_aspect_ratio=decrease`
- **Divisibility** – both dimensions forced even via `force_divisible_by=2` (required by many ffmpeg codecs)

---

## Where the Filter Is Applied

Every frame‑extraction function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) injects this filter into its ffmpeg command:

| Function | Usage | Source lines |
|----------|-------|--------------|
| `extract()` | Uniform frame sampling | `"-vf", f"fps={fps},{_scale_filter(resolution)}"`【/skills/watch/scripts/frames.py#L94-L95】 |
| `extract_keyframes()` | Key‑frame extraction | `"-vf", f"{_scale_filter(resolution)},showinfo"`【/skills/watch/scripts/frames.py#L14-L15】 |
| `extract_at_timestamps()` | Timestamp‑based extraction | `"-vf", _scale_filter(resolution)`【/skills/watch/scripts/frames.py#L70-L71】 |

This guarantees identical scaling behavior whether sampling evenly, grabbing I‑frames, or pulling specific timestamps.

---

## CLI Integration in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)

The entry point surfaces the limits to users. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the `--resolution` flag defaults to 512:

```python
parser.add_argument(
    "--resolution",
    type=int,
    default=512,
    help="Maximum width of extracted frames in pixels",
)

```

And the help output explicitly documents the dual constraint (line 309):

```text
- **Frame size:** max <resolution>px wide, max 1998px tall

```【/skills/watch/scripts/watch.py#L309-L310】

---

## Practical Examples

Default invocation (512 px width, 1998 px height ceiling):

```bash
watch https://example.com/video.mp4

```

Wider frames with same height limit:

```bash
watch https://example.com/video.mp4 --resolution 1024

```

The resulting ffmpeg filter chain resembles:

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

```

For a 4K vertical video (2160×3840), this yields frames scaled to ~1124×1998. For a 1920×1080 source at `--resolution 1024`, output is 1024×576 (both even, aspect ratio preserved).

---

## Summary

- **Height ceiling** – Hard‑coded to 1998 px via `MAX_READ_DIMENSION` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)
- **Width control** – User‑configurable via `--resolution` (default 512 px)
- **Aspect preservation** – `force_original_aspect_ratio=decrease` prevents distortion
- **Codec compatibility** – `force_divisible_by=2` ensures even dimensions
- **Universal application** – All three extraction modes use identical filtering

---

## Frequently Asked Questions

### What happens if my video is taller than 1998 pixels?

The `_scale_filter()` function shrinks the height to 1998 px and proportionally reduces width while respecting your `--resolution` limit. The aspect ratio is preserved via `force_original_aspect_ratio=decrease`.

### Can I increase the 1998px height limit?

No. `MAX_READ_DIMENSION` is a hard‑coded constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). It is not exposed as a CLI flag or configuration option.

### Why force dimensions to be divisible by 2?

Many ffmpeg codecs require even‑sided frames. The `force_divisible_by=2` parameter ensures output compatibility without manual rounding logic.

### Does `--resolution` ever override the height limit?

Never. The filter uses `min()` for both dimensions independently. A `--resolution 4096` request still yields frames no taller than 1998 px, as implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).