# How to Specify Start and End Times in Claude-Video Using `--start` and `--end` Flags > Learn to specify start and end times in claude-video using --start and --end flags. Process specific video segments easily with various timestamp formats. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: how-to-guide - Published: 2026-07-25 --- **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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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: ```bash 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: ```bash 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: ```bash watch https://www.youtube.com/watch?v=abc123 --start 00:05:00 --end 00:10:30 ``` ### Error Handling Examples **Invalid range (start after end):** ```bash watch https://www.youtube.com/watch?v=abc123 --start 120 --end 60 # → SystemExit: --end must be greater than --start ``` **Out-of-range timestamp:** ```bash 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) and implemented at line 689 of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.