# How Whisper Integration Works with Groq and OpenAI Backends in Claude-Video

> Learn how Whisper integrates with Groq and OpenAI backends in Claude-Video. Discover a unified transcription interface routing audio seamlessly for efficient speech-to-text processing.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-06

---

**The [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) script provides a unified transcription interface that routes audio to either Groq or OpenAI using identical request payloads, switching only the base URL and authentication headers based on the `--backend` flag.**

The `claude-video` repository by bradautomates bundles a lightweight, pure-stdlib Python client for audio transcription. Located at [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), this implementation abstracts provider-specific differences, enabling users to toggle between Groq and OpenAI Whisper APIs without modifying core request logic.

## Backend Selection Logic

The script determines which provider to use via a command-line argument. In [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), the parser validates the `--backend` flag against supported options (`groq` and `openai`), defaulting to **Groq** when unspecified. Invalid selections trigger an immediate error exit (as seen around line 470 in the source), ensuring the calling process receives clear feedback before any network requests initiate.

## Authentication Flow

Both backends rely on API keys stored in a user-specific environment file rather than hardcoded credentials or repository-committed secrets.

- **Environment File Location**: `~/.config/watch/.env`
- **Key Management**: On first run, [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) creates this directory and file, prompting users to paste their keys
- **Runtime Loading**: The script uses `dotenv` to load the file, then retrieves keys via `os.getenv`:
  - `GROQ_API_KEY` for Groq access
  - `OPENAI_API_KEY` for OpenAI access

This design keeps credentials out of version control while remaining accessible to the transcription workflow orchestrated by [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py).

## API Request Construction

Despite targeting different providers, the HTTP implementation remains nearly identical, leveraging Groq's OpenAI-compatible API specification.

**Groq Backend:**
- **Endpoint**: `https://api.groq.com/openai/v1/audio/transcriptions`
- **Headers**: `Authorization: Bearer <GROQ_API_KEY>`
- **Payload**: Multipart form-data containing the audio file and `model` parameter set to `whisper-1`

**OpenAI Backend:**
- **Endpoint**: `https://api.openai.com/v1/audio/transcriptions`
- **Headers**: `Authorization: Bearer <OPENAI_API_KEY>`
- **Payload**: Identical multipart structure with the same `whisper-1` model identifier

The only branching logic in the codebase selects between these two base URLs and corresponding environment variables; the file handling, model specification, and response parsing remain shared.

## Response Processing and Error Handling

After POSTing the audio file, the script expects a JSON response containing a `text` field. The implementation extracts this value and outputs it to **stdout** by default, or writes to a file path if provided as the second positional argument.

Error handling covers:
- **HTTP errors**: Non-2xx status codes print concise error messages and exit with non-zero status
- **Network exceptions**: Connection failures are caught and reported, allowing the parent [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) workflow to fall back to caption-based transcription methods when Whisper unavailable

## Usage Examples

**Command-Line Transcription (Groq default):**

```bash
python -m skills.watch.scripts.whisper ./audio.wav ./transcript.txt

```

**Explicit OpenAI Backend:**

```bash
python -m skills.watch.scripts.whisper ./audio.wav ./transcript.txt --backend openai

```

**Programmatic Integration:**

```python
from skills.watch.scripts.whisper import transcribe

# Groq transcription (default)

groq_text = transcribe(audio_path="meeting.wav", backend="groq")

# OpenAI transcription

openai_text = transcribe(audio_path="meeting.wav", backend="openai")

```

**Sample Environment Configuration** (`~/.config/watch/.env`):

```dotenv
GROQ_API_KEY=grok_xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

```

## Summary

- The [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) script abstracts provider differences through a single `--backend` flag that switches between Groq and OpenAI endpoints
- Authentication uses isolated environment files at `~/.config/watch/.env`, initialized by [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) to prevent credential leakage
- Both services receive identical `multipart/form-data` requests specifying the `whisper-1` model, minimizing code duplication
- Response handling extracts the JSON `text` field uniformly, with graceful error reporting that supports fallback workflows in [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py)
- The implementation requires only Python standard library plus `dotenv`, keeping dependencies minimal for portability

## Frequently Asked Questions

### How do I switch between Groq and OpenAI backends?

Pass the `--backend` flag followed by either `groq` or `openai` when running the CLI. In Python code, supply the `backend` parameter to the `transcribe()` function. The default is Groq if you omit this argument.

### Does the integration support audio formats other than WAV?

The script passes the audio file directly to the provider APIs without local transcoding. Both Groq and OpenAI Whisper endpoints accept common formats including MP3, WAV, and M4A, though you should verify current provider documentation for specific codec support.

### What happens if my API key is missing or invalid?

The script validates the presence of the appropriate environment variable (`GROQ_API_KEY` or `OPENAI_API_KEY`) before constructing the request. If the key is missing or the API returns an authentication error, the script prints an error message and exits with a non-zero status code, allowing calling processes to detect the failure.

### Can I use this without the rest of the claude-video skill system?

Yes. While designed to integrate with [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py), the [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) module functions as a standalone script. Ensure you create the `~/.config/watch/.env` file manually or set environment variables directly, then import the `transcribe` function or run the module directly from any directory.