# How to Use Timestamps to Extract Specific Moments from Videos in Claude Video

> Learn how to use timestamps to extract specific moments from videos in Claude Video. Supply timestamps in seconds, minutes:seconds, or hours:minutes:seconds format for precise frame extraction.

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

---

**Claude Video's watch skill allows you to extract exact frames from any video by supplying a comma-separated list of timestamps in seconds, minutes:seconds, or hours:minutes:seconds format.**

Claude Video is an open-source automation framework for video analysis that includes a powerful **watch** skill for intelligent frame extraction. Learning how to use timestamps to extract specific moments from videos in Claude Video enables precise content analysis without processing entire footage sequences. The system normalizes multiple time formats automatically, removes duplicate entries, and generates high-quality JPEG frames named `cue_XXXX.jpg` at exactly the requested temporal positions.

## Timestamp-Based Extraction Pipeline

The **watch** skill implements a four-stage pipeline for timestamp-driven frame extraction according to the bradautomates/claude-video source code. Understanding these stages helps you optimize extraction workflows and troubleshoot timing issues.

### CLI Argument Parsing

The extraction process begins in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), where the `--timestamps` flag is defined at lines 42-45. When you supply this parameter, the tool immediately triggers a full video download rather than audio-only mode, ensuring `ffmpeg` can seek to exact byte positions for frame accuracy.

### Timestamp Normalization

Raw timestamp strings undergo conversion in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) through the `parse_timestamps` function (lines 295-310). This utility accepts comma-separated values and normalizes them to floating-point seconds.

The parser supports three distinct input formats:

- **Seconds only**: `45` converts to 45.0 seconds
- **Minutes and seconds**: `2:30` converts to 150.0 seconds  
- **Hours, minutes, seconds**: `00:01:15` converts to 75.0 seconds

`parse_timestamps` automatically sorts the final list in ascending order and removes duplicates, guaranteeing deterministic frame extraction regardless of input order.

### Frame Extraction at Exact Moments

The `extract_at_timestamps` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 324-390) handles the actual rendering. This function:

1. Validates each timestamp against optional start/end window constraints
2. Applies optional frame caps via the `max_frames` parameter
3. Invokes `ffmpeg` once per timestamp to extract a single JPEG frame
4. Writes output files as `cue_XXXX.jpg` in the designated working directory

Each extraction includes metadata tagging with `"reason": "transcript-cue"` to distinguish timestamp-driven frames from automatically selected detail frames.

## Command-Line Usage

Extract specific moments from YouTube videos or local files using the `--timestamps` flag with the `watch` command. The flag accepts any combination of the supported time formats.

```bash

# Extract frames at 1 second, 3 minutes 15 seconds, and 2 minutes 30 seconds

watch https://www.youtube.com/watch?v=abc123 \
  --detail balanced \
  --timestamps 1,3:15,00:02:30

```

The command outputs a summary showing resolved timestamps:

```

[watch] Cue frames: 3 at transcript-flagged timestamps
- frame 0 (t=00:00:01.00, reason=transcript-cue)
- frame 1 (t=00:03:15.00, reason=transcript-cue)
- frame 2 (t=00:02:30.00, reason=transcript-cue)

```

All `cue_XXXX.jpg` files appear alongside standard detail frames in the temporary work directory, ready for analysis or further processing.

## Python API Implementation

For programmatic workflows, import the frame extraction utilities directly from the `frames` module.

```python
from pathlib import Path
from skills.watch.scripts import frames

# Parse timestamp string into normalized seconds

timestamps = frames.parse_timestamps("45,2:30,00:01:15")

# Result: [45.0, 75.0, 90.0] (automatically sorted)

# Extract frames with custom resolution

video_path = "/path/to/video.mp4"
output_dir = Path("/tmp/extraction")

extracted, metadata = frames.extract_at_timestamps(
    video_path=video_path,
    out_dir=output_dir,
    timestamps=timestamps,
    resolution=512,      # JPEG width in pixels, defaults to 512

    max_frames=None,     # Set to integer to limit extracted frames

)

```

The function returns a tuple containing:

- **extracted**: List of dictionaries with `index`, `timestamp_seconds`, `path`, and `reason` keys
- **metadata**: Dictionary with `engine: "timestamps"`, `candidate_count`, `selected_count`, and `dropped_out_of_window` statistics

## Output Structure and Metadata

Each extracted frame generates a JPEG file following the naming convention `cue_XXXX.jpg`, where `XXXX` represents a zero-padded index. The resolution parameter controls the output width while maintaining aspect ratio, defaulting to 512 pixels as implemented in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py).

The metadata dictionary returned by `extract_at_timestamps` provides extraction transparency:

```python
{
    "engine": "timestamps",
    "candidate_count": 3,
    "selected_count": 3,
    "dropped_out_of_window": 0,
    "fallback": False
}

```

This structure reports how many timestamps were requested, how many survived window filtering, and whether any were dropped due to temporal constraints outside your specified range.

## Core Implementation Files

According to the bradautomates/claude-video source code, timestamp functionality resides in these key locations:

- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: CLI entry point that parses `--timestamps` arguments and orchestrates the full video download workflow
- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)**: Contains `parse_timestamps` (lines 295-310) and `extract_at_timestamps` (lines 324-390) implementation
- **[`tests/test_timestamps.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_timestamps.py)**: Unit tests validating timestamp parsing edge cases and format conversions
- **[`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py)**: Integration tests covering end-to-end watch command execution with timestamp parameters

## Summary

- **Claude Video** extracts exact video moments using the `watch` skill with the `--timestamps` CLI flag, which triggers full video downloads to ensure frame accuracy.
- **`parse_timestamps`** in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) normalizes `SS`, `MM:SS`, and `HH:MM:SS` formats into sorted floating-point seconds while removing duplicates.
- **`extract_at_timestamps`** generates `cue_XXXX.jpg` files by invoking `ffmpeg` once per timestamp, with optional resolution and frame count constraints.
- The **metadata** system tracks extraction statistics including candidate counts and window filtering results through a standardized dictionary format.

## Frequently Asked Questions

### What timestamp formats does Claude Video accept?

Claude Video accepts three timestamp formats through the `parse_timestamps` function: seconds only (e.g., `45`), minutes and seconds separated by a colon (e.g., `2:30`), and full hours:minutes:seconds notation (e.g., `00:01:15`). All formats are automatically converted to floating-point seconds and sorted before extraction.

### Why does using timestamps force a full video download?

When you specify the `--timestamps` flag, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) disables audio-only mode and downloads the complete video file. This ensures `ffmpeg` can perform accurate byte-level seeking to extract frames at exact temporal positions, which is impossible with audio-only streams or segmented downloads.

### How are the extracted frame files named and organized?

The `extract_at_timestamps` function saves frames as `cue_XXXX.jpg` in the specified output directory, where `XXXX` is a zero-padded index corresponding to the timestamp's position in the sorted list. These files appear alongside any standard detail frames in the temporary work directory.

### Can I limit how many timestamp frames get extracted?

Yes. When calling `extract_at_timestamps` programmatically, set the `max_frames` parameter to an integer value to cap the number of extracted frames. The function processes timestamps in sorted order and stops once reaching the limit, dropping subsequent timestamps from the extraction queue.