How Focus Mode with `--start` and `--end` Works in claude-video for Specific Sections

Focus mode in claude-video lets you isolate specific video segments by passing --start and --end time strings to the watch command, which validates the range before invoking ffmpeg to extract frames only from that window.

The claude-video repository provides a watch skill that downloads videos, extracts frames, and optionally transcribes audio. When working with long videos, processing the entire file is often unnecessary. Focus mode solves this by allowing you to specify exact time ranges using --start and --end flags, ensuring that only the relevant segment is analyzed.

Parsing Focus Mode Arguments

The entry-point script skills/watch/scripts/watch.py defines the focus mode interface at line 49. The CLI accepts two optional parameters:

• --start – Accepts a time string in seconds, MM:SS, or HH:MM:SS format. Defaults to None.
• --end – Accepts the same time formats to mark the end of the extraction window.

These arguments are processed before any network or disk activity begins, ensuring that malformed inputs trigger immediate feedback.

Validation Logic

After parsing, watch.py converts the time strings into seconds and performs three critical validations at lines 144-148:

1. Non-negative start – The start time must be ≥ 0. If negative, the script aborts with:

   SystemExit: --start must be non-negative

2. End greater than start – The end time must exceed the start time. If not, the script aborts with:

   SystemExit: --end must be greater than --start

3. Start within duration – The start time cannot exceed the video's total length. If it does, the script aborts with:

   SystemExit: --start {start_sec:.1f}s is past end of video ({full_duration:.1f}s)

This validation sequence ensures that downstream processes receive only valid, bounded time ranges.

Frame Extraction Pipeline

Once validated, the start_sec and end_sec values are forwarded to skills/watch/scripts/frames.py. This script receives the same --start and --end flags (documented in its help string at line 689) and passes them directly to ffmpeg.

The ffmpeg invocation seeks to the start timestamp and terminates at the end timestamp, effectively limiting frame extraction to the requested slice without processing the entire video file.

Usage Examples

Basic focus mode with timestamps

# Extract frames only from 1:30 to 2:45 of a YouTube video

watch "https://youtu.be/abcd1234" --start 01:30 --end 02:45

Using plain seconds

watch "./local-video.mp4" --start 90 --end 165

Combining with other flags

watch "https://vimeo.com/123456" \
  --start 00:00:30 --end 00:01:00 \
  --max-frames 200 \
  --no-dedup \
  --question "What is being shown in this segment?"

If you omit --start and --end, the CLI prints a reminder at line 332 suggesting you re-run with --start HH:MM:SS --end HH:MM:SS to zoom into a specific section.

Error Handling Examples

Negative start time

watch video.mp4 --start -5

# → SystemExit: --start must be non-negative

End before start

watch video.mp4 --start 00:02:00 --end 00:01:00

# → SystemExit: --end must be greater than --start

Start beyond video duration

watch video.mp4 --start 10:00

# → SystemExit: --start 600.0s is past end of video (300.0s)

Summary

• Focus mode uses --start and --end flags in skills/watch/scripts/watch.py to limit processing to specific video segments.
• Time formats supported include seconds, MM:SS, and HH:MM:SS strings.
• Validation occurs early (lines 144-148), checking for non-negative start, end > start, and start within video duration.
• Frame extraction is handled by skills/watch/scripts/frames.py (line 689), which passes the range to ffmpeg for efficient segment processing.
• Error messages provide immediate feedback before any network or disk operations begin.

Frequently Asked Questions

What time formats does claude-video accept for --start and --end?

claude-video accepts three formats: plain seconds (e.g., 90), minutes:seconds (01:30), or hours:minutes:seconds (00:01:30). The watch.py script parses these strings and converts them to seconds before validation.

Why does the validation happen before downloading the video?

The watch command retrieves the video's metadata and duration before frame extraction begins. This allows skills/watch/scripts/watch.py to validate that your --start time exists within the video bounds at line 148, preventing wasted bandwidth and processing on invalid ranges.

Can I use --start without --end?

While the argument parser allows omitting either flag, the validation logic requires --end to be greater than --start if both are provided. If you specify only --start, the extraction will begin at that timestamp and continue to the end of the video, depending on how frames.py handles the None value for end time.

How does focus mode affect transcription?

Focus mode limits the audio segment sent to transcription models to the same --start and --end window used for frame extraction. Because frames.py handles the ffmpeg invocation that slices the video, both visual frames and audio tracks are constrained to your specified range, ensuring transcription covers only the relevant section.

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