# How the --timestamps Argument Parses and Validates Timestamp Values in Claude-Video

> Learn how claude-video's --timestamps argument parses, validates, and sorts time values for accurate frame extraction. Understand flexible time formats and focus window checks.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-05

---

**The `--timestamps` flag splits comma-separated strings, parses each token into total seconds using flexible time formats, deduplicates and sorts the values, then validates them against the video's focus window during frame extraction.**

The `claude-video` repository provides precise frame extraction through its `--timestamps` argument, which converts human-readable time strings into exact video positions. Understanding how timestamps are parsed and validated ensures you provide valid inputs and interpret extraction metadata correctly. The implementation resides primarily in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), with the CLI entry point handling argument ingestion in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

## Input Tokenization and Splitting

The parsing pipeline begins in `parse_timestamps` at lines 295-304 of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). The raw string supplied after `--timestamps` is split on commas using `value.split(",")`. The function filters out blank tokens automatically, allowing flexible input spacing such as `"30, 1:05, 90"` or `"30,1:05,90"`.

## Time Format Parsing

Each non-empty token passes to `parse_time` (lines 55-74), which recognizes **three distinct time formats** and converts them to float values representing total seconds:

- **`SS`** – Raw seconds (e.g., `30` becomes `30.0`)
- **`MM:SS`** – Minutes and seconds (e.g., `1:05` becomes `65.0`)
- **`HH:MM:SS`** – Hours, minutes, and seconds, optionally with fractional seconds (e.g., `1:30:45.5` becomes `5445.5`)

If `parse_time` encounters an unrecognized pattern, the program aborts immediately with a descriptive error message indicating the invalid token and expected formats.

## Deduplication and Ordering

After successful parsing, `parse_timestamps` collects the float values into a list and converts them to a `set` to remove duplicate entries. The unique timestamps are then sorted in ascending order before returning to the caller. This ensures that frame extraction requests are processed chronologically and that redundant frames are eliminated before the expensive video I/O operations begin.

## Runtime Validation Against Focus Windows

The parsed timestamps undergo final validation in `extract_at_timestamps` (lines 324-389). This function:

1. **Rounds** each timestamp to two decimal places for precise frame seeking
2. **Filters** timestamps against the user-specified focus window (`start_seconds` and `end_seconds`), dropping any values outside the bounds
3. **Caps** the total frame count when exceeding limits, sampling evenly across the requested timestamps

The function returns metadata reporting the number of candidate timestamps, how many were selected for extraction, and how many were dropped due to window constraints.

## Usage Examples

Pass timestamps directly via the CLI using comma-separated values:

```bash
python -m skills.watch.scripts.watch https://example.com/video.mp4 --detail transcript --timestamps "30,1:05,90"

```

Import and use the parsing functions directly in Python:

```python
from skills.watch.scripts.frames import parse_timestamps

# Flexible spacing and formats are automatically handled

raw = "30, 1:05,   90"
seconds = parse_timestamps(raw)  # → [30.0, 65.0, 90.0]

print(seconds)

```

Handle parsing errors gracefully when encountering malformed input:

```python
try:
    parse_timestamps("4:bad")
except SystemExit as e:
    print(e)  # Cannot parse time value: '4:bad' (expected SS, MM:SS, or HH:MM:SS)

```

## Summary

- The `--timestamps` argument splits input on commas and ignores blank tokens in `parse_timestamps`.
- `parse_time` supports **SS**, **MM:SS**, and **HH:MM:SS** formats, converting all values to float seconds.
- Duplicate timestamps are removed via `set` conversion, and results are sorted ascending before extraction.
- Runtime validation in `extract_at_timestamps` rounds values, filters against focus windows, and handles frame caps.
- Parsing errors trigger immediate program termination with clear messages indicating the invalid token.

## Frequently Asked Questions

### What time formats does the --timestamps argument accept?

The argument accepts three formats: raw seconds (`SS`), minutes and seconds (`MM:SS`), and hours with minutes and seconds (`HH:MM:SS`). Fractional seconds are supported in the `HH:MM:SS` format. All formats can be mixed within a single comma-separated list.

### How does claude-video handle duplicate timestamp values?

Duplicate values are automatically deduplicated using a `set` conversion inside `parse_timestamps` before sorting. If you request `"30,30,60"`, the extraction engine receives `[30.0, 60.0]` and processes each unique timestamp only once.

### What happens if a timestamp falls outside the video's focus window?

The `extract_at_timestamps` function filters out any timestamps that exceed the `start_seconds` or `end_seconds` boundaries specified by the user. These dropped timestamps are reported in the extraction metadata, allowing you to verify which requested frames were skipped due to window constraints.

### Where are the timestamp parsing tests located?

The test suite resides in [`tests/test_timestamps.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_timestamps.py). This file validates `parse_timestamps` and `parse_time` behavior across edge cases including malformed inputs, mixed formats, and boundary conditions.