How Claude Video's Focused Range Mode Works with `--start` and `--end`

Claude Video's watch skill uses --start and --end flags to restrict processing to a specific video segment, automatically adjusting frame extraction budgets, transcript filtering, and validation to operate only within the defined time window.

The bradautomates/claude-video repository provides a powerful video analysis CLI that avoids processing entire files when you only need a segment. By leveraging the focused range mode with --start and --end parameters, you can extract frames and transcripts from precise timestamps while the system automatically recalculates sampling rates and validates bounds against the video duration.

Parsing Time Inputs and Validating Ranges

The focused range mode begins by parsing string inputs into numeric seconds. In skills/watch/scripts/watch.py, the argparse configuration registers --start and --end as optional string arguments. These raw values are converted to floats using the parse_time function imported from frames.py, which supports SS, MM:SS, and HH:MM:SS formats.

Once converted, the code enforces strict validation rules:

• The start timestamp must be greater than or equal to 0.
• The end timestamp must be greater than the start timestamp when both are provided.
• The start value cannot exceed the video's total duration.

If any validation fails, the CLI exits before attempting frame extraction.

Calculating the Effective Window and Focused Flag

After validation, watch.py calculates the effective processing window. The variables effective_start defaults to 0 seconds, while effective_end defaults to the full video length. When flags are present, the parsed values override these defaults to create the constrained bounds.

The boolean focused flag is set to True when either --start or --end is supplied. This flag drives conditional logic throughout the pipeline, signaling downstream functions to restrict their operations to the calculated window rather than the full duration.

Adjusting Frame Extraction Budgets

The focused range mode significantly changes how the auto-fps (frames per second) calculation works. When focused is true, the code calls auto_fps_focus(effective_duration, max_frames=budget_cap) instead of the standard auto_fps function.

This adjustment ensures the frame budget is calculated against the shortened duration rather than the full video length. By passing the effective window duration to the budget calculator, Claude Video maintains consistent sampling density without exceeding API limits on the focused segment.

Filtering Transcripts and Cue Frames

When transcripts are available (from captions or Whisper), the filter_range function in transcribe.py discards any segments falling outside the [start, end] interval. This prevents out-of-range text from polluting the analysis context.

For user-supplied cue timestamps (via --timestamps), the system interprets these as absolute timestamps against the full video. However, any cues falling outside the focused window are dropped with a log message, ensuring only relevant visual references are processed.

Frame Extraction Within Constraints

All frame extraction functions respect the focused window boundaries. The extract_keyframes and extract_scene_or_uniform functions in frames.py receive explicit start_seconds and end_seconds parameters.

In skills/watch/scripts/watch.py, these boundaries are passed at lines 104-114, ensuring that keyframe analysis and uniform sampling only consider frames within the effective window. This architectural constraint prevents unnecessary disk I/O and API calls on excluded portions of the video.

Usage Examples

Execute focused range mode using standard time notation:

# Extract frames from 1 minute 30 seconds to 2 minutes 45 seconds

watch https://example.com/video.mp4 --start 01:30 --end 02:45

# Process local file with balanced detail and custom resolution

watch ./local.mov --detail balanced --resolution 768 --start 00:10 --end 00:45

Both commands will:

1. Download the video or load the local file.
2. Compute an auto-fps budget fitting the shortened window duration.
3. Return only frames and transcript segments within the specified bounds.

Summary

• Time parsing supports SS, MM:SS, and HH:MM:SS formats via parse_time in frames.py.
• Validation ensures logical bounds and prevents start times from exceeding video duration in watch.py.
• Effective windows default to full video bounds unless overridden by user flags.
• The focused boolean triggers conditional logic for transcript filtering and frame extraction budgets.
• Auto-fps calculation switches to auto_fps_focus to maintain proper sampling density within shortened durations.
• Transcript segments are trimmed using filter_range to exclude out-of-window content.
• Frame extraction functions receive explicit start/end parameters to constrain visual analysis.

Frequently Asked Questions

What time formats does Claude Video accept for --start and --end?

Claude Video accepts SS (seconds only), MM:SS (minutes and seconds), or HH:MM:SS (hours, minutes, and seconds). The parse_time function in skills/watch/scripts/frames.py converts these strings into float values representing seconds.

What happens if I only specify --start without --end?

The effective window begins at your specified start time and continues to the end of the video. The focused flag activates, and effective_end defaults to the video's total duration. The auto-fps calculation adjusts for the remaining runtime from your start point.

Does focused range mode affect how transcripts are processed?

Yes. When focused range mode is active, the filter_range function in transcribe.py removes any transcript segments (from captions or Whisper) that fall outside the [start, end] interval. This ensures Claude only receives text context from the relevant portion of the video.

How does the frame budget change when using --start and --end?

The frame budget recalculates based on the shortened duration. Instead of calling auto_fps on the full video length, the code invokes auto_fps_focus(effective_duration, max_frames=budget_cap) in watch.py. This maintains appropriate sampling rates for the focused segment without exceeding API frame limits on the excluded portions.

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