# How to Use `--resolution` in Claude Video to Increase Frame Width for Text Capture

> Learn how to use Claude Video's --resolution flag to increase frame width beyond 512px. Capture clearer images for improved OCR accuracy and on-screen text readability.

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

---

**The `--resolution` flag controls the maximum frame width during video extraction, allowing you to override the default 512px limit to capture higher-resolution images that improve OCR accuracy and on-screen text readability.**

The `bradautomates/claude-video` repository provides powerful video processing capabilities for Claude AI workflows. When extracting frames for text recognition or visual analysis, the default resolution may not provide sufficient clarity for small on-screen text. Understanding how to leverage the `--resolution` flag allows you to optimize frame width for your specific text capture needs.

## Understanding the `--resolution` Mechanism

The `--resolution` parameter controls the **maximum width** of extracted frames while preserving the original aspect ratio. According to the source code in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the script builds an FFmpeg scale filter through the `_scale_filter` function (lines 42-46), which constrains output width to the smaller of your requested resolution or the source video's native width.

### Default Resolution Behavior

By default, the resolution is set to **512 pixels** (line 99 in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)). This default works well for thumbnail generation and general scene understanding, but often lacks the pixel density required for accurate optical character recognition (OCR) of small text, code snippets, or detailed UI elements.

### The `_scale_filter` Implementation

When processing videos, the `_scale_filter` function dynamically constructs the FFmpeg scale filter string. It accepts your specified resolution value and ensures the output frames never exceed that width while maintaining proper aspect ratios. This function is called during the extraction process (lines 94-95) after the argument parser stores your `--resolution` value in the `resolution` variable (lines 104-110).

## How to Increase Frame Width for Text Capture

Raising the resolution value creates wider frames that preserve more detail for downstream text reading tasks.

1. **Select an appropriate width** – Common values include `1024`, `1280`, or the full native width of your source video.
2. **Pass the flag via CLI** or the `/watch` command to trigger higher resolution extraction.
3. **Verify output quality** – Check that text characters are clearly legible in the extracted JPEG frames.

## Practical Implementation Examples

### Command Line Interface

When running the frame extraction script directly, append the `--resolution` flag with your desired pixel width:

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

```

### Claude Slash Command

If using the Claude Video integration through the `/watch` slash command documented in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), pass the same arguments:

```text
/watch path/to/video.mp4 --resolution 1024 --max-frames 150

```

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) entry point forwards these arguments to the underlying extraction functions.

### Python API Integration

For programmatic access, import the extraction functions and specify the resolution parameter:

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

meta = get_metadata("video.mp4")
fps, _ = auto_fps(meta["duration_seconds"])

frames = extract(
    video_path="video.mp4",
    out_dir=Path("out/frames"),
    fps=fps,
    resolution=1024,  # Increase frame width here

    max_frames=150,
)

```

## Performance and Storage Considerations

Increasing frame width generates **larger JPEG files** that consume more disk space per frame. Higher resolutions also require slightly more processing time during FFmpeg encoding. However, the trade-off is justified when your workflow depends on accurate text extraction from dense on-screen content, programming tutorials, or documentation videos.

## Summary

- The `--resolution` flag in `bradautomates/claude-video` controls maximum frame width via the `_scale_filter` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).
- Default resolution is **512px**, suitable for thumbnails but often insufficient for text OCR.
- Increase values to `1024`, `1280`, or higher to improve text legibility in extracted frames.
- Use via CLI (`--resolution 1024`), `/watch` commands, or the Python `extract()` function.
- Higher resolutions increase file size and processing time but significantly improve text capture accuracy.

## Frequently Asked Questions

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

The default resolution is **512 pixels** as defined in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) at line 99. This value provides a balance between file size and visual information for general scene understanding tasks.

### How high can I set the resolution value?

You can specify any positive integer up to the native width of your source video. The `_scale_filter` function automatically uses the smaller of your requested value or the video's actual dimensions, preventing upscaling artifacts while allowing you to match the source quality exactly.

### Does increasing resolution affect processing speed?

Yes. Higher resolution frames require more computational resources during FFmpeg encoding and result in larger file sizes that take longer to write to disk. However, the impact is typically minimal unless processing hundreds of frames at 4K resolutions.

### Can I use `--resolution` with any video format?

Yes. The `--resolution` flag works with any video format supported by FFmpeg, including MP4, AVI, MOV, and MKV files. The scaling filter applies uniformly during the frame extraction process regardless of the input codec.