How to Configure Whisper API Using Groq or OpenAI in Claude-Video

Configure the Whisper API in Claude-Video by setting either GROQ_API_KEY or OPENAI_API_KEY as environment variables or in ~/.config/watch/.env, with Groq automatically preferred when both keys are present.

The Claude-Video repository's /watch skill transcribes video audio using OpenAI's Whisper model through either the Groq or OpenAI API endpoints. Configuring the Whisper API using Groq or OpenAI requires setting specific environment variables that the system automatically detects and prioritizes according to the logic in skills/watch/scripts/whisper.py.

Backend Selection Logic

The transcription backend is determined by the load_api_key function in skills/watch/scripts/whisper.py (lines 65-112), which implements a cascading priority system to select between providers.

How the API Key Loader Works

The load_api_key() function first checks for GROQ_API_KEY and OPENAI_API_KEY in the process environment, then falls back to .env files located at ~/.config/watch/.env and the project root. It returns a tuple containing the backend name ("groq" or "openai") and the corresponding API key.

When transcribe_video() is called without explicit backend or api_key parameters (lines 24-30), it automatically invokes load_api_key() to determine which provider to use.

Priority Order and Fallback

Groq is the preferred provider. The system checks for GROQ_API_KEY first, and only falls back to OPENAI_API_KEY if the Groq key is absent. If neither key is found, the /watch skill operates in video-frame-only mode without transcription capabilities.

Configuration Methods

You can configure the API credentials through three methods, listed in order of precedence.

Environment Variables

Setting variables in your shell provides the highest priority configuration and overrides any .env file settings:

export GROQ_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# or

export OPENAI_API_KEY=sk-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

The .env File Location

The persistent configuration lives in ~/.config/watch/.env. This file is created automatically by the setup script with mode 0600 (read/write owner only) for security. The template includes commented placeholders for both providers as defined in skills/watch/scripts/setup.py (lines 38-55):

# /watch API configuration

# ...

GROQ_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
#OPENAI_API_KEY=sk-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Using the Setup Script

Run the installer to scaffold the configuration directory and .env file:

python3 skills/watch/scripts/setup.py

The script checks for existing keys using the _have_api_key() helper (lines 16-22) and writes SETUP_COMPLETE=true once a valid key is detected. If the .env file is missing, the script creates one with the template above.

Implementation Details

Understanding the internal mechanics ensures reliable configuration across different deployment scenarios.

Automatic Backend Detection

The _have_api_key() function in skills/watch/scripts/setup.py returns a tuple (bool, str) indicating whether a key exists and which backend it corresponds to. This detection drives both the setup wizard and runtime backend selection in skills/watch/scripts/whisper.py.

Security and Permissions

When the setup script creates ~/.config/watch/.env, it explicitly sets file permissions to 0600 (owner read/write only). This prevents other users on the system from accessing your API credentials.

Usage Examples

Practical implementations demonstrating the configuration in action.

Command Line Setup

Initialize the configuration and run a transcription:

# Scaffold the config file

python3 skills/watch/scripts/setup.py

# Edit ~/.config/watch/.env to add your key

# Then run:

export GROQ_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
watch https://www.youtube.com/watch?v=dQw4w9WgXcQ

Programmatic Python Usage

Import and use the transcription function directly from skills/watch/scripts/whisper.py:

import os
from pathlib import Path
from skills.watch.scripts.whisper import transcribe_video

# Optional: set key programmatically

os.environ["GROQ_API_KEY"] = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

segments, backend = transcribe_video(
    video_path="example.mp4",
    audio_out=Path("example_audio.mp3")
)

print(f"Transcribed with {backend}:")
for seg in segments:
    print(f"{seg['start']:.2f}-{seg['end']:.2f}: {seg['text']}")

Summary

• Configure the Whisper API by setting GROQ_API_KEY or OPENAI_API_KEY in ~/.config/watch/.env or as environment variables
• Groq is automatically preferred over OpenAI when both keys are present according to the logic in load_api_key()
• Run skills/watch/scripts/setup.py to generate the configuration template automatically with secure permissions
• The system falls back to video-frame-only mode if neither API key is configured
• File permissions are set to 0600 to protect API credentials from unauthorized access

Frequently Asked Questions

Which provider is preferred when configuring the Whisper API?

Groq is the preferred provider. The load_api_key() function in skills/watch/scripts/whisper.py checks for GROQ_API_KEY before falling back to OPENAI_API_KEY. If both environment variables are present, Groq is selected automatically for the transcription session.

Can I use both Groq and OpenAI simultaneously?

No, the system uses a single backend per transcription. The _have_api_key() helper in skills/watch/scripts/setup.py detects the first available key and commits to that provider for the session. You must choose one provider per environment configuration, though you can switch between them by changing which environment variable is set.

What happens if no API key is configured?

If neither GROQ_API_KEY nor OPENAI_API_KEY is found in the environment or .env files, the /watch skill continues to function but returns only video frames without audio transcription. The transcribe_video() function will skip the Whisper API call and return empty segments, while the backend detection returns None.

Where is the configuration file stored?

The persistent configuration is stored in ~/.config/watch/.env. This location is created by skills/watch/scripts/setup.py with restricted permissions (mode 0600) to ensure your API keys remain secure and readable only by the file owner.

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