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

The 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, 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, 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 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.

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 workflow to fall back to caption-based transcription methods when Whisper unavailable

Usage Examples

Command-Line Transcription (Groq default):

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

Explicit OpenAI Backend:

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

Programmatic Integration:

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):

GROQ_API_KEY=grok_xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

Summary

• The 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 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
• 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, the 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.

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