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

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

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 (lines 30‑46):

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

The entry point surfaces the limits to users. In skills/watch/scripts/watch.py, the --resolution flag defaults to 512:

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):

- **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:

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

The resulting ffmpeg filter chain resembles:

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

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