How to Manually Override the Auto-FPS Calculation with --fps in claude-video

Use the --fps flag when running the watch command to replace the automatic frame-rate calculation with a fixed value, which the tool then caps to the internal MAX_FPS safety limit.

The claude-video repository provides intelligent video frame extraction that normally calculates the optimal frames-per-second rate automatically based on duration and frame budget. When you need precise control over sampling density, you can manually override the auto-FPS calculation with the --fps flag to specify exactly how many frames to extract per second.

Where --fps Overrides the Auto-FPS Logic

Argument Parsing in watch.py

The entry point in skills/watch/scripts/watch.py defines the flag on line 33 using argparse:

ap.add_argument("--fps", type=float, default=None, help="Override auto-fps")

This accepts a floating-point value that defaults to None, allowing the automatic calculation to run when the flag is omitted.

The Override Implementation

After computing initial values via auto_fps or auto_fps_focus (lines 55-58), the script checks for manual input on lines 59-62:

if args.fps is not None:
    fps = min(args.fps, MAX_FPS)                     # cap to the library’s safe maximum

    target = max(1, int(round(fps * effective_duration)))

This logic completely replaces the automatically computed fps and target frame count with your manually specified rate, subject to the safety ceiling.

How the Automatic FPS Calculation Works

Before the override applies, claude-video determines the frame-extraction rate automatically using logic in skills/watch/scripts/frames.py. The functions auto_fps and auto_fps_focus analyze video duration against requested frame budgets to determine optimal extraction rates.

When you provide --fps, this heuristic calculation is bypassed entirely. The effective_duration (total duration or the specified start/end range) is multiplied by your manual FPS value to determine the final target frame count.

CLI and Python Usage Examples

Command Line

Override the auto-FPS calculation for specific sampling rates:

# Let claude-video choose the FPS automatically (default behavior)

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

# Force a constant 2 frames per second

watch https://example.com/video.mp4 --fps 2

# Use a higher value; if it exceeds MAX_FPS, it reduces automatically

watch https://example.com/video.mp4 --fps 30

Python Subprocess

Invoke the tool programmatically with manual FPS control:

import subprocess

# Auto-FPS (no override)

subprocess.run(["watch", "my_video.mp4"])

# Manual FPS override at 5 frames per second

subprocess.run(["watch", "my_video.mp4", "--fps", "5"])

Safety Limits and MAX_FPS

The MAX_FPS constant defined in skills/watch/scripts/frames.py acts as a hard upper bound for safe extraction. Even when you manually override the auto-FPS calculation with a high --fps value, the min(args.fps, MAX_FPS) operation ensures the actual extraction rate never exceeds this internal safety limit.

The final frame target calculates as max(1, int(round(fps * effective_duration))), guaranteeing at least one frame extracts even with extremely short durations or low FPS values.

Summary

• The --fps flag in claude-video bypasses the auto_fps and auto_fps_focus heuristics in skills/watch/scripts/frames.py
• Override logic executes in skills/watch/scripts/watch.py at lines 59-62 after the initial automatic calculation
• Manual values automatically cap to MAX_FPS to prevent unsafe extraction rates
• The target frame count recalculates as max(1, int(round(fps * effective_duration))) based on your specified rate
• The flag accepts floating-point values and works with both full-video and range-limited (focus) extraction modes

Frequently Asked Questions

What happens if I specify a --fps value higher than MAX_FPS?

The tool automatically reduces your requested rate to the MAX_FPS ceiling defined in skills/watch/scripts/frames.py. According to the source code, the extraction proceeds at this capped rate to maintain system safety and prevent performance degradation.

Does --fps work when extracting a specific time range?

Yes. When you specify start/end timestamps, the code initially uses auto_fps_focus but still applies the same override logic on lines 59-62 of watch.py. Your manual --fps value replaces the calculated rate regardless of whether you are processing the full video or a specific segment.

Can I use --fps to extract fewer frames than the automatic calculation would choose?

Absolutely. Since the manual value completely replaces the automatic result, you can specify a lower FPS than the heuristic would select. This is useful when you need sparser sampling for long videos or want to reduce API costs by limiting frame density.

Which functions calculate the automatic FPS if I don't use the flag?

The automatic logic resides in skills/watch/scripts/frames.py within the auto_fps and auto_fps_focus functions. These analyze video duration and available frame budgets to determine extraction rates, but they are bypassed entirely when args.fps is not None.

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