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

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, 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). 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:

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, pass the same arguments:

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

The 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:

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.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}