# How the Timestamps Feature Extracts Specific Frames from Transcript Cues in Claude Video

> Leverage the timestamps feature in Claude Video to extract specific frames from transcript cues. Learn how this tool aligns visual content with metadata using ffmpeg.

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

---

**The timestamps feature in bradautomates/claude-video converts user-supplied time strings into normalized seconds, then leverages ffmpeg to extract single frames at those exact positions, aligning visual content with transcript metadata.**

The timestamps functionality in the `bradautomates/claude-video` repository enables precise frame extraction at specified moments, creating visual references that correspond directly to transcript cues. This feature bridges temporal metadata with visual content by converting human-readable time formats into exact video frame captures. Understanding how the timestamps feature extracts specific frames from transcript cues reveals the robust parsing and ffmpeg integration implemented in the watch skill.

## Parsing Timestamp Input with parse_timestamps

The extraction workflow begins in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) with the `parse_timestamps` function (lines 295-315). This utility accepts a comma-separated string of time values and normalizes them into a sorted list of floating-point seconds.

The function signature explicitly handles optional string inputs:

```python
def parse_timestamps(value: str | None) -> list[float]:

```

### Supported Time Formats

The parser recognizes three distinct time formats and converts them to total seconds:

- **Plain seconds**: `30` or `120.5`
- **Minute-second notation**: `1:05` or `10:30`
- **Hour-minute-second notation**: `00:01:05` or `1:30:45`

For segments containing colons, the implementation reverses the split components and calculates total seconds using base-60 arithmetic:

```python
if ":" in part:
    secs = sum(int(x) * 60 ** i for i, x in enumerate(reversed(part.split(":"))))
    seconds.append(float(secs))
else:
    seconds.append(float(part))

```

### Normalization and Deduplication

After converting all valid segments, the function rounds each value to two decimal places, removes duplicates via `set()`, and returns a sorted list. This ensures that `1:05` and `65` resolve to the same timestamp, and that the extraction process receives chronologically ordered timestamps regardless of input order.

```python
return sorted(set(round(s, 2) for s in seconds))

```

## Extracting Frames at Precise Timestamps

Once normalized, the timestamps feed into `extract_at_timestamps`, also located in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 324-352). This function orchestrates the actual frame capture by constructing and executing ffmpeg commands for each time point.

### ffmpeg Command Construction

For each timestamp in the sorted list, the function builds a subprocess call that seeks to the specific time position and extracts a single frame:

```python
cmd = [
    "ffmpeg",
    "-hide_banner",
    "-loglevel", "error",
    "-ss", str(ts),
    "-i", video_path,
    "-frames:v", "1",
    "-q:v", "2",
    str(out_path),
]
subprocess.run(cmd, check=True)

```

The `-ss` parameter performs the seek operation, while `-frames:v 1` limits output to a single video frame. The `-q:v 2` flag sets high-quality JPEG output. Each frame saves to the specified output directory with a filename matching the timestamp (e.g., `65.00.jpg`).

### Output Handling and Metadata

The function returns a tuple containing a list of `Path` objects pointing to the extracted frames and a metadata dictionary tagged with `"engine": "timestamps"`:

```python
return frames, {"engine": "timestamps"}

```

This metadata tag allows the calling code in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) to identify the extraction method used for the generated frames.

## Integrating Cue Frames into the Watch Pipeline

The CLI entry point in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) coordinates the entire workflow. When the `--timestamps` flag receives a non-empty value, the script invokes `parse_timestamps` to validate the input, then passes the resulting list to `extract_at_timestamps`.

After extraction, the script appends the cue frames to the detail report (lines 300-310), indicating the count of frames captured at transcript-flagged timestamps:

```python
if cue_frames:
    detail.append(f"- **Cue frames:** {len(cue_frames)} at transcript-flagged timestamps")

```

These frames appear alongside other extraction methods depending on the selected `--detail` mode.

### Usage Examples

Run the skill from the command line to extract frames at specific seconds:

```bash
watch.py https://youtu.be/abc123 --detail balanced --timestamps "1,3"

```

Use the functions programmatically in Python:

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

ts = parse_timestamps("1,3")
frames, meta = extract_at_timestamps(
    video_path="my_clip.mp4",
    out_dir="frames/",
    timestamps=ts,
)

print(frames)            # [PosixPath('frames/1.00.jpg'), PosixPath('frames/3.00.jpg')]

print(meta["engine"])    # "timestamps"

```

## Summary

- The `parse_timestamps` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) converts human-readable time strings (including HH:MM:SS and MM:SS formats) into normalized floating-point seconds, deduplicating and sorting the results.
- The `extract_at_timestamps` function uses ffmpeg with the `-ss` seek parameter and `-frames:v 1` to capture single high-quality JPEG frames at each specified position.
- Extracted frames are tagged with metadata identifying the `"timestamps"` engine and integrated into the final detail report by [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).
- The system handles duplicate timestamps and various input formats automatically, ensuring robust alignment between transcript cues and visual frames.

## Frequently Asked Questions

### What time formats does the timestamps feature support?

The `parse_timestamps` function accepts plain seconds (e.g., `30`), minute-second notation (e.g., `1:05`), and full hour-minute-second notation (e.g., `00:01:05`). All formats are normalized to floating-point seconds and rounded to two decimal places for consistency.

### How does the system handle duplicate or out-of-order timestamps?

The implementation automatically deduplicates timestamps using `set()` and sorts them chronologically before extraction. This ensures that ffmpeg receives an optimized sequence regardless of how the user ordered the input string, preventing redundant frame extraction.

### What ffmpeg parameters are used to extract frames at specific timestamps?

The `extract_at_timestamps` function constructs commands using `-ss <timestamp>` to seek to the position, `-frames:v 1` to capture a single frame, and `-q:v 2` for high-quality JPEG output. The `-hide_banner` and `-loglevel error` flags minimize console verbosity during processing.

### How are extracted timestamp frames integrated with other frame extraction methods?

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script merges timestamp-extracted frames into the detail report alongside frames from other engines. The final output displays the count of cue frames and includes them in the visual analysis based on the selected detail level, allowing direct visual reference for transcript analysis.