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

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, with the CLI entry point handling argument ingestion in 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. 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:

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:

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:

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. This file validates parse_timestamps and parse_time behavior across edge cases including malformed inputs, mixed formats, and boundary conditions.

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