How the Watch Skill Integrates Groq vs OpenAI for Whisper Transcription in bradautomates/claude-video

The watch skill automatically prefers the Groq Whisper API for faster, cheaper transcription but seamlessly falls back to OpenAI when only an OpenAI key is present, using pure standard-library Python to route requests based on environment variables and an optional --backend flag.

The watch skill in the bradautomates/claude-video repository provides a lightweight, dependency-free solution for transcribing video audio using OpenAI's Whisper models. Located in skills/watch/scripts/whisper.py, the module implements a dual-backend architecture that switches between Groq and OpenAI endpoints without requiring external SDKs. Understanding how this integration works allows you to configure the optimal transcription pipeline for your specific API access and cost requirements.

Backend Endpoints and Model Configuration

According to the source code in skills/watch/scripts/whisper.py, lines 29-34 define distinct HTTP endpoints and model identifiers for each provider:

• Groq: Uses https://api.groq.com/openai/v1/audio/transcriptions with model whisper-large-v3
• OpenAI: Uses https://api.openai.com/v1/audio/transcriptions with model whisper-1

These constants drive all subsequent request construction, ensuring the correct endpoint receives the audio payload with the appropriate model parameter.

API Key Discovery and Selection Logic

The load_api_key(preferred=None) function (lines 93-100) implements the selection hierarchy. It searches for credentials in two locations: ~/.config/watch/.env and a .env file in the current working directory.

The function checks for GROQ_API_KEY and OPENAI_API_KEY environment variables. When called without a preferred argument, it defaults to Groq if that key exists, falling back to OpenAI only when Groq is unavailable. If you specify preferred="groq" or preferred="openai", the function validates only that specific key and raises an error if missing.

Chunking Strategy for Large Audio Files

Both services enforce a 25 MiB upload limit. The script defines MAX_UPLOAD_BYTES = 24 * 1024 * 1024 (24 MiB) as a safety margin and uses plan_chunks() (lines 35-62) to slice large audio files into compliant segments. Each chunk is uploaded independently through the selected backend, with transcripts concatenated to preserve the original temporal structure expected by downstream processing.

HTTP Request Execution with Standard Library

The module avoids third-party dependencies by using urllib.request for all HTTP operations. When backend == "groq", the code constructs a POST request to the Groq endpoint with Authorization: Bearer <GROQ_API_KEY>; otherwise, it targets the OpenAI endpoint with Authorization: Bearer <OPENAI_API_KEY> (lines 205-215). This approach keeps the skill lightweight while maintaining full compatibility with both APIs.

Command-Line Interface and Backend Overrides

The transcription driver exposes the dual-backend capability through the command line. The entry point in whisper.py (lines 470-474) supports a --backend flag accepting groq or openai, which overrides automatic detection. Similarly, the main watch.py driver presents an interactive prompt with choices=["groq", "openai"] (lines 59-60), allowing explicit backend selection during video processing.

Practical Code Examples

Automatic Backend Selection

Configure a Groq API key to enable automatic preference:

# Create environment file

echo "GROQ_API_KEY=gsk_xxxxxxxx" > ~/.config/watch/.env

# Run transcription (auto-selects Groq)

watch https://example.com/video.mp4

Force OpenAI Backend

Explicitly request OpenAI even if Groq credentials exist:

# With OPENAI_API_KEY set in environment

watch https://example.com/video.mp4 --backend openai

Programmatic Backend Detection

Use the internal helper to validate credentials in your own scripts:

from skills.watch.scripts.whisper import load_api_key

backend, api_key = load_api_key(preferred="groq")
print(f"Selected backend: {backend}")  # Outputs: groq

Summary

• The watch skill defaults to Groq for Whisper transcription due to cost and speed advantages, but automatically falls back to OpenAI when only that key is available.
• Configuration relies on standard .env files containing GROQ_API_KEY or OPENAI_API_KEY, checked in ~/.config/watch/.env or the current directory.
• Audio files exceeding 24 MiB are automatically chunked using plan_chunks() to satisfy upload limits without external dependencies.
• All HTTP requests use urllib.request from the Python standard library, targeting Groq's whisper-large-v3 or OpenAI's whisper-1 models.
• Override automatic selection using the --backend CLI flag or the interactive prompt in watch.py.

Frequently Asked Questions

How does the watch skill decide which Whisper API to use?

The decision flows through load_api_key() in skills/watch/scripts/whisper.py. If GROQ_API_KEY exists in the environment, Groq is selected automatically. If only OPENAI_API_KEY is present, it falls back to OpenAI. You can force a specific provider by passing preferred="groq" or preferred="openai" to the function, or using the --backend command-line flag.

What file size limits apply to audio uploads?

Both Groq and OpenAI enforce a 25 MiB maximum upload size. The script sets a conservative MAX_UPLOAD_BYTES of 24 MiB and uses the plan_chunks() function to split larger audio files into sequential chunks that are transcribed individually and reassembled.

Can I use this without installing external SDKs?

Yes. The integration relies entirely on Python's standard library (urllib.request for HTTP, os and pathlib for environment management). No openai or groq pip packages are required, making the skill lightweight and portable across environments.

Where should I store my API keys?

Keys are loaded from .env files located in either ~/.config/watch/.env (user-wide configuration) or the current working directory (project-specific). The load_api_key() function checks these locations in order for variables named GROQ_API_KEY and OPENAI_API_KEY.

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