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

> Discover how the watch skill in bradautomates/claude-video uses Groq vs OpenAI for Whisper transcription. Experience faster, cheaper audio processing with automatic fallbacks.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: comparison
- Published: 2026-07-09

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) (lines 470-474) supports a `--backend` flag accepting `groq` or `openai`, which overrides automatic detection. Similarly, the main [`watch.py`](https://github.com/bradautomates/claude-video/blob/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:

```bash

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

```bash

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

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`.