# How the Whisper Fallback Mechanism Selects Between Groq and OpenAI Backends

> Discover how the Whisper fallback mechanism in bradautomates/claude-video prioritizes Groq over OpenAI. Learn how it automatically selects backends based on API key availability.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-08

---

**The Whisper fallback mechanism in bradautomates/claude-video prioritizes Groq over OpenAI by checking for API keys in a specific order, automatically selecting the first available backend unless explicitly overridden by the user.**

The `claude-video` repository implements an intelligent fallback system for audio transcription that removes the guesswork from backend selection. When processing video content, the system must decide whether to route Whisper API calls to Groq or OpenAI based on available credentials. This selection logic is hardcoded in a specific priority sequence that favors Groq while maintaining OpenAI as a reliable secondary option.

## How the Backend Selection Works

The core logic resides in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), specifically within the `transcribe_video` function and its helper `load_api_key()`.

### The Automatic Discovery Logic

When `transcribe_video` is invoked without an explicit backend parameter, it delegates credential discovery to `load_api_key()`. This function implements a sequential search strategy:

1. It defines an ordered list of candidate tuples: `("GROQ_API_KEY", "groq")` followed by `("OPENAI_API_KEY", "openai")`.
2. It iterates through this list, checking for each key in environment variables (`os.environ`) or local configuration files.
3. The search targets two specific `.env` file locations: `~/.config/watch/.env` and a local `.env` file in the project root.
4. The first key found determines the backend; the function immediately returns a tuple of `(backend_name, api_key)`.

If neither key is discovered, `load_api_key` returns `(None, None)`, triggering an abort with a setup message directing the user to configure their API credentials.

### Priority Order: Groq First, OpenAI Second

The hardcoded sequence in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) (lines 93-99) establishes **Groq as the primary preference**. The system only falls back to OpenAI when:

- No `GROQ_API_KEY` exists in the environment or configured `.env` files
- An `OPENAI_API_KEY` is present while the Groq key is absent

This design assumes Groq as the preferred provider for cost or performance reasons, while ensuring transcription remains possible if only OpenAI credentials are available.

## Explicit Backend Override

Users can bypass the automatic fallback mechanism entirely by specifying the backend explicitly. The `transcribe_video` function accepts a `backend` parameter that skips the `load_api_key()` discovery process.

When passed via the `--backend` CLI flag (e.g., `--backend openai`), the code ignores any automatically discovered keys and forces the selected provider. This override is useful for testing specific APIs or when both keys are present but you prefer the non-default option.

## Code Implementation Examples

### Automatic Selection with Groq Priority

```python

# Environment contains: GROQ_API_KEY=gsk_xxx

from skills.watch.scripts import whisper

segments, backend_used = whisper.transcribe_video(
    video_path="example.mp4",
    audio_out=Path("audio.mp3")
)
print(f"Used backend: {backend_used}")  # Output: "groq"

```

### Automatic Fallback to OpenAI

```python

# Environment contains: OPENAI_API_KEY=sk-xxx (no GROQ_API_KEY)

segments, backend_used = whisper.transcribe_video(
    video_path="example.mp4",
    audio_out=Path("audio.mp3")
)
print(f"Used backend: {backend_used}")  # Output: "openai"

```

### Explicit Override via Function Call

```python

# Force OpenAI even if Groq key is present

segments, backend_used = whisper.transcribe_video(
    video_path="example.mp4",
    audio_out=Path("audio.mp3"),
    backend="openai"
)
print(backend_used)  # Output: "openai"

```

### CLI Usage with Backend Flag

```bash

# Override automatic selection from command line

python -m skills.watch.scripts.whisper video.mp4 audio.mp3 --backend openai

```

## Configuration and Environment Setup

The system searches for API keys in the following locations in order of precedence:

- **Environment variables**: `GROQ_API_KEY` or `OPENAI_API_KEY`
- **Global config**: `~/.config/watch/.env`
- **Local config**: `.env` in the project directory

To ensure the Whisper fallback mechanism selects your preferred backend, place the corresponding API key in one of these locations. If you want to guarantee Groq is used, ensure only `GROQ_API_KEY` is set. If you want to force OpenAI, either set only `OPENAI_API_KEY` or use the explicit `--backend openai` flag.

## Summary

- The **Whisper fallback mechanism** lives in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) and uses the `load_api_key()` function for automatic discovery.
- **Groq takes precedence** over OpenAI in the hardcoded candidate list.
- The system checks for `GROQ_API_KEY` first, then `OPENAI_API_KEY`, searching environment variables and `.env` files.
- Users can override automatic selection by passing the `backend` parameter to `transcribe_video` or using the `--backend` CLI flag.
- If neither key is found, the function returns `(None, None)` and the transcription aborts with a configuration error.

## Frequently Asked Questions

### How does the system decide which Whisper backend to use?

The system checks for API keys in a specific order: first `GROQ_API_KEY`, then `OPENAI_API_KEY`. Whichever key is found first determines the backend. Groq is always attempted first because it appears first in the candidate list defined in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py).

### Can I force the Whisper transcription to use OpenAI instead of Groq?

Yes. You can pass `backend="openai"` as a parameter to the `transcribe_video` function, or use the `--backend openai` CLI flag. This bypasses the automatic `load_api_key()` discovery and forces the OpenAI backend regardless of which API keys are present in your environment.

### Where does the Whisper script look for API keys?

The `load_api_key()` function searches three locations: environment variables (`os.environ`), a global configuration file at `~/.config/watch/.env`, and a local `.env` file in the project directory. It checks these locations for each backend in the priority order (Groq first, then OpenAI).

### What happens if I don't have either API key configured?

If neither `GROQ_API_KEY` nor `OPENAI_API_KEY` is found in the environment or configuration files, `load_api_key()` returns `(None, None)`. This causes `transcribe_video` to abort with a helpful error message directing you to set up your API credentials before attempting transcription.