# How to Capture Transcript-Cue Frames Using the `--timestamps` Option in Claude Video

> Easily capture transcript cue frames with the --timestamps option in Claude Video. Pinpoint exact moments for detailed visual analysis, going beyond the default frame budget.

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

---

**The `--timestamps` flag in Claude Video's `/watch` skill extracts frames at exact timestamps you specify, ensuring critical moments are captured alongside the automatic frame budget for precise visual analysis.**

The `bradautomates/claude-video` repository provides a `/watch` skill that enables Claude to analyze video content from YouTube, TikTok, or local files using both visual frames and audio transcripts. When you need to guarantee that specific moments—such as a slide change at 2:15 or a UI transition at 0:45—are included in the analysis, the **transcript-cue frames** feature activated by the `--timestamps` option ensures those exact timestamps are captured regardless of the automatic frame sampling.

## How the `--timestamps` Option Works

The `--timestamps` option operates as an overlay to the standard frame extraction pipeline defined in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). While the base system automatically calculates frame extraction rates based on your selected `--detail` mode, timestamp-cue frames are forcibly injected into the final frame set.

### Command Parsing and Validation

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the entry point parses the video URL or path, the optional analysis question, and flags including `--timestamps`. The timestamp values are validated to support `SS`, `MM:SS`, or `HH:MM:SS` formats.

### Base Frame Generation vs. Timestamp Injection

The system first generates a budgeted frame set via [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), which runs `ffmpeg` with an automatically computed FPS (or user-provided `--fps`) to produce approximately 100 frames in `balanced` mode. After this base extraction, the timestamps supplied via `--timestamps` trigger separate `ffmpeg` calls that capture single JPEG frames at each exact moment.

These frames are **added to the frame list** and counted toward the overall frame budget, but they are guaranteed to appear even if the automatic budget would have skipped that region.

### Transcript Alignment

The [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) module gathers native captions via `yt-dlp` or falls back to Whisper via [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py). The resulting transcript includes timestamps that align with the extracted frames, allowing Claude to correlate visual cues with specific audio segments.

## Implementation Details in the Source Code

The timestamp extraction logic resides primarily in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). After the base frame extraction completes, the script iterates through the comma-separated timestamp values provided to the `--timestamps` argument. For each timestamp, it constructs a targeted `ffmpeg` command to seek to the specific timecode and extract a single frame.

The [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) coordinator manages the workflow sequence: downloading via [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) (a thin wrapper around `yt-dlp`), extracting frames, transcribing audio, and formatting the output. The final presentation includes lines such as `frame_001.jpg t=00:01:23` followed by the timestamped transcript, which Claude reads to generate answers.

## Practical Usage Examples

You can combine the `--timestamps` option with other flags like `--detail` and `--max-frames` to optimize token usage while ensuring critical moments are captured.

Extract frames at specific timestamps for targeted analysis:

```bash
/watch https://youtu.be/dQw4w9WgXcQ "what does the presenter say at 1:23?" \
  --timestamps 1:23,2:45,03:10

```

Combine with a custom detail mode to reduce the base frame budget while keeping cue frames:

```bash
/watch video.mp4 "explain the UI change at 0:45" \
  --detail efficient \
  --timestamps 0:45

```

Limit the overall frame budget while preserving specific cue frames:

```bash
/watch https://vimeo.com/12345 "summarize the key points" \
  --max-frames 30 \
  --timestamps 00:15,00:30

```

In each case, the output contains lines such as:

```

frame_001.jpg t=00:01:23
frame_002.jpg t=00:02:45
...

```

followed by a timestamped transcript.

## Benefits of Transcript-Cue Frames

Using the `--timestamps` option provides specific advantages for video analysis:

- **Focused analysis**: You guarantee that pivotal moments are not missed by the automatic frame-budget logic, which might otherwise skip sections based on FPS calculations.
- **Efficient token use**: Only the requested frames are added; the remainder of the frame budget stays intact for broader context.
- **Consistent timing**: Timestamps displayed in the transcript make it easy for Claude to correlate audio and visual cues precisely.

## Summary

- The `--timestamps` option in `bradautomates/claude-video` extracts **transcript-cue frames** at exact timecodes you specify, ensuring critical visual moments are included in Claude's analysis.
- Timestamp formats supported include `SS`, `MM:SS`, and `HH:MM:SS`, parsed by [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) and processed by [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).
- These frames are injected into the standard frame set via separate `ffmpeg` calls and count toward the overall frame budget while being guaranteed to appear in the output.
- The feature works alongside `--detail` modes and `--max-frames` limits, allowing you to optimize token usage while preserving specific moments.
- Output format includes timestamp annotations (e.g., `frame_001.jpg t=00:01:23`) that align with the transcript generated by [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py).

## Frequently Asked Questions

### What timestamp formats does the `--timestamps` option accept?

The `--timestamps` option accepts comma-separated values in `SS` (seconds), `MM:SS` (minutes:seconds), or `HH:MM:SS` (hours:minutes:seconds) formats. The parsing logic in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) normalizes these values before passing them to the frame extraction module.

### Do timestamp-cue frames count against the `--max-frames` limit?

Yes, frames extracted via `--timestamps` are added to the frame list and count toward the overall frame budget defined by `--max-frames` or the default `--detail` mode. However, they are guaranteed to appear in the final set even if the automatic sampling would have excluded that time region.

### Can I use `--timestamps` with audio-only content?

The `--timestamps` option specifically extracts visual frames using `ffmpeg` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). If you provide audio-only content, the timestamp extraction will fail unless a video stream is present. For audio-only analysis, the system relies on [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) for timestamped text output without visual frames.

### How does Claude correlate the frames with the transcript?

[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) outputs each frame with a timestamp annotation (e.g., `frame_001.jpg t=00:01:23`) followed by the transcript from [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py), which includes time-aligned text. Claude reads both the image files and the timestamped transcript to correlate visual events with specific audio segments.