How to Use --timestamps to Extract Frames at Specific Moments with Claude-Video

Supply the --timestamps flag followed by a comma-separated list of timestamps to extract specific frames at absolute positions in the video.

The claude-video repository provides a watch skill that extracts video frames using three distinct methods: uniform sampling, scene-change detection, and timestamp-based extraction. When you need to capture exact moments rather than uniform samples, the --timestamps flag allows you to specify absolute time positions in seconds, MM:SS, or HH:MM:SS format.

How Timestamp-Based Extraction Works

The timestamp extraction workflow follows a four-stage pipeline defined in the skills/watch/scripts/ directory. When you invoke the watch command with the --timestamps flag, the system processes your input through dedicated parsing functions before executing targeted FFmpeg commands.

CLI Argument Parsing

In skills/watch/scripts/watch.py, the command-line interface defines the --timestamps option at lines 42-45. This argument expects a comma-separated string of absolute timestamps. The implementation stores the raw string for downstream processing, ensuring the value is passed to the frame extraction engine before any audio-only optimizations are applied.

When timestamps are present, the --detail mode automatically switches to video-only processing, bypassing audio-only optimizations because timestamp extraction requires the video stream.

Timestamp Parsing and Validation

The raw timestamp string is handed to frames.parse_timestamps in skills/watch/scripts/frames.py (lines 295-311). This helper function:

• Tolerates whitespace and mixed format inputs (seconds, minutes:seconds, hours:minutes:seconds)
• Removes duplicate timestamps automatically
• Returns a sorted list of floats representing seconds
• Raises a ValueError for invalid entries

The parser handles normalization internally, converting timecode strings into absolute seconds for consistent processing.

Frame Extraction with FFmpeg

The parsed list of seconds is passed to frames.extract_at_timestamps in skills/watch/scripts/frames.py (lines 324-388). For each timestamp, the function executes an FFmpeg command using -ss for precise seeking followed by -vframes 1 to capture a single frame. This approach ensures accurate frame extraction without processing the entire video sequentially.

The function returns a tuple containing:

• A list of generated frame file paths
• A metadata dictionary with "engine": "timestamps" and the requested timestamp values

Output Integration

In skills/watch/scripts/watch.py (lines 178-186), the extracted cue frames are merged into the overall result set. The detail view displays a count of extracted frames, labeling them as originating from transcript-flagged timestamps when presenting the final output to the user.

Command-Line Usage Examples

Use the --timestamps flag with the watch command to extract frames at specific moments. Separate multiple timestamps with commas, and optionally combine with --detail for balanced analysis.

Extract frames at 1 second, 3 seconds, and 1 minute 2 seconds:

watch https://example.com/video.mp4 --timestamps "1,3,1:02"

Combine timestamp extraction with detail view:

watch https://example.com/video.mp4 --detail balanced --timestamps "0:30,2:15,5"

The command output includes a summary line indicating the count of cue frames extracted:

Cue frames: 3 at transcript-flagged timestamps

Programmatic Python API

You can also invoke timestamp extraction directly from Python code using the internal frame utilities.

Import the parsing and extraction functions from the frames module:

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

# Parse a raw timestamp string with mixed formats

raw = "30,1:05,90"
seconds = parse_timestamps(raw)          # → [30.0, 65.0, 90.0]

# Extract frames at the parsed timestamps

video_path = "/tmp/video.mp4"
out_dir    = "/tmp/frames"
frames, meta = extract_at_timestamps(video_path, out_dir, seconds)

print(frames)  # ['/tmp/frames/f001.jpg', '/tmp/frames/f002.jpg', ...]

print(meta)    # {'engine': 'timestamps', 'requested': [30.0, 65.0, 90.0]}

The extract_at_timestamps function handles directory creation and file naming automatically, returning absolute paths to the generated JPEG files.

Input Formats and Edge Cases

The timestamp parser accepts flexible input formats but enforces strict validation rules. Whitespace is automatically trimmed, and duplicate values are removed during parsing.

Valid input handling:

• " 90 , 30, 30 " → [30.0, 90.0] (whitespace trimmed, duplicates removed, sorted)
• "30,1:05,90" → [30.0, 65.0, 90.0] (mixed formats normalized to seconds)

Invalid input handling:

• "" or " , ," → Returns empty list [] (no frames extracted)
• "4:bad" → Raises ValueError with clear error message about invalid format

Always use absolute timestamps from the start of the video. Relative offsets or durations are not supported by the current implementation in skills/watch/scripts/frames.py.

Summary

• The --timestamps flag in claude-video enables precise frame extraction at absolute time positions using the watch skill
• Input parsing is handled by frames.parse_timestamps in skills/watch/scripts/frames.py, supporting seconds, MM:SS, and HH:MM:SS formats
• Frame extraction uses FFmpeg with -ss seeking and -vframes 1 for each timestamp via frames.extract_at_timestamps
• The presence of timestamps forces video-only processing mode, disabling audio-only optimizations
• Duplicate timestamps are automatically deduplicated, and invalid formats raise ValueError exceptions

Frequently Asked Questions

What timestamp formats does the --timestamps flag accept?

The flag accepts comma-separated values in three formats: plain seconds (e.g., 90), minutes:seconds (e.g., 1:30), or hours:minutes:seconds (e.g., 1:30:45). The parse_timestamps function in skills/watch/scripts/frames.py normalizes all formats to floating-point seconds for internal processing.

How does timestamp extraction differ from uniform sampling?

Uniform sampling extracts frames at regular intervals across the entire video duration, while timestamp extraction captures specific moments you define. According to the source code in skills/watch/scripts/frames.py, timestamp extraction uses individual FFmpeg seek commands for each position, whereas uniform sampling processes the video stream sequentially.

Can I combine --timestamps with other extraction methods?

When you specify --timestamps, the system adds those specific frames to the overall result set alongside any other configured extractions. However, the --detail mode automatically switches to video-only processing when timestamps are present, as implemented in skills/watch/scripts/watch.py, ensuring the video stream is available for precise seeking.

What happens if I provide an invalid timestamp format?

The parse_timestamps function raises a ValueError with a descriptive error message. Inputs like "4:bad" or malformed timecodes will halt execution before any FFmpeg commands are executed. Empty strings or strings containing only commas and whitespace return an empty list and result in no frame extraction.

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