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

> Manually select frames for Claude Video analysis using timestamps. Ensure key moments appear in reports with this CLI and Python guide. Learn to create cue frames easily.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-13

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) parses your `--timestamps` argument and merges the resulting cue frames with any detail-level frames extracted automatically.

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This bypasses the CLI wrapper and gives you fine-grained control over resolution and output paths.

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). The CLI entry point that orchestrates these calls is [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).