Recommended Resolution for Reading On-Screen Text with Claude-Video

Use --resolution 1024 when analyzing videos containing slides, terminal output, or code snippets, while sticking to the default 512px width for general content to minimize token consumption.

Claude-video extracts frames from video files for AI vision analysis. When the content includes fine details like on-screen text, adjusting the frame resolution becomes critical for accuracy. Understanding the recommended resolution for reading on-screen text ensures you balance visual clarity with cost-effectiveness according to the bradautomates/claude-video source code.

How Resolution Impacts Image Tokens

Claude-video processes video frames as image tokens, where the frame width directly determines token consumption and text legibility. The source code documents two primary settings:

• Default width (512px) → frames render at 512 × 288 px, consuming approximately 197 image tokens per frame
• High width (1024px) → frames render at 1024 × 576 px, consuming roughly 4× more tokens per frame than the default

In skills/watch/scripts/frames.py, the extraction logic scales frames based on the --resolution parameter passed from the CLI. Higher resolutions preserve fine details necessary for optical character recognition, but each frame sends more data to Claude's vision model.

When to Use 1024px Resolution

According to skills/watch/SKILL.md at line 147, you should "bump to 1024 only if the user needs to read on-screen text." This recommendation targets specific content types where text legibility is paramount:

• Presentation slides with small fonts
• Terminal output and command-line interfaces
• Code editors and IDE screenshots
• Documentation screencasts with dense text

The same file cautions at line 245 that "Bumping --resolution to 1024 roughly quadruples the image tokens per frame. Only do it when necessary." The README.md at line 196 reiterates this guidance, specifying --resolution 1024 for cases "when Claude needs to read on-screen text (slides, terminals, code)."

CLI Implementation

The resolution flag is implemented in skills/watch/scripts/watch.py, which parses user input and forwards the width parameter to the frame extraction pipeline. When you specify --resolution 1024, the watch.py script invokes the extraction logic in skills/watch/scripts/frames.py to generate higher-fidelity frames before sending them to Claude's vision API.

Usage Examples

Default Resolution for General Video

Use the 512px default for interviews, animations, or content without readable text:

claude-video watch https://example.com/video.mp4

High Resolution for Text-Heavy Content

Switch to 1024px when processing presentations or tutorials with on-screen text:

# Use higher resolution so Claude can read the text on the slides

claude-video watch --resolution 1024 https://example.com/presentation.mp4

Custom Resolution Values

While 512 and 1024 are the documented standards, you can experiment with intermediate widths, keeping in mind that token costs scale with resolution:

# Custom width for specific use cases

claude-video watch --resolution 800 https://example.com/video.mp4

Summary

• Start with 512px (default) for most video analysis tasks to optimize token usage
• Switch to 1024px specifically when the video contains slides, terminal output, or code that Claude must read accurately
• Expect roughly 4× higher token consumption at 1024px compared to the default 512px
• Set the resolution using the --resolution flag in the claude-video watch command as documented in skills/watch/SKILL.md

Frequently Asked Questions

What is the default resolution for claude-video?

The default frame width is 512px, producing frames at 512 × 288 px and consuming approximately 197 image tokens per frame. This setting is defined in skills/watch/SKILL.md and applied when you run claude-video watch without specifying a resolution flag.

How much do tokens increase at 1024px resolution?

Bumping the resolution to 1024px roughly quadruples the image tokens per frame compared to the 512px default. According to skills/watch/SKILL.md at line 245, this significant increase in token consumption is why the higher resolution should only be used when necessary for reading on-screen text.

Can I use resolutions other than 512 or 1024?

Yes, the --resolution flag accepts custom width values in pixels, which skills/watch/scripts/watch.py passes directly to the frame extraction logic. However, 512px and 1024px are the only documented and tested resolutions in the repository, with 1024px specifically recommended as the threshold for text readability.

Why does higher resolution improve text recognition?

Claude's vision model processes images as discrete tokens, where higher-resolution frames contain more pixel data and finer detail. At 1024 × 576 px, on-screen text appears sharper and more legible compared to the 512 × 288 px default, enabling accurate transcription of small fonts in terminal windows, code editors, and presentation slides.

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