# Claude-Video Frame Extraction Modes: auto_fps, fixed_fps, and every_n_seconds Explained

> Explore Claude-Video frame extraction modes: auto_fps, fixed_fps, and every_n_seconds. Control temporal granularity for precise video analysis.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-09

---

**Claude-Video supports three distinct frame extraction modes—`auto_fps` (default), `fixed_fps`, and `every_n_seconds`—that let you control temporal granularity by automatically adjusting for video length, forcing a specific frame rate, or sampling at fixed time intervals.**

The `bradautomates/claude-video` repository provides intelligent video processing capabilities for Claude, with **frame extraction modes** handled centrally in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). Understanding these three strategies allows you to optimize the balance between analysis detail and computational overhead when processing video content.

## The Three Frame Extraction Modes

Claude-Video implements three distinct strategies for sampling frames from video files, selectable via the `mode` key in the skill's JSON configuration.

### auto_fps (Default)

The `auto_fps` mode automatically inspects the video's native frame rate using `ffprobe` and applies intelligent downsampling to prevent overwhelming downstream LLMs. If the video reports a variable frame rate or very high FPS, the script automatically reduces the output to a sensible rate—approximately 1 FPS for long videos and 2-5 FPS for typical clips.

This is the fallback behavior when no mode is explicitly specified in the configuration.

### fixed_fps

The `fixed_fps` mode bypasses auto-detection and extracts frames at a user-specified rate. You provide an exact FPS value (e.g., `fps=2`), which the script passes directly to `ffmpeg` via the `-vf fps=<value>` filter.

Use this mode when you need precise temporal resolution, such as analyzing fast-motion scenes or synchronizing with transcripts at a known cadence.

### every_n_seconds

The `every_n_seconds` mode samples frames at fixed temporal intervals rather than frame rates. You specify an interval in seconds (e.g., `interval=5`), and the script translates this into an FPS value of `1/interval`, extracting one frame every *n* seconds of video.

This approach is ideal for very long videos where you only need periodic snapshots, such as summarizing a 2-hour lecture by grabbing a frame every 30 seconds.

## Configuring Frame Extraction in Claude-Video

Configuration is managed through [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), which validates mode-specific parameters before [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) executes the extraction.

### Using auto_fps (Default Behavior)

When no mode is specified, the system automatically applies `auto_fps`:

```python
from scripts import frames, config

cfg = config.load()

# No explicit mode → auto_fps applied automatically

frames.extract(cfg, video_path="interview.mp4")

```

### Using fixed_fps for Precise Control

Set the mode and specify your desired frame rate:

```json
{
  "mode": "fixed_fps",
  "fps": 3
}

```

```python
cfg = config.load()
frames.extract(cfg, video_path="sports_clip.mp4")

# ffmpeg receives: -vf fps=3

```

### Using every_n_seconds for Long Videos

Configure periodic sampling by specifying the interval in seconds:

```json
{
  "mode": "every_n_seconds",
  "interval": 10
}

```

```python
cfg = config.load()
frames.extract(cfg, video_path="documentary.mp4")

# ffmpeg receives: -vf fps=0.1 (1 frame every 10 seconds)

```

## Technical Implementation Details

The extraction pipeline is orchestrated by [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which coordinates downloading, frame extraction, and transcription. The core frame extraction logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), where the script:

1. Parses the `mode` key from the configuration object
2. Validates required parameters (`fps` for `fixed_fps`, `interval` for `every_n_seconds`)
3. Constructs the appropriate `ffmpeg` command with the `-vf fps` filter
4. Falls back to `auto_fps` when no mode is specified

According to the source code in `bradautomates/claude-video`, the `auto_fps` implementation specifically checks for variable frame rates and high-FPS content to ensure the downstream LLM receives a manageable number of images without losing contextual relevance.

## Summary

- **Three extraction strategies**: `auto_fps` (default), `fixed_fps`, and `every_n_seconds` provide flexible control over temporal sampling density.
- **Configuration-driven selection**: Set the `mode` key in the skill's JSON configuration, with optional `fps` or `interval` parameters depending on your chosen strategy.
- **ffmpeg integration**: All modes ultimately translate to ffmpeg's `-vf fps` filter, with `auto_fps` adding intelligent rate limiting based on video metadata analysis.
- **Sensible defaults**: When no mode is specified, the system automatically falls back to `auto_fps` to ensure optimal performance without manual tuning.

## Frequently Asked Questions

### What is the default frame extraction mode in Claude-Video?

If no mode is specified in the configuration, the system defaults to `auto_fps`. This mode automatically inspects the video's native frame rate using `ffprobe` and reduces it to a manageable level—approximately 1 FPS for long videos and 2-5 FPS for typical clips—to prevent overwhelming downstream processing while maintaining representative coverage.

### How do I extract frames at a specific time interval?

Use the `every_n_seconds` mode by setting `"mode": "every_n_seconds"` and specifying an `interval` value in seconds (e.g., `30` for one frame every 30 seconds). According to the implementation in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the system translates this interval into an FPS value of `1/interval` and passes it to ffmpeg's `-vf fps` filter.

### Which mode should I use for analyzing fast-motion scenes?

For fast-motion analysis requiring precise temporal resolution, use `fixed_fps` mode. Set `"mode": "fixed_fps"` and specify your desired frame rate via the `fps` parameter (e.g., `5` for 5 frames per second). This bypasses automatic detection and extracts exactly the requested number of frames per second, ensuring you capture rapid movements.

### Where is the frame extraction logic implemented in the source code?

The core extraction logic is implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), which parses the mode configuration and constructs the ffmpeg command. Configuration validation occurs in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), while the orchestration pipeline is managed by [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) according to the `bradautomates/claude-video` source code.