# What Happens When --timestamps Fall Outside the --start/--end Range in claude-video

> Discover what happens when --timestamps fall outside the --start/--end range in claude-video. Out-of-range timestamps are silently dropped and recorded in metadata.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: internals
- Published: 2026-07-14

---

**Out-of-range timestamps are silently dropped from frame extraction and excluded from the ffmpeg invocation, while the count of discarded coordinates is recorded in the `dropped_out_of_window` metadata field.**

The claude-video tool extracts cue frames from video sources based on user-supplied temporal coordinates. When you specify a focus range using `--start` and `--end` parameters alongside specific `--timestamps` values, the application reconciles these inputs according to strict filtering logic implemented in the frame extraction engine.

## How the Focus Window Filters Timestamps

In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the function **`extract_at_timestamps`** establishes the active focus window by calculating lower and upper bounds from the CLI arguments:

```python
lo = start_seconds or 0.0
hi = end_seconds if end_seconds is not None else float("inf")

```

This creates a closed interval `[lo, hi]` representing the valid extraction range. The function then processes the requested timestamps, rounding them to two decimal places, and filters against this window:

```python
requested = sorted(set(round(float(t), 2) for t in timestamps))
in_window = [t for t in requested if lo <= t <= hi]      # ← drop‑out‑of‑window

dropped = len(requested) - len(in_window)               # ← count dropped timestamps

```

Timestamps failing the `lo <= t <= hi` condition are excluded from the `in_window` list. Only the surviving timestamps proceed to ffmpeg for frame generation.

## Metadata Tracking for Dropped Timestamps

When timestamps are discarded, the resulting metadata explicitly records this event. The dictionary returned by the extraction engine includes specific fields quantifying the filtering operation:

```python
meta = {
    "engine": "timestamps",
    "candidate_count": len(requested),
    "selected_count": len(out),
    "dropped_out_of_window": dropped,   # ← number of out‑of‑range timestamps

    "fallback": False,
}

```

The **`dropped_out_of_window`** field provides transparency by indicating exactly how many requested coordinates fell outside the permissible range, while `selected_count` reflects how many actually triggered frame extraction.

## Command-Line Behavior Examples

The following examples demonstrate how claude-video handles out-of-range timestamps against a 10-second sample video.

### Partial Overlap: One Timestamp Inside, One Outside

```bash
python -m skills.watch.scripts.watch sample.mp4 \
    --start 00:02 \
    --end   00:08 \
    --detail balanced \
    --timestamps 1,5

```

The timestamp at 1 second falls before the 2-second start boundary. The tool generates only the frame at 5 seconds, reporting `dropped_out_of_window: 1` in the metadata.

### Complete Exclusion: All Timestamps Outside Range

```bash
python -m skills.watch.scripts.watch sample.mp4 \
    --start 00:02 \
    --end   00:05 \
    --detail balanced \
    --timestamps 0,6,9

```

All three requested timestamps lie outside the `[2, 5]` focus window. The extraction produces zero cue frames, returning metadata with `candidate_count: 3`, `selected_count: 0`, and `dropped_out_of_window: 3`.

### Unbounded Range: Default Behavior

```bash
python -m skills.watch.scripts.watch sample.mp4 \
    --detail balanced \
    --timestamps 1,5,9

```

Without explicit `--start` or `--end` arguments, the window defaults to `[0, ∞)`. Consequently, all timestamps remain valid and generate corresponding frames.

## Source Code Architecture

The timestamp filtering logic spans multiple files in the **bradautomates/claude-video** repository.

### [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)

This file contains the **`extract_at_timestamps`** function implementing the core filtering logic that drops out-of-range timestamps before invoking ffmpeg. It defines the boundary calculations and the list comprehension that produces the `in_window` collection.

### [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)

The CLI entry point parses `--start`, `--end`, and `--timestamps` arguments, then delegates to `extract_at_timestamps` to orchestrate the cue-frame extraction pipeline.

### [`tests/test_timestamps.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_timestamps.py)

The pytest suite validates the `parse_timestamps` and `extract_at_timestamps` functions, specifically verifying the behavior of dropping timestamps outside the defined focus window.

## Summary

- Out-of-range timestamps are filtered in `extract_at_timestamps` using a closed interval `[lo, hi]` defined by `--start` and `--end` parameters.
- The **`dropped_out_of_window`** metadata field tracks exactly how many coordinates were excluded from processing.
- When all timestamps fall outside the window, the extraction returns zero frames with `selected_count: 0` and no ffmpeg frame generation occurs.
- Valid timestamps within the range proceed normally to ffmpeg for frame extraction without warning or error messages.

## Frequently Asked Questions

### How does claude-video handle timestamps that occur before the --start time?

Timestamps occurring before the `--start` value are treated as out-of-range and filtered out during the extraction preparation phase in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). They increment the `dropped_out_of_window` counter in the returned metadata but do not interrupt the processing of valid timestamps that fall within the window.

### What metadata indicates that timestamps were dropped in claude-video?

The extraction metadata includes a field named **`dropped_out_of_window`**, which contains an integer representing the count of requested timestamps that fell outside the `[--start, --end]` interval. This value appears alongside `candidate_count` (total requested) and `selected_count` (successfully processed) fields.

### Does claude-video produce an error when all timestamps are outside the focus range?

No error is raised. The tool completes successfully but returns `selected_count: 0` and `dropped_out_of_window` equal to the total number of requested timestamps. No cue frames are generated, and the pipeline continues without ffmpeg frame extraction calls.

### Where is the timestamp filtering logic implemented in the claude-video source code?

The filtering logic resides in the **`extract_at_timestamps`** function within [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This function calculates the valid window bounds, filters the requested timestamp list using the `lo <= t <= hi` condition, and prepares the metadata dictionary before invoking ffmpeg.