How to Manually Select Frames for Claude Video Analysis: CLI and Python Guide

You can manually select frames for Claude Video analysis by passing specific timestamps to the --timestamps flag, which creates "cue frames" that are guaranteed to appear in the final report regardless of automatic scene detection.

The bradautomates/claude-video repository automatically extracts representative frames based on scene changes, but this automation might miss critical moments you need analyzed. By manually selecting frames for Claude Video analysis, you can force the inclusion of exact timestamps—formatted as seconds, MM:SS, or HH:MM:SS—using either the command-line interface or the Python API.

How Timestamp-Based Frame Selection Works

When you supply manual timestamps, the tool executes a three-stage pipeline implemented in skills/watch/scripts/frames.py. Understanding this flow helps you predict which frames will appear in your final report.

Parsing Time Inputs with parse_timestamps

The CLI delegates timestamp interpretation to the parse_timestamps function. This utility converts comma-separated strings into a sorted, de-duplicated list of seconds (floats). It accepts absolute timestamps in multiple formats:

• Raw seconds (e.g., 12 or 133.5)
• Minutes and seconds (e.g., 00:45 or 2:13)
• Full timestamps (e.g., 01:30:00)

The function returns a normalized list that drives the extraction logic.

Extraction and Frame Pinning with extract_at_timestamps

Once parsed, timestamps flow to extract_at_timestamps, which seeks to each point using ffmpeg with the -ss flag for fast, accurate seeking. It writes JPEG files prefixed with cue_*.jpg to your output directory. These cue frames are pinned, meaning they bypass the deduplication and frame-budget capping logic defined in skills/watch/scripts/config.py. This ensures your manually selected moments are never dropped, even when automatic scene extraction hits the max_frames limit.

Using the --timestamps Flag in the CLI

The simplest way to manually select frames is through the watch command. The entry point in skills/watch/scripts/watch.py parses your --timestamps argument and merges the resulting cue frames with any detail-level frames extracted automatically.

watch "https://www.youtube.com/watch?v=example" \
  --detail balanced \
  --timestamps "12, 00:45, 02:13.5" \
  --out-dir ./my-workdir

This command instructs Claude Video to:

1. Analyze the video at the balanced detail level (normal scene-aware extraction).
2. Force extraction at 12 seconds, 45 seconds, and 2 minutes 13.5 seconds.
3. Output all frames to ./my-workdir.

The cue frames appear in the "Cue frames" section of the generated markdown report and are included in the total "Frames" list sent to the analysis model.

Extracting Frames Programmatically with Python

For custom workflows, import the core functions directly from skills/watch/scripts/frames.py. This bypasses the CLI wrapper and gives you fine-grained control over resolution and output paths.

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

video_path = "path/to/video.mp4"
out_dir = Path("./frames")

# Parse string input into list of floats: [12.0, 45.0, 133.5]

timestamps = parse_timestamps("12,00:45,02:13.5")

# Extract frames at exact timestamps

frames, meta = extract_at_timestamps(
    video_path,
    out_dir,
    timestamps,
    resolution=512,
    max_frames=None,  # No cap applied to cue frames

)

print("Cue frames:", frames)
print("Metadata:", meta)

The extract_at_timestamps function returns a tuple containing the frame descriptors and a metadata dictionary that may include the number of dropped timestamps if seeking failures occurred.

Why Cue Frames Bypass the Frame Budget

Claude Video imposes a frame budget based on your --detail setting (defined in skills/watch/scripts/config.py) to manage token consumption. However, cue frames generated from manual timestamps are treated as high-priority assets. Because they are pinned, the frame selection algorithm preserves them even when automatic scene frames must be pruned to stay within budget. This architectural guarantee ensures that critical evidence you explicitly request is always available for the AI analysis.

Summary

• Manual selection relies on the --timestamps CLI flag or the parse_timestamps / extract_at_timestamps Python API.
• Supported formats include raw seconds, MM:SS, and HH:MM:SS, parsed in skills/watch/scripts/frames.py.
• Cue frames are pinned and excluded from the automatic frame budget, ensuring they always appear in reports.
• Integration happens in skills/watch/scripts/watch.py, which merges manual cues with scene-aware extraction results.

Frequently Asked Questions

What timestamp formats does Claude Video support?

Claude Video accepts absolute timestamps as raw seconds (e.g., 45), minutes and seconds (e.g., 01:30), or full timestamps (e.g., 01:30:00). The parse_timestamps function in skills/watch/scripts/frames.py normalizes all formats into floating-point seconds before extraction.

Do manually selected frames count against the frame budget?

While cue frames are tracked in the frame list, they are pinned and exempt from the budget capping logic that limits automatic scene frames. According to the implementation in skills/watch/scripts/config.py and frames.py, your manual selections are never dropped to satisfy the max_frames constraint.

Can I combine manual timestamps with automatic scene detection?

Yes. The watch command in skills/watch/scripts/watch.py merges cue frames from manual timestamps with detail frames extracted via scene detection. The final report contains both your explicitly selected moments and the algorithmically chosen representative frames.

Where are the core extraction functions defined?

The timestamp parsing logic resides in parse_timestamps and the frame extraction logic in extract_at_timestamps, both located in skills/watch/scripts/frames.py. The CLI entry point that orchestrates these calls is skills/watch/scripts/watch.py.

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