How to Specify a Custom Time Range for Video Analysis in Claude-Video

Use the --start and --end flags with the /watch skill to limit analysis to a specific video segment, supporting SS, MM:SS, or HH:MM:SS time formats.

The Claude-Video project provides precise control over video processing through custom time range selection. By specifying start and end timestamps, you can significantly reduce runtime and token usage while focusing the analysis on relevant content. This guide explains how to specify a custom time range for video analysis based on the actual implementation in the bradautomates/claude-video repository.

Using the --start and --end Flags

The CLI entry point in skills/watch/scripts/watch.py defines two optional arguments that constrain the analysis window. When provided, these values propagate through the extraction pipeline to limit both frame sampling and transcript processing.

Supported Time Formats

The parse_time function implemented in skills/watch/scripts/frames.py (lines 55-62) accepts three human-readable formats and converts them to seconds:

• SS – Seconds only (e.g., 90 for 1 minute 30 seconds)
• MM:SS – Minutes and seconds (e.g., 2:30)
• HH:MM:SS – Hours, minutes, and seconds (e.g., 1:05:30)

Command Line Examples

Extract frames and transcript for a specific one-minute segment:

watch https://example.com/video.mp4 \
      --detail balanced \
      --start 02:30 \
      --end 03:30 \
      --resolution 640

Analyze only the first two minutes of a local file:

watch path/to/video.mov \
      --detail high \
      --start 00:00 \
      --end 02:00

How Time Range Filtering Works Under the Hood

The implementation follows a three-stage pipeline that ensures precise temporal boundaries while optimizing performance.

Argument Parsing in watch.py

The CLI definition in skills/watch/scripts/watch.py (lines 49-51) adds the --start and --end flags as optional string arguments. These raw values pass directly to the parse_time helper before any extraction begins.

Time Conversion Logic

Within skills/watch/scripts/frames.py, the parse_time function handles the string-to-seconds conversion. This normalized representation (start_sec and end_sec) becomes the canonical reference for all downstream operations, ensuring consistent boundary enforcement across different extraction strategies.

Optimized Frame Extraction

The time range triggers two performance optimizations:

1. Adaptive FPS Budgeting – The system computes auto_fps_focus to allocate a denser sampling rate within the constrained window rather than spreading frames across the entire video duration.

2. FFmpeg Seek Operations – The extraction functions (extract, extract_scene_candidates, extract_keyframes, and extract_at_timestamps) receive -ss (seek start) and -to (stop time) parameters. This limits decoding overhead by instructing FFmpeg to process only the specified interval, avoiding full-file scanning.

Combining Time Ranges with Custom Timestamps

When using --timestamps to specify exact cue frames, the values undergo separate parsing via parse_timestamps before being filtered against the --start and --end boundaries. Any timestamps falling outside the defined range are automatically discarded, ensuring the final output contains only frames within your specified window.

# Request specific timestamps, but only those between 10s and 60s will be processed

watch path/to/video.mov \
      --detail transcript \
      --start 00:10 \
      --end 01:00 \
      --timestamps 5,15,30,45,90

Programmatic Usage

You can also specify a custom time range for video analysis when invoking the skill programmatically:

from watch import main
import sys

sys.argv = [
    "watch",
    "https://example.com/video.mp4",
    "--detail", "balanced",
    "--start", "00:01:05",
    "--end", "00:02:20",
]
main()  # Generates markdown report for the selected 75-second range

Summary

• The --start and --end flags in skills/watch/scripts/watch.py define analysis boundaries using human-readable time strings.
• The parse_time function in skills/watch/scripts/frames.py converts SS, MM:SS, and HH:MM:SS formats to seconds for internal processing.
• FFmpeg receives -ss and -to options to limit decoding to the specified range, improving performance.
• The auto_fps_focus mechanism adjusts sampling density to maximize frame quality within the constrained window.
• Custom timestamps provided via --timestamps are automatically filtered to exclude values outside the start/end range.

Frequently Asked Questions

What time formats does Claude-Video support for time ranges?

According to the parse_time implementation in skills/watch/scripts/frames.py, the system accepts seconds only (90), minutes:seconds (2:30), or hours:minutes:seconds (01:30:45). All formats are normalized to total seconds for internal calculations.

Can I use --start without --end (or vice versa)?

Yes, both arguments are optional. Providing only --start analyzes from that timestamp to the end of the video, while providing only --end analyzes from the beginning up to that point. The auto_fps_focus calculation adjusts accordingly to optimize frame distribution within the available window.

How does specifying a time range affect frame extraction performance?

Specifying a range significantly improves performance by passing -ss and -to parameters to FFmpeg in the extraction functions (extract, extract_scene_candidates, etc.). This prevents decoding the entire video file, reducing I/O and processing time proportionally to the segment length relative to the full duration.

What happens if I provide timestamps outside the specified range?

When using --timestamps alongside --start and --end, the system filters the cue list against the time window during the preprocessing phase. Timestamps before --start or after --end are silently discarded, ensuring only relevant frames are extracted and sent for analysis.

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