How to Customize Video Output in bradautomates/claude-video

You customize video output in bradautomates/claude-video through command-line arguments in 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.

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 (lines 71-78), the detail parameter is resolved and passed to the extraction engine:

# 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 (lines 31-34), the resolution flows directly to all extraction helpers:

# 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. The script clamps your input to prevent excessive extraction as shown in watch.py (lines 59-61):

# 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 (lines 40-58), these values compute a focused extraction window:

# 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 (lines 12-13), this flag inverts the boolean passed to extract_keyframes and extract_scene_or_uniform:

# 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 (lines 1-30).

First, configure your environment file:

# ~/.config/watch/.env

GROQ_API_KEY=sk-xxxxxxxxxxxx

Then invoke transcription:

# 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 (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.

# ~/.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
• 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, 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, 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 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. Add --no-dedup to your command to preserve every detected frame, ensuring all slides appear in the final Markdown report.

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