# How to Use bradautomates/claude-video with a Whisper API: Complete Setup Guide > Effortlessly integrate bradautomates/claude-video with Whisper API. This guide shows you how to set up API keys for seamless video transcription, even without native captions. Learn more now. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: getting-started - Published: 2026-07-15 --- **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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)**: Implements thin wrappers around the Whisper APIs, preferring Groq when both keys are present. - **[`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py)**: Orchestrates caption selection, calling `whisper.transcribe()` only when native subtitles are unavailable. - **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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: ```bash /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: ```bash python3 "$(watch_dir)/scripts/setup.py" --check ``` The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/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: ```bash # 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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: ```bash /watch https://youtu.be/dQw4w9WgXcQ "What happens at 30 seconds?" ``` Force a specific provider to override the automatic preference: ```bash /watch https://youtu.be/dQw4w9WgXcQ --whisper openai "Summarize the audio." ``` Skip Whisper entirely to use only native captions or visual analysis: ```bash /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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py). - Transcription only occurs when native captions are missing, managed by the logic in [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/setup.py) script creates with file mode `0600` (read/write for owner only) to restrict access. The [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/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.