# How Claude Video's Focused Range Mode Works with `--start` and `--end` > Discover how Claude Video's focused range mode efficiently processes video segments using start and end flags. Learn about budget adjustments, transcript filtering, and validation for precise video analysis. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: how-to-guide - Published: 2026-08-02 --- **Claude Video's `watch` skill uses `--start` and `--end` flags to restrict processing to a specific video segment, automatically adjusting frame extraction budgets, transcript filtering, and validation to operate only within the defined time window.** The `bradautomates/claude-video` repository provides a powerful video analysis CLI that avoids processing entire files when you only need a segment. By leveraging the focused range mode with `--start` and `--end` parameters, you can extract frames and transcripts from precise timestamps while the system automatically recalculates sampling rates and validates bounds against the video duration. ## Parsing Time Inputs and Validating Ranges The focused range mode begins by parsing string inputs into numeric seconds. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the `argparse` configuration registers `--start` and `--end` as optional string arguments. These raw values are converted to floats using the `parse_time` function imported from [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), which supports **SS**, **MM:SS**, and **HH:MM:SS** formats. Once converted, the code enforces strict validation rules: - **The start timestamp** must be greater than or equal to 0. - **The end timestamp** must be greater than the start timestamp when both are provided. - **The start value** cannot exceed the video's total duration. If any validation fails, the CLI exits before attempting frame extraction. ## Calculating the Effective Window and Focused Flag After validation, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) calculates the effective processing window. The variables `effective_start` defaults to `0` seconds, while `effective_end` defaults to the full video length. When flags are present, the parsed values override these defaults to create the constrained bounds. The boolean `focused` flag is set to `True` when either `--start` or `--end` is supplied. This flag drives conditional logic throughout the pipeline, signaling downstream functions to restrict their operations to the calculated window rather than the full duration. ## Adjusting Frame Extraction Budgets The focused range mode significantly changes how the **auto-fps** (frames per second) calculation works. When `focused` is true, the code calls `auto_fps_focus(effective_duration, max_frames=budget_cap)` instead of the standard `auto_fps` function. This adjustment ensures the frame budget is calculated against the shortened duration rather than the full video length. By passing the effective window duration to the budget calculator, Claude Video maintains consistent sampling density without exceeding API limits on the focused segment. ## Filtering Transcripts and Cue Frames When transcripts are available (from captions or Whisper), the `filter_range` function in [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) discards any segments falling outside the `[start, end]` interval. This prevents out-of-range text from polluting the analysis context. For user-supplied cue timestamps (via `--timestamps`), the system interprets these as absolute timestamps against the full video. However, any cues falling outside the focused window are dropped with a log message, ensuring only relevant visual references are processed. ## Frame Extraction Within Constraints All frame extraction functions respect the focused window boundaries. The `extract_keyframes` and `extract_scene_or_uniform` functions in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) receive explicit `start_seconds` and `end_seconds` parameters. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), these boundaries are passed at lines 104-114, ensuring that keyframe analysis and uniform sampling only consider frames within the effective window. This architectural constraint prevents unnecessary disk I/O and API calls on excluded portions of the video. ## Usage Examples Execute focused range mode using standard time notation: ```bash # Extract frames from 1 minute 30 seconds to 2 minutes 45 seconds watch https://example.com/video.mp4 --start 01:30 --end 02:45 # Process local file with balanced detail and custom resolution watch ./local.mov --detail balanced --resolution 768 --start 00:10 --end 00:45 ``` Both commands will: 1. Download the video or load the local file. 2. Compute an auto-fps budget fitting the shortened window duration. 3. Return only frames and transcript segments within the specified bounds. ## Summary - **Time parsing** supports SS, MM:SS, and HH:MM:SS formats via `parse_time` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py). - **Validation** ensures logical bounds and prevents start times from exceeding video duration in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py). - **Effective windows** default to full video bounds unless overridden by user flags. - **The `focused` boolean** triggers conditional logic for transcript filtering and frame extraction budgets. - **Auto-fps calculation** switches to `auto_fps_focus` to maintain proper sampling density within shortened durations. - **Transcript segments** are trimmed using `filter_range` to exclude out-of-window content. - **Frame extraction** functions receive explicit start/end parameters to constrain visual analysis. ## Frequently Asked Questions ### What time formats does Claude Video accept for --start and --end? Claude Video accepts **SS** (seconds only), **MM:SS** (minutes and seconds), or **HH:MM:SS** (hours, minutes, and seconds). The `parse_time` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) converts these strings into float values representing seconds. ### What happens if I only specify --start without --end? The effective window begins at your specified start time and continues to the end of the video. The `focused` flag activates, and `effective_end` defaults to the video's total duration. The auto-fps calculation adjusts for the remaining runtime from your start point. ### Does focused range mode affect how transcripts are processed? Yes. When focused range mode is active, the `filter_range` function in [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) removes any transcript segments (from captions or Whisper) that fall outside the `[start, end]` interval. This ensures Claude only receives text context from the relevant portion of the video. ### How does the frame budget change when using --start and --end? The frame budget recalculates based on the shortened duration. Instead of calling `auto_fps` on the full video length, the code invokes `auto_fps_focus(effective_duration, max_frames=budget_cap)` in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py). This maintains appropriate sampling rates for the focused segment without exceeding API frame limits on the excluded portions.