How to Use --start and --end Flags for Focused Extraction in Claude-Video

The --start and --end flags activate a focused extraction mode that narrows processing to a specific time window, validates the temporal range, allocates a denser frame rate budget, and passes precise seek parameters to FFmpeg for efficient segment processing.

The claude-video tool provides temporal slicing capabilities through command-line flags that trigger focused extraction workflows. When you specify --start and --end parameters, the system switches from full-video processing to a concentrated analysis of your defined segment, ensuring higher frame density within the specified bounds.

Parsing Time Formats with parse_time()

In skills/watch/scripts/watch.py (lines 140-148), the entry point captures the optional --start and --end arguments and passes them to parse_time() for conversion.

Supported Input Formats

The parse_time() function in skills/watch/scripts/frames.py (lines 55-74) accepts multiple human-readable formats:

• SS - Raw seconds (e.g., "90")
• MM:SS - Minutes and seconds (e.g., "1:30")
• HH:MM:SS - Hours, minutes, and seconds (e.g., "1:30:00")

Conversion to Seconds

Regardless of input format, parse_time() returns a float representing the total number of seconds. This standardization enables consistent mathematical comparisons and FFmpeg parameter generation.

Validating the Temporal Range

Before activating focused mode, watch.py performs three critical validation checks to ensure the requested segment exists within the video boundaries.

Boundary Checks

The validation logic enforces temporal logic constraints:

• Non-negative start: --start must be greater than or equal to 0, or the system raises SystemExit("--start must be non-negative") (line 143)
• Sequential ordering: --end must exceed --start, enforced by SystemExit("--end must be greater than --start") (line 145)

Duration Constraints

The system verifies that the start time does not exceed the video's total duration, raising SystemExit(f"--start {start_sec:.1f}s is past end of video …") if the requested window begins after the video ends (line 148).

Activating Focused Extraction Mode

Once validation passes, the pipeline switches from standard to focused processing.

The Focused Flag Logic

In watch.py (line 153), the boolean focused becomes True if either --start or --end is present. This flag signals downstream functions to adjust their extraction strategy for the abbreviated timeframe.

Denser Frame Rate Budgeting

When focused is True, the system calls auto_fps_focus() instead of the standard auto_fps() (lines 332-335). Implemented in skills/watch/scripts/frames.py (lines 41-45), auto_fps_focus() calculates a higher target FPS for short clips, ensuring the extracted preview retains visual detail despite the reduced temporal window.

FFmpeg Integration for Precise Seeking

The calculated start_sec and end_sec values flow into the low-level extraction pipeline.

Passing Parameters to Extraction Functions

Core functions including extract(), extract_scene_candidates(), and extract_keyframes() receive the temporal boundaries via start_seconds and end_seconds parameters. In skills/watch/scripts/frames.py (lines 86-90), these arguments become -ss (start time) and -to (end time) options for FFmpeg.

Command Construction

FFmpeg performs a fast seek to the specified start position and stops decoding at the end point, avoiding unnecessary processing of frames outside the defined window. This selective decoding reduces computational overhead while maintaining extraction quality.

Practical Usage Examples

Extract a focused 10-second clip from 00:01:30 to 00:01:40:

watch.py https://example.com/video.mp4 --start 1:30 --end 1:40

Programmatically use the same time-parsing and FPS logic:

from skills.watch.scripts.frames import parse_time, auto_fps_focus

# Manual use of the same helpers

start = parse_time("1:30")          # → 90.0

end   = parse_time("1:40")          # → 100.0

duration = end - start               # 10 seconds

# Denser FPS for the short slice

fps, target = auto_fps_focus(duration, max_frames=100)
print(f"Focused FPS: {fps:.2f}, target frames: {target}")

Summary

• The --start and --end flags trigger focused extraction mode when either parameter is present
• parse_time() in frames.py converts HH:MM:SS, MM:SS, or SS formats to float seconds
• Strict validation ensures start ≥ 0, end > start, and start < video duration before processing
• Focused mode switches from auto_fps() to auto_fps_focus() for higher frame density in short segments
• Temporal boundaries pass through to FFmpeg as -ss and -to parameters for efficient seeking

Frequently Asked Questions

What time formats does claude-video accept?

The parse_time() function accepts raw seconds (90), minutes:seconds (1:30), or hours:minutes:seconds (1:30:00). All formats convert to a float value representing total seconds.

Why does focused extraction use a higher frame rate?

When processing short segments, auto_fps_focus() allocates a denser frame budget to ensure the preview retains sufficient detail. This compensates for the reduced temporal window while maintaining analysis quality.

What happens if --start exceeds the video duration?

The system validates the start time against the video's total duration in watch.py (line 148) and raises a SystemExit with the message "--start {start_sec:.1f}s is past end of video …" to prevent invalid extraction attempts.

How does FFmpeg handle the time range internally?

FFmpeg receives the validated start and end times as -ss and -to arguments. It performs a fast seek to the start position and stops decoding at the end time, processing only frames within the specified window rather than scanning the entire video.

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