Whisper API Fallback Logic Between Groq and OpenAI: How It Works in claude-video

The Whisper API fallback logic in claude-video prioritizes Groq over OpenAI by checking for GROQ_API_KEY first before falling back to OPENAI_API_KEY, with both discovered from environment variables or .env files.

The claude-video project implements an intelligent backend selection system for speech-to-text transcription. Located in skills/watch/scripts/whisper.py, this logic ensures seamless operation even when one provider's credentials are unavailable.

How the Fallback Mechanism Works

The transcribe_video function orchestrates backend selection. When no explicit backend is provided, it delegates discovery to load_api_key() (source, source).

The Priority Order: Groq First, OpenAI Second

The load_api_key function defines candidate backends as an ordered list:

# From skills/watch/scripts/whisper.py, lines 93-99

candidates = [
    ("GROQ_API_KEY", "groq"),      # Checked first

    ("OPENAI_API_KEY", "openai"),  # Fallback

]

This ordering guarantees Groq → OpenAI precedence. The function iterates through candidates, probing:

• Environment variables (os.environ)
• ~/.config/watch/.env
• Local .env file in the working directory

The first match wins. If GROQ_API_KEY exists anywhere in these locations, Groq is selected immediately. Only when Groq is absent does the system evaluate OpenAI credentials.

When No Keys Are Found

If neither key is discovered, load_api_key returns (None, None). The transcribe_video function then aborts with a setup message directing the user to configure their environment.

Overriding Automatic Selection

Users can bypass the automatic Whisper API fallback logic entirely via two mechanisms:

Command-Line Flag

# Force OpenAI despite having Groq key available

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

Direct Function Parameter

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

segments, backend_used = whisper.transcribe_video(
    video_path="example.mp4",
    audio_out=Path("audio.mp3"),
    backend="openai"  # Explicit choice ignores key discovery

)

Practical Code Examples

Automatic Groq Selection

# Environment: GROQ_API_KEY=abc123 (OPENAI_API_KEY may or may not exist)

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

segments, backend_used = whisper.transcribe_video(
    video_path="interview.mp4",
    audio_out=Path("interview.mp3")
)
assert backend_used == "groq"  # Groq prioritized

Automatic OpenAI Fallback

# Environment: Only OPENAI_API_KEY=def456 set (no GROQ_API_KEY)

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

segments, backend_used = whisper.transcribe_video(
    video_path="lecture.mp4",
    audio_out=Path("lecture.mp3")
)
assert backend_used == "openai"  # Falls back when Groq unavailable

Key Source Files

File	Purpose
skills/watch/scripts/whisper.py	Core transcription logic with load_api_key() and transcribe_video()
skills/watch/scripts/config.py	Configuration defaults and path constants
tests/test_whisper.py	Test coverage for fallback behavior
skills/watch/SKILL.md	/watch slash-command interface specification

Summary

• Priority order is hardcoded: Groq always precedes OpenAI in skills/watch/scripts/whisper.py
• Discovery sources: Environment variables and two .env file locations
• Override capability: --backend CLI flag or backend= parameter bypasses automatic selection
• Graceful failure: Clear error message when no API keys are configured

Frequently Asked Questions

Why does claude-video prioritize Groq over OpenAI for Whisper transcription?

The candidate list in load_api_key places ("GROQ_API_KEY", "groq") first at lines 93-99 of skills/watch/scripts/whisper.py. This design choice likely reflects Groq's competitive pricing or latency advantages for inference workloads, though the repository does not explicitly document the rationale.

How can I force OpenAI when both API keys are present?

Pass --backend openai on the command line or supply backend="openai" as a keyword argument to transcribe_video. Either approach skips the load_api_key discovery logic entirely and uses your specified provider.

What .env file locations does the fallback check?

The load_api_key function examines ~/.config/watch/.env first, then a local .env in the current working directory. It also checks os.environ for directly exported variables. The search stops at the first valid key found.

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