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

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. 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, 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, 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 module gathers native captions via yt-dlp or falls back to Whisper via 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. 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 coordinator manages the workflow sequence: downloading via 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:

/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:

/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:

/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 and processed by 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.

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 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. 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 for timestamped text output without visual frames.

How does Claude correlate the frames with the transcript?

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, which includes time-aligned text. Claude reads both the image files and the timestamped transcript to correlate visual events with specific audio segments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}