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

> Manually override auto FPS calculation in claude-video using the --fps flag for precise control. Learn to set a fixed frame rate and understand the MAX_FPS limit.

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

---

**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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) defines the flag on line 33 using `argparse`:

```python
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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash

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

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)
- Override logic executes in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`.