How to Use bradautomates/claude-video with a Whisper API: Complete Setup Guide

You can use bradautomates/claude-video with a Whisper API by storing your GROQ_API_KEY or OPENAI_API_KEY in ~/.config/watch/.env, which the /watch skill automatically loads to transcribe videos lacking native captions.

The bradautomates/claude-video repository implements a Claude skill that analyzes video content through frame extraction and speech-to-text transcription. When processing videos without built-in subtitles, the skill automatically falls back to Whisper API providers, requiring proper API key configuration in your local environment.

Understanding the bradautomates/claude-video Architecture

The video analysis pipeline consists of several specialized scripts that orchestrate the transcription workflow. Understanding these components helps clarify how your API credentials flow through the system.

According to the source code, the key components include:

• skills/watch/SKILL.md: Documents the watch command and explains the pre-flight setup flow, including how the skill resolves its directory and reads API keys from ~/.config/watch/.env.
• skills/watch/scripts/setup.py: Checks for required binaries like ffmpeg and yt-dlp, then scaffolds the ~/.config/watch/.env file with placeholders for both API keys.
• skills/watch/scripts/config.py: Loads the environment file and exposes config.GROQ_API_KEY and config.OPENAI_API_KEY to the rest of the application.
• skills/watch/scripts/whisper.py: Implements thin wrappers around the Whisper APIs, preferring Groq when both keys are present.
• skills/watch/scripts/transcribe.py: Orchestrates caption selection, calling whisper.transcribe() only when native subtitles are unavailable.
• skills/watch/scripts/watch.py: The entry point that parses arguments and runs the complete download, extraction, and transcription pipeline.

Configuring the Whisper API Integration

Setting up the API integration requires three distinct steps: installing the skill, running the pre-flight checks, and adding your credentials to the environment file.

Step 1: Install the Watch Skill

First, install the skill using the Claude plugin system:

/plugin install watch@claude-video

This command registers the /watch command with your Claude instance and makes the skill's scripts available on your system.

Step 2: Run the Pre-Flight Setup

Before using the transcription features, run the setup script to verify dependencies and create the configuration directory:

python3 "$(watch_dir)/scripts/setup.py" --check

The setup.py script performs two critical functions. First, it verifies that ffmpeg and yt-dlp are installed on your system. Second, if ~/.config/watch/.env does not exist, it creates one with commented placeholders for both API providers and sets the file permissions to mode 0600 for security.

Step 3: Add Your API Credentials

Edit the ~/.config/watch/.env file to include your preferred Whisper provider key:

# For OpenAI Whisper

echo "OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx" >> ~/.config/watch/.env

# Or for Groq (preferred if both are present)

echo "GROQ_API_KEY=groq-xxxxxxxxxxxxxxxxxxxx" >> ~/.config/watch/.env

You only need to configure one key, though providing both allows the system to prioritize Groq for transcription tasks.

How the API Key Flow Works

Once configured, the bradautomates/claude-video skill follows a specific resolution path to authenticate with Whisper services.

Configuration Loading: When the /watch command executes, skills/watch/scripts/config.py reads the ~/.config/watch/.env file and stores the values in module-level variables. This makes the credentials available to other scripts without repeated file I/O operations.

Provider Selection: The skills/watch/scripts/whisper.py module implements the provider logic. It checks config.GROQ_API_KEY first; if present, it routes requests to the Groq endpoint. If the Groq key is absent but config.OPENAI_API_KEY exists, it falls back to OpenAI's Whisper API.

Transcription Orchestration: The skills/watch/scripts/transcribe.py module handles the decision logic. It first attempts to extract native subtitles from the video source. Only when native captions are unavailable does it invoke whisper.transcribe() to generate a transcript using your configured API key.

Usage Examples and Best Practices

With your API key configured, you can now process videos that lack subtitles.

Basic usage automatically triggers Whisper transcription when no native captions exist:

/watch https://youtu.be/dQw4w9WgXcQ "What happens at 30 seconds?"

Force a specific provider to override the automatic preference:

/watch https://youtu.be/dQw4w9WgXcQ --whisper openai "Summarize the audio."

Skip Whisper entirely to use only native captions or visual analysis:

/watch https://youtu.be/dQw4w9WgXcQ --no-whisper "Describe the visual layout."

Summary

• Store your Whisper API credentials in ~/.config/watch/.env using either GROQ_API_KEY or OPENAI_API_KEY variables.
• Run skills/watch/scripts/setup.py --check to initialize the secure configuration directory and verify system dependencies.
• The skill prefers Groq over OpenAI when both keys are present, as implemented in skills/watch/scripts/whisper.py.
• Transcription only occurs when native captions are missing, managed by the logic in skills/watch/scripts/transcribe.py.
• Use --whisper to force a specific provider or --no-whisper to disable API transcription entirely.

Frequently Asked Questions

Can I use bradautomates/claude-video without an API key?

Yes. If neither GROQ_API_KEY nor OPENAI_API_KEY is present in ~/.config/watch/.env, the skill runs in "no-whisper" mode. It will return only extracted frames and any available native captions, skipping the speech-to-text transcription step entirely.

Which Whisper provider does the skill prefer?

The skills/watch/scripts/whisper.py module prefers Groq when both API keys are configured. It checks for config.GROQ_API_KEY first and only falls back to OpenAI if the Groq key is absent. You can override this behavior using the --whisper command-line flag.

Where does bradautomates/claude-video store API keys?

API keys are stored in plain text in ~/.config/watch/.env, which the setup.py script creates with file mode 0600 (read/write for owner only) to restrict access. The skills/watch/scripts/config.py module reads this file at runtime to load the credentials into memory.

How do I switch between OpenAI and Groq providers?

To switch providers, simply update the ~/.config/watch/.env file to include only the key for your desired service, or set both keys and allow the automatic preference logic to select Groq. You can also force a specific provider for individual commands using the --whisper openai or --whisper groq flags.

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