# How to Use --timestamps to Extract Frames at Specific Moments with Claude-Video

> Extract specific frames from videos using the --timestamps flag in Claude-Video. Learn to pinpoint exact moments for frame extraction and enhance your video analysis workflow.

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

---

**Supply the `--timestamps` flag followed by a comma-separated list of timestamps to extract specific frames at absolute positions in the video.**

The `claude-video` repository provides a `watch` skill that extracts video frames using three distinct methods: uniform sampling, scene-change detection, and **timestamp-based extraction**. When you need to capture exact moments rather than uniform samples, the `--timestamps` flag allows you to specify absolute time positions in seconds, `MM:SS`, or `HH:MM:SS` format.

## How Timestamp-Based Extraction Works

The timestamp extraction workflow follows a four-stage pipeline defined in the `skills/watch/scripts/` directory. When you invoke the `watch` command with the `--timestamps` flag, the system processes your input through dedicated parsing functions before executing targeted FFmpeg commands.

### CLI Argument Parsing

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the command-line interface defines the `--timestamps` option at lines 42-45. This argument expects a comma-separated string of absolute timestamps. The implementation stores the raw string for downstream processing, ensuring the value is passed to the frame extraction engine before any audio-only optimizations are applied.

When timestamps are present, the `--detail` mode automatically switches to video-only processing, bypassing audio-only optimizations because timestamp extraction requires the video stream.

### Timestamp Parsing and Validation

The raw timestamp string is handed to `frames.parse_timestamps` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 295-311). This helper function:

- Tolerates whitespace and mixed format inputs (seconds, minutes:seconds, hours:minutes:seconds)
- Removes duplicate timestamps automatically
- Returns a sorted list of floats representing seconds
- Raises a `ValueError` for invalid entries

The parser handles normalization internally, converting timecode strings into absolute seconds for consistent processing.

### Frame Extraction with FFmpeg

The parsed list of seconds is passed to `frames.extract_at_timestamps` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 324-388). For each timestamp, the function executes an FFmpeg command using `-ss` for precise seeking followed by `-vframes 1` to capture a single frame. This approach ensures accurate frame extraction without processing the entire video sequentially.

The function returns a tuple containing:
- A list of generated frame file paths
- A metadata dictionary with `"engine": "timestamps"` and the requested timestamp values

### Output Integration

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 178-186), the extracted cue frames are merged into the overall result set. The detail view displays a count of extracted frames, labeling them as originating from transcript-flagged timestamps when presenting the final output to the user.

## Command-Line Usage Examples

Use the `--timestamps` flag with the `watch` command to extract frames at specific moments. Separate multiple timestamps with commas, and optionally combine with `--detail` for balanced analysis.

Extract frames at 1 second, 3 seconds, and 1 minute 2 seconds:

```bash
watch https://example.com/video.mp4 --timestamps "1,3,1:02"

```

Combine timestamp extraction with detail view:

```bash
watch https://example.com/video.mp4 --detail balanced --timestamps "0:30,2:15,5"

```

The command output includes a summary line indicating the count of cue frames extracted:

```

Cue frames: 3 at transcript-flagged timestamps

```

## Programmatic Python API

You can also invoke timestamp extraction directly from Python code using the internal frame utilities.

Import the parsing and extraction functions from the frames module:

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

# Parse a raw timestamp string with mixed formats

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

# Extract frames at the parsed timestamps

video_path = "/tmp/video.mp4"
out_dir    = "/tmp/frames"
frames, meta = extract_at_timestamps(video_path, out_dir, seconds)

print(frames)  # ['/tmp/frames/f001.jpg', '/tmp/frames/f002.jpg', ...]

print(meta)    # {'engine': 'timestamps', 'requested': [30.0, 65.0, 90.0]}

```

The `extract_at_timestamps` function handles directory creation and file naming automatically, returning absolute paths to the generated JPEG files.

## Input Formats and Edge Cases

The timestamp parser accepts flexible input formats but enforces strict validation rules. Whitespace is automatically trimmed, and duplicate values are removed during parsing.

**Valid input handling:**

- `" 90 , 30, 30 "` → `[30.0, 90.0]` (whitespace trimmed, duplicates removed, sorted)
- `"30,1:05,90"` → `[30.0, 65.0, 90.0]` (mixed formats normalized to seconds)

**Invalid input handling:**

- `""` or `" , ,"` → Returns empty list `[]` (no frames extracted)
- `"4:bad"` → Raises `ValueError` with clear error message about invalid format

Always use absolute timestamps from the start of the video. Relative offsets or durations are not supported by the current implementation in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

## Summary

- The `--timestamps` flag in `claude-video` enables precise frame extraction at absolute time positions using the `watch` skill
- Input parsing is handled by `frames.parse_timestamps` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), supporting seconds, `MM:SS`, and `HH:MM:SS` formats
- Frame extraction uses FFmpeg with `-ss` seeking and `-vframes 1` for each timestamp via `frames.extract_at_timestamps`
- The presence of timestamps forces video-only processing mode, disabling audio-only optimizations
- Duplicate timestamps are automatically deduplicated, and invalid formats raise `ValueError` exceptions

## Frequently Asked Questions

### What timestamp formats does the --timestamps flag accept?

The flag accepts comma-separated values in three formats: plain seconds (e.g., `90`), minutes:seconds (e.g., `1:30`), or hours:minutes:seconds (e.g., `1:30:45`). The `parse_timestamps` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) normalizes all formats to floating-point seconds for internal processing.

### How does timestamp extraction differ from uniform sampling?

Uniform sampling extracts frames at regular intervals across the entire video duration, while timestamp extraction captures specific moments you define. According to the source code in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), timestamp extraction uses individual FFmpeg seek commands for each position, whereas uniform sampling processes the video stream sequentially.

### Can I combine --timestamps with other extraction methods?

When you specify `--timestamps`, the system adds those specific frames to the overall result set alongside any other configured extractions. However, the `--detail` mode automatically switches to video-only processing when timestamps are present, as implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), ensuring the video stream is available for precise seeking.

### What happens if I provide an invalid timestamp format?

The `parse_timestamps` function raises a `ValueError` with a descriptive error message. Inputs like `"4:bad"` or malformed timecodes will halt execution before any FFmpeg commands are executed. Empty strings or strings containing only commas and whitespace return an empty list and result in no frame extraction.