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

> Learn how to use --start and --end flags in Claude-Video for focused extraction. Optimize processing and improve efficiency with precise time window selection and FFmpeg integration.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-07

---

**The --start and --end flags activate a focused extraction mode that narrows processing to a specific time window, validates the temporal range, allocates a denser frame rate budget, and passes precise seek parameters to FFmpeg for efficient segment processing.**

The claude-video tool provides temporal slicing capabilities through command-line flags that trigger focused extraction workflows. When you specify `--start` and `--end` parameters, the system switches from full-video processing to a concentrated analysis of your defined segment, ensuring higher frame density within the specified bounds.

## Parsing Time Formats with parse_time()

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 140-148), the entry point captures the optional `--start` and `--end` arguments and passes them to `parse_time()` for conversion.

### Supported Input Formats

The `parse_time()` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 55-74) accepts multiple human-readable formats:

- `SS` - Raw seconds (e.g., "90")
- `MM:SS` - Minutes and seconds (e.g., "1:30")
- `HH:MM:SS` - Hours, minutes, and seconds (e.g., "1:30:00")

### Conversion to Seconds

Regardless of input format, `parse_time()` returns a float representing the total number of seconds. This standardization enables consistent mathematical comparisons and FFmpeg parameter generation.

## Validating the Temporal Range

Before activating focused mode, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) performs three critical validation checks to ensure the requested segment exists within the video boundaries.

### Boundary Checks

The validation logic enforces temporal logic constraints:

- **Non-negative start**: `--start` must be greater than or equal to 0, or the system raises `SystemExit("--start must be non-negative")` (line 143)
- **Sequential ordering**: `--end` must exceed `--start`, enforced by `SystemExit("--end must be greater than --start")` (line 145)

### Duration Constraints

The system verifies that the start time does not exceed the video's total duration, raising `SystemExit(f"--start {start_sec:.1f}s is past end of video …")` if the requested window begins after the video ends (line 148).

## Activating Focused Extraction Mode

Once validation passes, the pipeline switches from standard to focused processing.

### The Focused Flag Logic

In [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (line 153), the boolean `focused` becomes `True` if either `--start` or `--end` is present. This flag signals downstream functions to adjust their extraction strategy for the abbreviated timeframe.

### Denser Frame Rate Budgeting

When `focused` is `True`, the system calls `auto_fps_focus()` instead of the standard `auto_fps()` (lines 332-335). Implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 41-45), `auto_fps_focus()` calculates a higher target FPS for short clips, ensuring the extracted preview retains visual detail despite the reduced temporal window.

## FFmpeg Integration for Precise Seeking

The calculated `start_sec` and `end_sec` values flow into the low-level extraction pipeline.

### Passing Parameters to Extraction Functions

Core functions including `extract()`, `extract_scene_candidates()`, and `extract_keyframes()` receive the temporal boundaries via `start_seconds` and `end_seconds` parameters. In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 86-90), these arguments become `-ss` (start time) and `-to` (end time) options for FFmpeg.

### Command Construction

FFmpeg performs a fast seek to the specified start position and stops decoding at the end point, avoiding unnecessary processing of frames outside the defined window. This selective decoding reduces computational overhead while maintaining extraction quality.

## Practical Usage Examples

Extract a focused 10-second clip from 00:01:30 to 00:01:40:

```bash
watch.py https://example.com/video.mp4 --start 1:30 --end 1:40

```

Programmatically use the same time-parsing and FPS logic:

```python
from skills.watch.scripts.frames import parse_time, auto_fps_focus

# Manual use of the same helpers

start = parse_time("1:30")          # → 90.0

end   = parse_time("1:40")          # → 100.0

duration = end - start               # 10 seconds

# Denser FPS for the short slice

fps, target = auto_fps_focus(duration, max_frames=100)
print(f"Focused FPS: {fps:.2f}, target frames: {target}")

```

## Summary

- The `--start` and `--end` flags trigger **focused extraction mode** when either parameter is present
- `parse_time()` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) converts `HH:MM:SS`, `MM:SS`, or `SS` formats to float seconds
- Strict validation ensures start ≥ 0, end > start, and start < video duration before processing
- Focused mode switches from `auto_fps()` to `auto_fps_focus()` for higher frame density in short segments
- Temporal boundaries pass through to FFmpeg as `-ss` and `-to` parameters for efficient seeking

## Frequently Asked Questions

### What time formats does claude-video accept?

The `parse_time()` function accepts raw seconds (`90`), minutes:seconds (`1:30`), or hours:minutes:seconds (`1:30:00`). All formats convert to a float value representing total seconds.

### Why does focused extraction use a higher frame rate?

When processing short segments, `auto_fps_focus()` allocates a denser frame budget to ensure the preview retains sufficient detail. This compensates for the reduced temporal window while maintaining analysis quality.

### What happens if --start exceeds the video duration?

The system validates the start time against the video's total duration in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (line 148) and raises a `SystemExit` with the message "`--start {start_sec:.1f}s is past end of video …`" to prevent invalid extraction attempts.

### How does FFmpeg handle the time range internally?

FFmpeg receives the validated start and end times as `-ss` and `-to` arguments. It performs a fast seek to the start position and stops decoding at the end time, processing only frames within the specified window rather than scanning the entire video.