How claude-video's Whisper Integration Switches Between Groq and OpenAI Backends

Claude-video uses a pure-stdlib Python script that automatically selects between Groq and OpenAI Whisper APIs based on environment variables or CLI flags, normalizing both responses into a unified transcription format.

The bradautomates/claude-video repository provides a flexible Whisper integration that lets you choose between Groq and OpenAI transcription backends without modifying source code. This claude-video Whisper integration with Groq and OpenAI backends prioritizes Groq for cost-effectiveness while maintaining OpenAI as a seamless fallback. Understanding how the backend selection logic works in skills/watch/scripts/whisper.py ensures you can optimize for latency, pricing, or availability.

Backend Selection Hierarchy in load_api_key

The core logic resides in the load_api_key function within skills/watch/scripts/whisper.py. This function implements a three-tier selection process:

1. CLI Flag Override – Passing --backend groq or --backend openai forces that specific provider regardless of environment variables.
2. Automatic Detection – Without a flag, the script checks for GROQ_API_KEY first; if absent, it falls back to OPENAI_API_KEY.
3. Failure Mode – If neither key is found, the script aborts with instructions to run the setup helper (setup.py).

Environment Variable Priority

Keys are sourced from three locations in order of precedence:

• Shell environment variables (export GROQ_API_KEY=... or export OPENAI_API_KEY=...)
• User-specific dotenv file at ~/.config/watch/.env
• Project-local .env file in the working directory

Endpoint and Model Configuration

The script hardcodes distinct endpoints and models for each provider in whisper.py:

Groq Configuration:

• Endpoint: https://api.groq.com/openai/v1/audio/transcriptions
• Model: whisper-large-v3

OpenAI Configuration:

• Endpoint: https://api.openai.com/v1/audio/transcriptions
• Model: whisper-1

These constants feed into _transcribe_file, which constructs multipart uploads via _build_multipart and executes requests through _post_whisper.

Unified Response Normalization

Regardless of which backend processes the audio, whisper.py normalizes the API response into a consistent segment format. Both Groq and OpenAI responses are transformed into dictionaries containing start, end, and text keys. This backend-agnostic approach means downstream consumers in watch.py receive identical data structures whether using Groq's whisper-large-v3 or OpenAI's whisper-1.

Configuration Examples

Setting Up Groq as the Primary Backend

Create the configuration directory and store your Groq key:

mkdir -p ~/.config/watch
cat >> ~/.config/watch/.env <<EOF
GROQ_API_KEY=your-groq-secret-key
EOF
chmod 600 ~/.config/watch/.env

Run the transcription:

python -m skills.watch.scripts.whisper /path/to/video.mp4

# Output indicates: backend: groq

Configuring OpenAI as Fallback

If no Groq key exists, the script automatically uses OpenAI:

cat >> ~/.config/watch/.env <<EOF
OPENAI_API_KEY=sk-your-openai-secret-key
EOF

Forcing a Specific Backend via CLI

Override automatic detection with the --backend flag:

# Force OpenAI even if Groq key exists

python -m skills.watch.scripts.whisper /path/to/video.mp4 --backend openai

# Force Groq even if only OpenAI key is configured

python -m skills.watch.scripts.whisper /path/to/video.mp4 --backend groq

Temporary Testing with Environment Variables

For one-off tests without persistent configuration:

GROQ_API_KEY=your-key python -m skills.watch.scripts.whisper video.mp4

Integration with the Watch Skill

The config.py module exposes backend configuration to the broader skill suite through get_config(). This allows watch.py and other entry points to respect the same dotenv files and backend preferences established in whisper.py, ensuring consistent behavior across the claude-video codebase.

Summary

• Automatic fallback: Groq is preferred; OpenAI serves as the automatic fallback when GROQ_API_KEY is absent.
• CLI override: Use --backend groq|openai to force a specific provider regardless of environment configuration.
• Flexible configuration: API keys can reside in environment variables, ~/.config/watch/.env, or project-local .env files.
• Normalized output: Both backends return identical {start, end, text} segment formats via _transcribe_file.
• Security: Configuration files should use chmod 600 permissions as shown in setup.py helpers.

Frequently Asked Questions

Does claude-video require code changes to switch between Groq and OpenAI?

No. The load_api_key function in skills/watch/scripts/whisper.py handles backend selection automatically based on available API keys or CLI arguments. You can switch providers by setting different environment variables or using the --backend flag without touching the Python source.

Which Whisper model does claude-video use for each backend?

According to the source code in whisper.py, Groq uses the whisper-large-v3 model while OpenAI uses the standard whisper-1 model. These are hardcoded constants passed to their respective endpoints (https://api.groq.com/openai/v1/audio/transcriptions and https://api.openai.com/v1/audio/transcriptions).

How does claude-video handle authentication errors?

If neither GROQ_API_KEY nor OPENAI_API_KEY is found in environment variables or dotenv files, the script aborts with a descriptive error message directing users to run setup.py. This helper script creates the ~/.config/watch/.env file with placeholder values for both providers.

Can I use both Groq and OpenAI simultaneously in the same claude-video instance?

No. The architecture selects a single backend per invocation via load_api_key. While you could theoretically alternate calls by changing environment variables between executions, each individual transcription request targets only one provider as determined by the hierarchy: CLI flag > Groq key > OpenAI key.

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