# How to Customize the Frame Resolution for Video Analysis in Claude-Video

> Customize frame resolution for video analysis in Claude-Video using --resolution CLI flag or Python. Set max width, preserve aspect ratio, and cap height for optimal results.

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

---

**You can customize the frame resolution in Claude-Video by using the `--resolution` CLI flag (default 512px) or the `resolution` parameter in Python functions, which sets the maximum width for extracted JPEG frames while automatically preserving aspect ratio and capping height at 1998px.**

The bradautomates/claude-video repository provides a `watch` entry point for video analysis that extracts frames as JPEG images. When you customize the frame resolution, you control the maximum width of these extracted frames, allowing you to balance image detail against processing speed and storage requirements according to the source code implementation.

## Understanding the Resolution Control Mechanism

Claude-Video implements frame resolution customization through two core components: the CLI argument parser and an FFmpeg scaling filter.

### CLI Argument Parsing in watch.py

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the `watch` entry point defines the `--resolution` argument using `argparse`:

```python
ap.add_argument("--resolution", type=int, default=512, help="Frame width in pixels (default 512)")

```

This stores the user-provided integer in `args.resolution`, which defaults to **512 pixels** if not specified.

### FFmpeg Scaling Filter in frames.py

The actual scaling logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) within the `_scale_filter` function:

```python
def _scale_filter(resolution: int) -> str:
    return f"scale=w='min({resolution},iw)':h='min({MAX_READ_DIMENSION},ih)'"

```

Here, `MAX_READ_DIMENSION` is hardcoded to **1998**, ensuring the height never exceeds this limit regardless of the width setting.

## Methods to Customize Frame Resolution

You can adjust the frame resolution through three approaches depending on your integration needs.

### Using the Command-Line Interface

The simplest method is passing the `--resolution` flag when invoking the `watch` command:

```bash

# Default 512px width

watch https://youtu.be/example_video

# Custom 1024px width

watch https://youtu.be/example_video --resolution 1024

```

The tool outputs a confirmation showing the applied limits:

```

- **Frame size:** max 1024px wide, max 1998px tall

```

### Using the Python API Directly

For programmatic access, import the extraction functions from `skills/watch.scripts.frames`:

```python
from pathlib import Path
from skills.watch.scripts.frames import extract

video_path = "path/to/video.mp4"
out_dir = Path("frames_out")

frames = extract(
    video_path,
    out_dir,
    fps=1.0,
    resolution=800,  # Custom width of 800px

    max_frames=50,
)

```

All extraction functions—including `extract_keyframes`, `extract_at_timestamps`, and `extract_scene_or_uniform`—accept the `resolution` parameter and forward it to `_scale_filter`.

### Modifying the Default Globally

To change the default resolution across all invocations, edit the argument definition in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py):

```python

# Change default from 512 to 1024

ap.add_argument("--resolution", type=int, default=1024,
                help="Frame width in pixels (default 1024)")

```

After modification, running `watch` without the `--resolution` flag uses your new default.

## Technical Implementation Details

The resolution value propagates through every frame extraction pathway in Claude-Video. When you call `extract`, `extract_keyframes`, or any other extraction routine, the resolution parameter builds an FFmpeg command that applies the scaling filter before writing JPEG files.

The `_scale_filter` constructs a filter string using `min({resolution},iw)`, which ensures the output width never exceeds your specified resolution or the source width, whichever is smaller. This preprocessing occurs during extraction, eliminating the need for post-processing.

## Summary

- **Primary control**: Use `--resolution` CLI flag or `resolution` parameter in Python functions
- **Default value**: 512 pixels maximum width
- **Height limit**: Hardcoded to 1998 pixels via `MAX_READ_DIMENSION` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)
- **Implementation**: FFmpeg `scale` filter applied during frame extraction in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)
- **Scope**: Affects all extraction methods including keyframes, scene-aware, and uniform sampling

## Frequently Asked Questions

### What is the default frame resolution in Claude-Video?

The default frame resolution is **512 pixels** width, as defined in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). If you do not specify the `--resolution` flag or `resolution` parameter, extracted JPEG frames will be scaled to a maximum width of 512 pixels while preserving aspect ratio.

### Why is there a maximum height limit of 1998 pixels?

The `MAX_READ_DIMENSION = 1998` constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) serves as a safeguard to prevent excessive memory usage and ensure compatibility with downstream analysis components. This limit applies regardless of the width you specify via `--resolution`.

### Can I set a specific height instead of width?

No, the current implementation only supports setting the maximum width via the `--resolution` parameter. The height is automatically calculated to preserve the original aspect ratio, capped at 1998 pixels. To customize height behavior, you would need to modify the `_scale_filter` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

### Does changing resolution affect video processing speed?

Yes, higher resolutions generally increase processing time and storage requirements because FFmpeg must handle larger pixel data, and subsequent analysis processes larger JPEG files. Conversely, reducing the resolution below the default 512px can improve performance when high detail is unnecessary.