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

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, the function extract_at_timestamps establishes the active focus window by calculating lower and upper bounds from the CLI arguments:

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:

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:

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

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

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

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

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

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

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. 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. 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.

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