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

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. 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, which validates mode-specific parameters before skills/watch/scripts/frames.py executes the extraction.

Using auto_fps (Default Behavior)

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

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:

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

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:

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

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, which coordinates downloading, frame extraction, and transcription. The core frame extraction logic resides in 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, 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, which parses the mode configuration and constructs the ffmpeg command. Configuration validation occurs in skills/watch/scripts/config.py, while the orchestration pipeline is managed by skills/watch/scripts/watch.py according to the bradautomates/claude-video source code.

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