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

Pass --start and --end to the watch.py script to activate focus mode, which extracts frames at a denser rate (up to 2 fps) from a specific time window while filtering transcripts to match.

Claude-Video, the open-source video analysis toolkit from bradautomates/claude-video, provides precise temporal control through its --start and --end command-line flags. These flags enable focus mode, allowing you to extract high-density frames from specific segments rather than processing the entire video. Understanding how to use the --start and --end flags in claude-video for focused frame extraction ensures you get detailed visual analysis exactly where you need it.

Understanding Focus Mode in Claude-Video

When you provide either --start or --end to skills/watch/scripts/watch.py, the script switches from full-video scanning to focus mode. In this mode, the system concentrates its frame extraction budget on your specified window rather than distributing frames across the entire duration.

The focus mode logic resides in skills/watch/scripts/watch.py, which orchestrates the entire pipeline including argument parsing, validation, and user feedback.

Timestamp Filtering for Transcripts

Focus mode also affects transcription handling. According to SKILL.md, any transcript cue falling outside the [start, end] window is automatically dropped (lines 218-220), while remaining timestamps are reported as absolute source times.

Supported Time Formats and Validation

The --start and --end flags accept flexible human-readable time formats validated by the main orchestrator.

Time Format Options

As implemented in skills/watch/scripts/watch.py (lines 49-52), the flags accept string values in three formats:

• SS – Seconds only (e.g., 50)
• MM:SS – Minutes and seconds (e.g., 2:15)
• HH:MM:SS – Hours, minutes, and seconds (e.g., 1:12:00)

Validation Rules

The script enforces strict temporal boundaries at lines 144-148 of watch.py:

• Start time must be greater than or equal to 0
• End time must be strictly greater than the start time
• Start time cannot exceed the total video duration

Frame Budget Adjustments in Focus Mode

Focus mode automatically increases frame density while maintaining overall caps. According to SKILL.md (lines 156-162), the per-second frame budget becomes denser (up to 2 fps) when these flags are present, though it still respects the overall mode caps: approximately 100 frames for balanced mode and 50 for efficient mode.

This means a 30-second clip extracted with --start and --end receives significantly more frames per second than the same duration would receive in a full-video scan.

How to Extract Frames from a Specific Time Range

Here are practical examples for both local files and remote URLs using the watch.py entry point.

Extract frames from a local video file between 50 and 60 seconds:

python3 "${SKILL_DIR}/skills/watch/scripts/watch.py" video.mp4 --start 50 --end 60

Zoom into a specific range of a YouTube video with custom FPS:

python3 "${SKILL_DIR}/skills/watch/scripts/watch.py" "$URL" --start 2:15 --end 2:45 --fps 2

Extract everything from a specific time onward (omitting --end):

python3 "${SKILL_DIR}/skills/watch/scripts/watch.py" "$URL" --start 1:12:00

In slash-command environments (Claude Code, Codex, or Cursor), pass the flags after the URL or file path:

/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60

Technical Implementation Details

The frame extraction logic in skills/watch/scripts/frames.py (lines 689-713) receives the --start and --end arguments directly, computing the frame-extraction schedule to ensure extracted images correspond exactly to the requested segment.

If you attempt to process a long video without these flags, watch.py (lines 332-335) detects when a full-video scan would produce sparse results and prints a warning suggesting you re-run with --start and --end to obtain a richer view.

Summary

• Focus mode activation: Adding --start or --end to watch.py switches from full-video scanning to concentrated segment analysis
• Flexible time syntax: Accepts seconds (50), minutes:seconds (2:15), or hours:minutes:seconds (1:12:00) formats
• Denser extraction: Up to 2 fps budget allocation within the specified window compared to sparse full-video distribution
• Transcript filtering: Automatically excludes cues outside the time window while preserving absolute timestamps
• Validation enforcement: watch.py ensures start ≥ 0, end > start, and start does not exceed video duration

Frequently Asked Questions

What time formats does claude-video accept?

Claude-Video accepts three time formats in skills/watch/scripts/watch.py: raw seconds (50), minutes and seconds (2:15), and full hours-minutes-seconds notation (1:12:00). The argument parser at lines 49-52 converts these to seconds internally for processing.

How does focus mode affect frame extraction quality?

Focus mode increases the per-second frame budget to up to 2 fps according to SKILL.md, while maintaining the total frame caps (balanced ~100, efficient ~50). This produces denser visual coverage of your specific segment compared to the sparse distribution used for full-video scans.

Can I use --start without --end?

Yes. You can specify only --start to extract from that timestamp to the end of the video. The validation logic in watch.py requires that when both are present, the end time must exceed the start time.

Where is the focus mode logic implemented?

The focus mode logic spans three key files: skills/watch/scripts/watch.py handles argument parsing and validation, skills/watch/scripts/frames.py implements the actual frame extraction schedule (lines 689-713), and skills/watch/SKILL.md defines the behavior specifications including budget adjustments and transcript filtering.

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