How Timestamps Are Extracted in Claude Video Using --timestamps

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 and 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, the parse_timestamps function handles this transformation.

Input Processing

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

# 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 (lines 295-324).

---

Extracting Frames at Each Timestamp

The parsed timestamps feed into extract_at_timestamps, also in 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:

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:

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 (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

# 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	parse_timestamps	Converts raw --timestamps input to sorted seconds
skills/watch/scripts/frames.py	extract_at_timestamps	Uses ffmpeg -ss and showinfo for precise frame capture
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 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 contains parse_timestamps (lines 295-324) and extract_at_timestamps (lines 324-384), while skills/watch/scripts/watch.py (lines 81-182) orchestrates their integration into the overall workflow according to the bradautomates/claude-video source code.

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