# How Frame Resolution Scaling Works in Claude Video: The --resolution Parameter Explained

> Understand how Claude Video's --resolution parameter scales frame resolution. Learn how it preserves aspect ratio and avoids upscaling, keeping frames divisible by two.

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

---

**The `--resolution` parameter in Claude Video sets the maximum width of extracted frames while automatically preserving the aspect ratio and ensuring dimensions are divisible by two, preventing upscaling beyond the source resolution.**

The `bradautomates/claude-video` repository provides intelligent video analysis capabilities through frame extraction and processing. Understanding how **frame resolution scaling** works is essential for optimizing storage, processing speed, and API costs when working with video content. This guide examines the internal mechanics of the `--resolution` flag as implemented in the project's frame extraction pipeline.

## The Resolution Scaling Pipeline

In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the `--resolution` value flows through a dedicated helper function that constructs an ffmpeg video filter. The entry point in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) parses this CLI argument and passes it unchanged to the extraction functions, ensuring consistent behavior across all processing modes.

### The _scale_filter Function

The core logic resides in the `_scale_filter` helper function defined at line 42 of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This function generates an ffmpeg scale filter string that balances user requirements with technical constraints:

```

scale=w='min(<resolution>,iw)':h='min(1998,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2

```

This filter is injected into the `-vf` (video filter) chain for every extraction routine, including `extract`, `extract_scene_candidates`, `extract_keyframes`, and `extract_at_timestamps`.

## Resolution Constraints and Safeguards

The scaling implementation enforces three critical constraints to ensure compatibility and quality.

### Maximum Width Protection

The filter expression `w='min(<resolution>,iw)'` prevents **upscaling** by selecting the smaller value between the user-requested resolution and the input video's native width (`iw`). If you specify `--resolution 1024` on a 640×480 video, the output remains 640 pixels wide.

### Height Ceiling and Aspect Ratio

The height parameter `h='min(1998,ih)'` references a hard-coded maximum dimension constant (`MAX_READ_DIMENSION = 1998`) while preserving the original aspect ratio through the `force_original_aspect_ratio=decrease` flag. This ensures the frame never exceeds safe processing dimensions regardless of input size.

### Codec Compatibility

The `force_divisible_by=2` parameter guarantees both dimensions are even numbers, satisfying requirements for JPEG encoding and H.264/H.265 codecs that demand divisible-by-2 dimensions for macro block alignment.

## Practical Usage Examples

Apply the `--resolution` parameter through the main CLI interface or directly via the frames module.

### Standard CLI Usage

Extract frames with a maximum width of 720 pixels:

```bash
watch <video-url-or-path> --resolution 720

```

Request a specific 300-pixel width (will not upscale smaller sources):

```bash
watch <video-url-or-path> --resolution 300

```

### Direct Module Invocation

For scripting or advanced workflows, invoke the frames module directly:

```bash
python -m skills.watch.scripts.frames \
    path/to/video.mp4 out_dir \
    --resolution 1024

```

Both approaches generate an ffmpeg command incorporating the scale filter:

```bash
-vf "fps=2.0,scale=w='min(720,iw)':h='min(1998,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2"

```

## Summary

- The `--resolution` parameter controls maximum frame width while preserving aspect ratio through the `_scale_filter` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).
- The system prevents upscaling by comparing the requested resolution against the input width (`iw`) and caps height at 1998 pixels.
- All extraction methods—`extract`, `extract_scene_candidates`, `extract_keyframes`, and `extract_at_timestamps`—utilize identical scaling logic.
- Output dimensions are always forced to even numbers (`force_divisible_by=2`) to maintain codec compatibility.
- The default resolution value is 512 pixels when the parameter is omitted.

## Frequently Asked Questions

### What is the default resolution if I don't specify --resolution?

The CLI parser in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) defaults to **512 pixels** when the `--resolution` flag is omitted. This default applies uniformly across all frame extraction routines including uniform sampling and scene-based extraction.

### Does --resolution upscale videos to the specified width?

No. The filter expression `w='min(<resolution>,iw)'` explicitly prevents upscaling by selecting the smaller value between your requested resolution and the input video's native width. If the source video is 640 pixels wide and you request `--resolution 1920`, the output frames will remain 640 pixels wide.

### Why are frame dimensions forced to be divisible by 2?

The `force_divisible_by=2` parameter ensures compatibility with downstream codecs and image formats. Many video codecs (including H.264 and H.265) require even dimensions for macro block processing, and JPEG encoding performs optimally with divisible-by-2 dimensions. This constraint prevents encoding errors during frame extraction.

### Which extraction methods support the --resolution parameter?

All major extraction functions in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) support the parameter: `extract` (uniform sampling), `extract_scene_candidates` (scene change detection), `extract_keyframes` (keyframe extraction), and `extract_at_timestamps` (cue-based extraction). The `_scale_filter` helper ensures consistent resolution handling across every extraction mode.