# How to Configure Custom Frame Resolution with `--resolution` in Claude-Video

> Configure custom frame resolution with --resolution in Claude-Video. Extract higher-detail JPEG frames from videos while preserving aspect ratio. Learn how to override default settings for enhanced clarity.

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

---

**Use the `--resolution` flag in Claude-Video’s `/watch` skill to override the default 512-pixel frame width, allowing you to extract higher-detail JPEG frames from videos while preserving aspect ratio.**

Claude-Video’s **watch** skill extracts JPEG frames from video sources using `ffmpeg` for analysis by Claude. By default, frames are scaled to 512 pixels wide (with height auto-scaled to a maximum of 1998 pixels) to balance visual detail against token consumption. When you configure custom frame resolution with `--resolution`, you override this default to capture finer visual details such as on-screen text, code snippets, or presentation slides.

## How the `--resolution` Flag Works

The resolution parameter flows through three core components before reaching the `ffmpeg` execution layer.

In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the CLI argument parser captures the `--resolution` value and stores it in the `Config.resolution` attribute. This value is then forwarded through [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (the main orchestration module) to the `frames.extract_frames()` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

Inside [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), the resolution value is injected into an `ffmpeg` filter string using the `scale` video filter:

```bash
ffmpeg -i INPUT -vf "scale=W:-2" -qscale:v 2 FRAME_%05d.jpg

```

Here, `W` represents the integer value passed to `--resolution` (e.g., `1024`), while `-2` instructs `ffmpeg` to automatically calculate the height that preserves the original aspect ratio. The generated frames are subsequently listed with timestamps (e.g., `t=00:01:23`) and fed to Claude via the `Read` tool.

## Using the `--resolution` Flag

### Basic Usage with Default Resolution

If you omit the flag, the system defaults to 512 pixels wide:

```bash
/watch https://youtu.be/dQw4w9WgXcQ "What does the presenter say at 45 seconds?"

```

### Increasing Resolution for Text-Heavy Content

For videos containing small fonts, code, or detailed slides, increase the width to 1024 pixels or higher:

```bash
/watch https://youtu.be/dQw4w9WgXcQ "Summarize the slide content" --resolution 1024

```

### Combining with Other Options

The `--resolution` flag integrates seamlessly with time range and frame rate controls:

```bash
/watch video.mp4 \
  --start 1:15 --end 1:45 \
  --detail balanced \
  --resolution 1024 \
  --fps 3

```

### Python API Usage

Developers can invoke the resolution setting programmatically via the `run_watch` function:

```python
from skills.watch.scripts.watch import run_watch

run_watch(
    source="https://youtu.be/dQw4w9WgXcQ",
    query="Explain the key point at 30 seconds",
    resolution=1024,          # Custom width override

    detail="balanced",
)

```

## Technical Implementation Details

The skill contract in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) declares the `--resolution` option, ensuring compatibility across Claude Code, Codex, and other hosts. The actual implementation spans three critical source files:

- **[`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)**: Parses CLI arguments and validates the resolution value, making it available as `Config.resolution` throughout the pipeline.
- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: Acts as the entry point and coordinator, passing the resolution parameter to the frame extraction layer.
- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)**: Constructs the final `ffmpeg` command, applying the `scale=W:-2` filter where `W` equals the configured resolution.

## Performance and Token Cost Considerations

Each pixel in a JPEG frame consumes approximately 4 image tokens when processed by Claude. While higher resolutions improve OCR accuracy and detail recognition, they proportionally increase your token budget usage.

The default 512-pixel width optimizes for general video comprehension while staying within typical context window limits. Reserve resolutions above 1024 pixels for scenarios requiring precise text extraction or analysis of dense visual information, as documented in the repository’s README token-cost table.

## Summary

- The `--resolution` flag overrides the default 512-pixel frame width in Claude-Video’s `/watch` skill.
- Resolution values flow from [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) through [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) to [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), where they generate an `ffmpeg` `scale=W:-2` filter.
- Higher resolutions preserve aspect ratio automatically but increase image token consumption by roughly 4 tokens per pixel.
- Use resolutions above 1024 pixels specifically for text-heavy content, code demonstrations, or detailed slides.

## Frequently Asked Questions

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

If you omit the flag, Claude-Video defaults to 512 pixels wide, automatically calculating the height to preserve the video’s original aspect ratio while capping the maximum height at 1998 pixels. This default balances sufficient visual detail with reasonable token consumption.

### How does the `--resolution` flag affect the ffmpeg command?

The flag modifies the video filter chain in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), specifically inserting your custom width into the `scale=W:-2` parameter. The `-2` value ensures `ffmpeg` computes a height that maintains the aspect ratio using even numbers, which is required for JPEG compatibility.

### Will increasing the resolution help Claude read small text in videos?

Yes. Increasing the resolution to 1024 or higher significantly improves Claude’s ability to recognize small fonts, code syntax, and presentation slides. However, each resolution doubling quadruples the pixel count (and thus token cost), so use higher resolutions selectively for text-critical segments rather than entire videos.

### Can I use the `--resolution` flag with local video files as well as URLs?

Absolutely. The `--resolution` flag works identically for both local file paths and remote URLs, as the frame extraction pipeline in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) processes both input types through the same `ffmpeg` scaling logic after the source is validated.