# How to Control Frame Resolution Using the `--resolution` Flag in Claude-Video

> Control frame resolution in Claude-Video with the --resolution flag. Balance visual detail and API token usage for efficient video analysis directly from the command line.

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

---

**Use the `--resolution` command-line flag in Claude-Video to set the output frame width in pixels, directly balancing visual detail against Anthropic API token consumption.**

Claude-Video is an open-source video processing tool designed for frame extraction and analysis with Claude. You can control the output quality and token costs using the `--resolution` flag, which adjusts the frame width before images are sent to the API.

## Where the `--resolution` Flag is Defined

The argument is defined in the main entry point at [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 30-33). The parser accepts an integer value representing the desired width in pixels, defaulting to **512**:

```python
parser.add_argument(
    '--resolution',
    type=int,
    default=512,
    help='Width of extracted frames in pixels'
)

```

## How Resolution Propagates to Frame Extraction

When you execute the `watch` command, the resolution value flows through the codebase in three stages:

1. **Capture**: [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) reads the value from `args.resolution`
2. **Propagation**: The value passes to frame extraction helpers including `extract_at_timestamps` and `extract`
3. **Execution**: These helpers invoke the FFmpeg command in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 98-104), where the `resolution` parameter constrains the output width while maintaining the video's aspect ratio

## Understanding Token Cost Implications

The `--resolution` setting directly impacts your Anthropic API token usage. The cost calculation follows the formula: **(width × height) / 750**.

- **Default (512px)**: Produces frames approximately 512 × 288 pixels, costing roughly **197 tokens per frame**
- **High (1024px)**: Doubles the width and roughly **quadruples the token cost** per frame due to the area increase
- **Low (256px)**: Reduces token consumption significantly for faster, cheaper processing

## Practical Usage Examples

Use the default 512px for most video analysis tasks:

```bash
watch https://example.com/video.mp4

```

Increase to 1024px when you need to read on-screen text or small details:

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

```

Reduce to 256px to minimize token usage for high-framerate extraction:

```bash
watch https://example.com/video.mp4 --resolution 256

```

### Direct Module Invocation

You can also invoke the frames module directly with the same flag:

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

```

## Summary

- The `--resolution` flag in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) defaults to **512 pixels** and accepts any positive integer
- The value propagates through `extract_at_timestamps` and `extract` helpers to the FFmpeg command in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)
- Token costs scale quadratically with resolution following the **(width × height) / 750** formula
- Use **1024px** for detailed text, **512px** for general analysis, and **256px** for token-sensitive workflows

## Frequently Asked Questions

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

The default resolution is **512 pixels** width, which produces frames approximately 512 × 288 pixels and costs roughly 197 tokens per frame according to the Anthropic pricing formula documented in the repository's README.

### How does changing the resolution affect API costs?

Token costs scale with pixel area following the formula (width × height) / 750. Doubling the resolution from 512px to 1024px quadruples the token cost per frame, not doubles it, because both width and height increase proportionally while maintaining aspect ratio.

### Can I use the --resolution flag when calling frames.py directly?

Yes. When invoking the frame extraction module directly with `python -m skills.watch.scripts.frames`, you can pass `--resolution` followed by the desired width in pixels, along with other parameters like `--fps` and `--timestamps`.

### Where is the --resolution flag defined in the source code?

The flag is defined in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 30-33) as an integer argument with a 512px default, and it is consumed in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 98-104) to configure the FFmpeg output width via the `scale` filter.