How to Specify Start and End Times in Claude-Video Using `--start` and `--end` Flags

Use the --start and --end flags with the watch command to process only a specific video segment, accepting timestamps in seconds (SS), minutes:seconds (MM:SS), or hours:minutes:seconds (HH:MM:SS) formats.

The claude-video repository by bradautomates provides a watch skill that processes video content through Claude AI. By leveraging the --start and --end command-line flags defined in skills/watch/scripts/watch.py, you can limit processing to specific time ranges, reducing API costs and processing time while focusing analysis on relevant segments.

Supported Time Formats

The watch skill accepts three flexible timestamp formats through an internal parse_timestamp helper function:

• Seconds only: 30 (30 seconds)
• Minutes:Seconds: 01:30 (1 minute 30 seconds)
• Hours:Minutes:Seconds: 01:30:45 (1 hour 30 minutes 45 seconds)

All formats are normalized to floating-point seconds for internal processing, ensuring precise frame extraction and transcription boundaries.

Validation Rules and Constraints

According to the source code in skills/watch/scripts/watch.py, the system enforces strict validation at lines 144-148 to prevent invalid ranges:

• --start must be non-negative (line 144): You cannot specify negative timestamps
• --end must be greater than --start (line 146): The end time must strictly follow the start time
• Both must be within video duration (line 148): Timestamps exceeding the video length raise a SystemExit error

These validations occur after parsing but before any download or processing begins, ensuring efficient resource usage.

Command-Line Usage Examples

Basic Usage (Seconds)

Process a 60-second clip starting at 30 seconds:

watch https://www.youtube.com/watch?v=abc123 --start 30 --end 90

Using MM:SS Format

Extract the segment from 1 minute 15 seconds to 2 minutes 45 seconds:

watch https://www.youtube.com/watch?v=abc123 --start 01:15 --end 02:45

Using HH:MM:SS Format

Process a 5-minute segment from a longer video:

watch https://www.youtube.com/watch?v=abc123 --start 00:05:00 --end 00:10:30

Error Handling Examples

Invalid range (start after end):

watch https://www.youtube.com/watch?v=abc123 --start 120 --end 60

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

Out-of-range timestamp:

watch https://www.youtube.com/watch?v=abc123 --start 0 --end 9999

# → SystemExit: --start 0.0s is past end of video (123.4s)

Technical Implementation Details

Argument Parsing in watch.py

The flag definitions reside at line 49 of skills/watch/scripts/watch.py, where the script registers --start and --end as optional string arguments. The parse_timestamp helper converts these string inputs into floating-point seconds, supporting the flexible formatting options described above.

The validation logic at lines 144-148 ensures that:

1. Start time ≥ 0
2. End time > Start time
3. Both timestamps ≤ video duration (retrieved from metadata)

Frame Extraction Integration

The timing parameters propagate through to skills/watch/scripts/frames.py at line 689, where the same --start and --end flags are exposed. This script forwards the validated timestamps directly to the ffmpeg command that extracts frames, ensuring that only the specified temporal segment generates visual data for Claude's analysis.

Summary

• Three time formats supported: Seconds, MM:SS, and HH:MM:SS via parse_timestamp in watch.py
• Strict validation: Start must be ≥ 0, end must exceed start, and both must fit within the video duration (lines 144-148)
• Pipeline integration: Flags defined at line 49 of skills/watch/scripts/watch.py and implemented at line 689 of skills/watch/scripts/frames.py
• Resource efficiency: Only the specified segment is downloaded, processed, and sent to the Claude API

Frequently Asked Questions

What time formats does claude-video accept?

Claude-video accepts timestamps in three formats parsed by the parse_timestamp helper: raw seconds (e.g., 90), minutes:seconds (e.g., 01:30), and hours:minutes:seconds (e.g., 00:01:30). All formats convert to floating-point seconds for precise ffmpeg frame extraction.

What happens if I specify an end time beyond the video length?

The validation logic at line 148 of skills/watch/scripts/watch.py detects when timestamps exceed the video's total duration and raises a SystemExit error with a descriptive message indicating the maximum valid timestamp. Processing halts before any network requests or API calls occur.

Can I use the --start and --end flags with the frames extraction script directly?

Yes. The skills/watch/scripts/frames.py file advertises the same --start and --end options at line 689, allowing direct frame extraction for specific time ranges without running the full watch pipeline. This is useful when you only need visual frames rather than the complete AI analysis.

Why does claude-video require that the end time be strictly greater than the start time?

The constraint at line 146 of watch.py ensures logical temporal ordering and prevents zero-duration or negative-duration processing jobs. This validation eliminates edge cases in the ffmpeg command construction and ensures that the downstream pipeline receives a valid, non-empty media segment to analyze.

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