# How to Customize Video Output in bradautomates/claude-video

> Customize video output in bradautomates/claude-video using command-line arguments and `.env` settings. Control frame rate, resolution, timestamps, and transcript generation for precise video analysis.

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

---

**You customize video output in bradautomates/claude-video through command-line arguments in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) and persistent settings in the `~/.config/watch/.env` environment file, controlling frame extraction density, resolution, timestamps, and transcript generation.**

The `bradautomates/claude-video` repository provides a `watch` skill that converts video content into structured Markdown reports containing extracted frames and transcripts. Whether processing YouTube URLs or local files, you can precisely tailor the visual and textual output through CLI flags and configuration files to match your analysis needs.

## Configure Frame Extraction Detail

The `--detail` argument controls how many frames are extracted and which engine processes them. This value resolves from CLI arguments first, then falls back to the `~/.config/watch/.env` file, and finally defaults to *balanced* as implemented in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).

The available detail levels map to specific frame budgets via the `frame_cap` function:

- **efficient**: Caps extraction at 50 frames using fast keyframe detection
- **balanced**: Default mode extracting up to 100 frames with scene-aware detection
- **token-burner**: Unlimited frame extraction for comprehensive visual analysis
- **transcript**: Skips frame extraction entirely unless custom timestamps are provided

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 71-78), the detail parameter is resolved and passed to the extraction engine:

```bash

# Efficient mode for quick analysis

watch https://youtu.be/xyz123 --detail efficient

# Unlimited frames for deep visual inspection

watch path/to/video.mp4 --detail token-burner --max-frames 0

```

## Adjust Resolution and Frame Rate

Control visual quality through the `--resolution` and `--fps` parameters. The resolution argument sets the width of extracted PNG/JPEG frames in pixels, with automatic height scaling capped at 1998 pixels maximum.

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 31-34), the resolution flows directly to all extraction helpers:

```bash

# High-resolution extraction for detailed frames

watch https://youtu.be/xyz123 --resolution 1024

```

For scene-aware extraction, the `--fps` parameter overrides the calculated frame rate but respects the `MAX_FPS` constant defined in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). The script clamps your input to prevent excessive extraction as shown in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 59-61):

```bash

# Force specific frame rate analysis

watch video.mp4 --fps 10

```

## Target Specific Video Segments

Limit processing to relevant portions using temporal targeting arguments. The `--start` and `--end` flags accept timestamp strings (e.g., `02:15`) that `parse_time` converts to seconds, while `--timestamps` accepts comma-separated absolute times for cue frames that override the frame cap budget.

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 40-58), these values compute a focused extraction window:

```bash

# Analyze only the introductions segment with specific cue frames

watch https://youtu.be/xyz123 \
  --start 00:30 --end 05:00 \
  --timestamps 01:15,03:40 \
  --resolution 800

```

Custom timestamps specified via `--timestamps` are parsed by `parse_timestamps` and extracted first via `extract_at_timestamps`, then merged with the regular frame list (lines 81-88).

## Toggle Frame Deduplication

By default, the `watch` skill removes near-duplicate frames to reduce token usage. For videos containing static slides or minimal motion that you want to preserve, disable this behavior with `--no-dedup`.

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 12-13), this flag inverts the boolean passed to `extract_keyframes` and `extract_scene_or_uniform`:

```bash

# Preserve all static slides from a lecture recording

watch lecture.webm --detail efficient --no-dedup

```

## Configure Whisper Transcription

When videos lack embedded captions, enable audio transcription via the `--whisper` flag. The system supports Groq and OpenAI backends, with API keys read from `~/.config/watch/.env` through the `load_api_key` function in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) (lines 1-30).

First, configure your environment file:

```bash

# ~/.config/watch/.env

GROQ_API_KEY=sk-xxxxxxxxxxxx

```

Then invoke transcription:

```bash

# Enable Groq Whisper for missing captions

watch https://youtu.be/xyz123 --whisper groq

```

Disable Whisper entirely with `--no-whisper` to skip audio processing when only visual analysis is required.

## Set Persistent Defaults via Environment Configuration

Avoid repetitive CLI flags by setting defaults in `~/.config/watch/.env`. The `get_config()` function in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (lines 48-56) reads this file via `read_env_file`, merging environment variables with hard-coded defaults.

Configuration priority follows: CLI arguments override environment variables, which override defaults.

```bash

# ~/.config/watch/.env

WATCH_DETAIL=efficient

```

With this configuration, `watch <source>` automatically applies the *efficient* detail level without requiring the `--detail` flag.

## Summary

- **Detail Control**: Use `--detail` with `efficient`, `balanced`, `token-burner`, or `transcript` to manage frame extraction density via `frame_cap` in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py)
- **Visual Quality**: Adjust `--resolution` for frame width and `--fps` for scene-aware sampling rates
- **Temporal Targeting**: Combine `--start`, `--end`, and `--timestamps` to focus analysis on specific segments
- **Deduplication**: Add `--no-dedup` to preserve static frames that would otherwise be filtered out
- **Transcription**: Configure `GROQ_API_KEY` or `OPENAI_API_KEY` in `~/.config/watch/.env` and use `--whisper` to enable audio transcription
- **Persistent Config**: Store common settings in `~/.config/watch/.env` to streamline repeated use

## Frequently Asked Questions

### How do I extract unlimited frames for comprehensive video analysis?

Use `--detail token-burner` combined with `--max-frames 0`. According to the `frame_cap` implementation in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), passing `0` disables the cap entirely, allowing scene-aware extraction to process all detected keyframes without the default 100-frame limit.

### Can I specify exact moments in the video for frame extraction?

Yes, use the `--timestamps` flag with comma-separated absolute times like `02:30,03:15`. The `parse_timestamps` function converts these to frame extraction triggers, processed before the budget calculation in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), ensuring these specific moments always appear in your output regardless of the detail level's frame cap.

### Where does bradautomates/claude-video store API keys for Whisper transcription?

API keys reside in `~/.config/watch/.env`. The `load_api_key` function in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) reads this file to retrieve `GROQ_API_KEY` or `OPENAI_API_KEY` values. Never pass keys via command-line arguments; the environment file keeps credentials secure and persistent across `watch` invocations.

### Why are my extracted frames missing when processing slide decks?

The deduplication filter likely removed visually similar frames. Slide decks with static content trigger the near-duplicate detection in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). Add `--no-dedup` to your command to preserve every detected frame, ensuring all slides appear in the final Markdown report.