How to Use Timestamps to Extract Specific Moments from Videos in Claude Video

Claude Video's watch skill allows you to extract exact frames from any video by supplying a comma-separated list of timestamps in seconds, minutes:seconds, or hours:minutes:seconds format.

Claude Video is an open-source automation framework for video analysis that includes a powerful watch skill for intelligent frame extraction. Learning how to use timestamps to extract specific moments from videos in Claude Video enables precise content analysis without processing entire footage sequences. The system normalizes multiple time formats automatically, removes duplicate entries, and generates high-quality JPEG frames named cue_XXXX.jpg at exactly the requested temporal positions.

Timestamp-Based Extraction Pipeline

The watch skill implements a four-stage pipeline for timestamp-driven frame extraction according to the bradautomates/claude-video source code. Understanding these stages helps you optimize extraction workflows and troubleshoot timing issues.

CLI Argument Parsing

The extraction process begins in skills/watch/scripts/watch.py, where the --timestamps flag is defined at lines 42-45. When you supply this parameter, the tool immediately triggers a full video download rather than audio-only mode, ensuring ffmpeg can seek to exact byte positions for frame accuracy.

Timestamp Normalization

Raw timestamp strings undergo conversion in skills/watch/scripts/frames.py through the parse_timestamps function (lines 295-310). This utility accepts comma-separated values and normalizes them to floating-point seconds.

The parser supports three distinct input formats:

• Seconds only: 45 converts to 45.0 seconds
• Minutes and seconds: 2:30 converts to 150.0 seconds
• Hours, minutes, seconds: 00:01:15 converts to 75.0 seconds

parse_timestamps automatically sorts the final list in ascending order and removes duplicates, guaranteeing deterministic frame extraction regardless of input order.

Frame Extraction at Exact Moments

The extract_at_timestamps function in skills/watch/scripts/frames.py (lines 324-390) handles the actual rendering. This function:

1. Validates each timestamp against optional start/end window constraints
2. Applies optional frame caps via the max_frames parameter
3. Invokes ffmpeg once per timestamp to extract a single JPEG frame
4. Writes output files as cue_XXXX.jpg in the designated working directory

Each extraction includes metadata tagging with "reason": "transcript-cue" to distinguish timestamp-driven frames from automatically selected detail frames.

Command-Line Usage

Extract specific moments from YouTube videos or local files using the --timestamps flag with the watch command. The flag accepts any combination of the supported time formats.

# Extract frames at 1 second, 3 minutes 15 seconds, and 2 minutes 30 seconds

watch https://www.youtube.com/watch?v=abc123 \
  --detail balanced \
  --timestamps 1,3:15,00:02:30

The command outputs a summary showing resolved timestamps:

[watch] Cue frames: 3 at transcript-flagged timestamps
- frame 0 (t=00:00:01.00, reason=transcript-cue)
- frame 1 (t=00:03:15.00, reason=transcript-cue)
- frame 2 (t=00:02:30.00, reason=transcript-cue)

All cue_XXXX.jpg files appear alongside standard detail frames in the temporary work directory, ready for analysis or further processing.

Python API Implementation

For programmatic workflows, import the frame extraction utilities directly from the frames module.

from pathlib import Path
from skills.watch.scripts import frames

# Parse timestamp string into normalized seconds

timestamps = frames.parse_timestamps("45,2:30,00:01:15")

# Result: [45.0, 75.0, 90.0] (automatically sorted)

# Extract frames with custom resolution

video_path = "/path/to/video.mp4"
output_dir = Path("/tmp/extraction")

extracted, metadata = frames.extract_at_timestamps(
    video_path=video_path,
    out_dir=output_dir,
    timestamps=timestamps,
    resolution=512,      # JPEG width in pixels, defaults to 512

    max_frames=None,     # Set to integer to limit extracted frames

)

The function returns a tuple containing:

• extracted: List of dictionaries with index, timestamp_seconds, path, and reason keys
• metadata: Dictionary with engine: "timestamps", candidate_count, selected_count, and dropped_out_of_window statistics

Output Structure and Metadata

Each extracted frame generates a JPEG file following the naming convention cue_XXXX.jpg, where XXXX represents a zero-padded index. The resolution parameter controls the output width while maintaining aspect ratio, defaulting to 512 pixels as implemented in frames.py.

The metadata dictionary returned by extract_at_timestamps provides extraction transparency:

{
    "engine": "timestamps",
    "candidate_count": 3,
    "selected_count": 3,
    "dropped_out_of_window": 0,
    "fallback": False
}

This structure reports how many timestamps were requested, how many survived window filtering, and whether any were dropped due to temporal constraints outside your specified range.

Core Implementation Files

According to the bradautomates/claude-video source code, timestamp functionality resides in these key locations:

• skills/watch/scripts/watch.py: CLI entry point that parses --timestamps arguments and orchestrates the full video download workflow
• skills/watch/scripts/frames.py: Contains parse_timestamps (lines 295-310) and extract_at_timestamps (lines 324-390) implementation
• tests/test_timestamps.py: Unit tests validating timestamp parsing edge cases and format conversions
• tests/test_watch.py: Integration tests covering end-to-end watch command execution with timestamp parameters

Summary

• Claude Video extracts exact video moments using the watch skill with the --timestamps CLI flag, which triggers full video downloads to ensure frame accuracy.
• parse_timestamps in skills/watch/scripts/frames.py normalizes SS, MM:SS, and HH:MM:SS formats into sorted floating-point seconds while removing duplicates.
• extract_at_timestamps generates cue_XXXX.jpg files by invoking ffmpeg once per timestamp, with optional resolution and frame count constraints.
• The metadata system tracks extraction statistics including candidate counts and window filtering results through a standardized dictionary format.

Frequently Asked Questions

What timestamp formats does Claude Video accept?

Claude Video accepts three timestamp formats through the parse_timestamps function: seconds only (e.g., 45), minutes and seconds separated by a colon (e.g., 2:30), and full hours:minutes:seconds notation (e.g., 00:01:15). All formats are automatically converted to floating-point seconds and sorted before extraction.

Why does using timestamps force a full video download?

When you specify the --timestamps flag, watch.py disables audio-only mode and downloads the complete video file. This ensures ffmpeg can perform accurate byte-level seeking to extract frames at exact temporal positions, which is impossible with audio-only streams or segmented downloads.

How are the extracted frame files named and organized?

The extract_at_timestamps function saves frames as cue_XXXX.jpg in the specified output directory, where XXXX is a zero-padded index corresponding to the timestamp's position in the sorted list. These files appear alongside any standard detail frames in the temporary work directory.

Can I limit how many timestamp frames get extracted?

Yes. When calling extract_at_timestamps programmatically, set the max_frames parameter to an integer value to cap the number of extracted frames. The function processes timestamps in sorted order and stops once reaching the limit, dropping subsequent timestamps from the extraction queue.

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