# How to Customize Frame Resolution Using the `--resolution` Option in Claude Video

> Customize frame resolution in Claude Video using the --resolution option. Override default limits, pass values to FFmpeg, and maintain aspect ratio for precise video frame extraction.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-01

---

**Use the `--resolution` flag to override the default 512‑px width limit when extracting frames from videos in Claude Video, which passes the value directly to FFmpeg's scale filter while maintaining aspect ratio and capping height at 1998 px.**

Claude Video (`bradautomates/claude-video`) extracts JPEG frames from video files using FFmpeg. By default, frames are scaled so the width never exceeds 512 pixels, but you can customize this limit to balance image quality against token usage by using the `--resolution` command‑line option.

## How the `--resolution` Flag Works

When you invoke the `watch` command with `--resolution`, the value is parsed in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 30‑34) and forwarded through the call chain to every frame‑extraction function. These functions—all residing in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)—include `extract()`, `extract_keyframes()`, `extract_scene_or_uniform()`, and `extract_at_timestamps()`. Each function passes the resolution parameter to the internal helper `_scale_filter()`, which constructs an FFmpeg `scale=` filter string that limits the output width while respecting a hard‑coded height ceiling.

## Understanding the Scaling Logic

The actual scaling behavior is defined in the `_scale_filter()` helper inside [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 42‑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"
    )

```

In this filter:

- `w='min({resolution},iw)'` sets the output width to the smaller of your specified value or the input video’s original width.
- `h='min({MAX_READ_DIMENSION},ih)'` caps the height at **1998 px** (the `MAX_READ_DIMENSION` constant defined on line 30 of [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)).
- `force_original_aspect_ratio=decrease` ensures the frame scales proportionally.
- `force_divisible_by=2` guarantees even pixel dimensions for codec compatibility.

Thus, specifying `--resolution 720` produces frames up to 720 px wide (or narrower if the source is smaller) while keeping the height within the 1998 px limit.

## Usage Examples

### Basic Usage

Run the default 512‑px extraction:

```bash
watch https://youtu.be/example-video

```

### High‑Resolution Extraction

Increase the width limit to 720 px for finer detail:

```bash
watch https://youtu.be/example-video --resolution 720

```

### Direct Script Execution

For debugging or development, invoke the module directly:

```bash
python -m skills.watch.scripts.watch \
    https://youtu.be/example-video \
    --resolution 720 \
    --out-dir ./my-output

```

## Implementation Details in the Source Code

### Argument Parsing in watch.py

The CLI entry point in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) defines the optional argument on lines 30‑34 and forwards it to the extraction pipeline. Any integer value supplied here propagates unchanged to the underlying frame functions.

### Frame Scaling in frames.py

The [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) module implements the scaling constraint. In addition to `_scale_filter()`, it defines `MAX_READ_DIMENSION = 1998` to prevent excessively tall images. Every extraction variant—uniform sampling, keyframe extraction, scene‑aware selection, and timestamp‑based extraction through `extract()`, `extract_keyframes()`, `extract_scene_or_uniform()`, and `extract_at_timestamps()`—honors this resolution parameter, ensuring consistent output dimensions across all generated JPEGs.

## Summary

- The default frame width in Claude Video is **512 px**, controlled by the `resolution` parameter in `frames.extract()`.
- Override the default by passing `--resolution N` to the `watch` command.
- The scaling logic in `_scale_filter()` uses FFmpeg’s `scale` filter with `min()` constraints to respect both your width limit and the 1998‑px height ceiling.
- Aspect ratio is preserved via `force_original_aspect_ratio=decrease`, and dimensions are forced to even numbers for codec compatibility.
- All extraction modes (uniform, keyframes, scene‑aware, timestamps) respect the same resolution setting.

## Frequently Asked Questions

### What is the maximum resolution I can specify?

While you can pass any integer to `--resolution`, the implementation caps the height at **1998 px** via the `MAX_READ_DIMENSION` constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). The width will not exceed your specified value or the source video’s width, whichever is smaller.

### Does changing the resolution affect aspect ratio?

No. The `_scale_filter()` function includes `force_original_aspect_ratio=decrease`, which ensures frames scale proportionally. Your video’s original aspect ratio is preserved while fitting within the width and height constraints.

### Which extraction modes support custom resolution?

All modes support it. The `resolution` parameter is accepted by `extract()`, `extract_keyframes()`, `extract_scene_or_uniform()`, and `extract_at_timestamps()` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), and the [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) entry point passes the CLI value to each of these functions uniformly.

### Why is the default resolution set to 512 px?

The default value of 512 balances image clarity with token consumption and storage efficiency when processing video frames through LLM vision APIs. You can increase this value for higher fidelity or decrease it to reduce file size and processing time.