# How Timestamps Are Extracted in Claude Video Using --timestamps

> Discover how Claude Video extracts timestamps using ffmpeg's -ss seek and showinfo filter. Learn to precisely capture and merge cue frames for your video projects.

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

---

**Claude Video extracts timestamp-specific frames by parsing user input into seconds, using ffmpeg's `-ss` seek and `showinfo` filter to capture precise frames, then merging these cue frames into the final output.**

The `--timestamps` option in Claude Video enables precise frame extraction at user-specified moments in a video. This feature, implemented across [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) and [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), supports flexible time formats and guarantees accurate frame capture through ffmpeg's built-in timing verification.

---

## Parsing the --timestamps Argument

The first step converts raw user input into a clean list of seconds. In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the `parse_timestamps` function handles this transformation.

### Input Processing

The function splits the comma-separated string, trims whitespace, removes empty entries, and deduplicates values:

```python

# Example input: "30,1:05,90" or "0:1:05, 2:30 , 90"

```

### Time Format Support

Each entry may be expressed in three formats:

- **Seconds only:** `30` → 30.0 seconds
- **Minutes:Seconds:** `1:05` → 65.0 seconds  
- **Hours:Minutes:Seconds:** `0:1:05` → 65.0 seconds

### Output Normalization

All values are converted to **floating-point seconds**, sorted ascending, and returned as a list. See `parse_timestamps` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 295-324).

---

## Extracting Frames at Each Timestamp

The parsed timestamps feed into `extract_at_timestamps`, also in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 324-384). This function performs the actual frame capture.

### FFmpeg Seek and Capture

For every timestamp, Claude Video invokes ffmpeg with:

```bash
ffmpeg -ss <timestamp> -i <input> -vframes 1 -vf showinfo <output>

```

- **`-ss <timestamp>`** seeks to the specified position
- **`-vframes 1`** extracts exactly one frame
- **`-vf showinfo`** enables frame metadata logging

### Precision Verification with showinfo

The `showinfo` filter outputs detailed timing data. Claude Video applies the `SHOWINFO_TS_RE` regex to this log, extracting the **actual presentation timestamp** ffmpeg used:

```python
timestamps = [round(offset + float(m.group(1)), 2) ...]

```

This captures the precise moment of extraction, accounting for any seek discrepancies.

### Return Structure

The function returns:

1. A list of generated frame file paths
2. A metadata dictionary with `"engine": "timestamps"` identifying this extraction path

---

## Merging Cue Frames into the Output

Back in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 81-182), the orchestration logic integrates timestamp frames into the final result.

### Transcript Integration

If the user requested `--detail transcript`, cue timestamps flag relevant transcript segments. Otherwise, the frames append as additional visual data.

### CLI Feedback

The interface reports extraction success:

```

Cue frames: 3 at transcript-flagged timestamps

```

---

## CLI Usage Examples

```bash

# Basic: extract frames at 30s, 1m5s, and 90s

claude-video /watch https://example.com/video.mp4 --timestamps "30,1:05,90"

# With transcript: timestamps become cue points in the text

claude-video /watch video.mp4 --detail transcript --timestamps "30,90"

# Mixed format with spaces

claude-video /watch video.mp4 --timestamps "0:2:30, 90, 1:15"

```

---

## Key Implementation Files

| File | Function | Purpose |
|------|----------|---------|
| [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) | `parse_timestamps` | Converts raw `--timestamps` input to sorted seconds |
| [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) | `extract_at_timestamps` | Uses ffmpeg `-ss` and `showinfo` for precise frame capture |
| [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) | Orchestration logic | Merges cue frames, handles transcript integration, reports results |

---

## Summary

- **`parse_timestamps`** handles flexible time formats (seconds, M:SS, H:MM:SS) and returns sorted float values
- **`extract_at_timestamps`** leverages ffmpeg's `-ss` seek and `showinfo` filter for verified, single-frame extraction
- **[`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)** orchestrates the workflow, merging cue frames with transcript or standard output
- The `--timestamps` engine is tagged in metadata as `"engine": "timestamps"` for traceability

---

## Frequently Asked Questions

### What timestamp formats does Claude Video accept?

Claude Video accepts three formats: raw seconds (`90`), minutes and seconds (`1:30`), and full clock time (`0:1:30`). All formats are converted to floating-point seconds internally. Commas separate multiple timestamps.

### How does Claude Video ensure frame extraction accuracy?

The tool uses ffmpeg's `showinfo` video filter during extraction. This outputs the actual presentation timestamp of the captured frame, which Claude Video parses with `SHOWINFO_TS_RE` to verify precision. The returned timestamp accounts for any seek offset adjustments.

### Can --timestamps be combined with other extraction modes?

Yes. When paired with `--detail transcript`, timestamp positions become cue points that flag relevant transcript segments. Otherwise, the extracted frames append to the standard frame collection. The CLI reports the count of cue frames separately in the output.

### Where is the timestamp processing logic located?

All timestamp-specific code resides in two files: [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) contains `parse_timestamps` (lines 295-324) and `extract_at_timestamps` (lines 324-384), while [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 81-182) orchestrates their integration into the overall workflow according to the bradautomates/claude-video source code.