# How the Agent-Reach Transcribe Command Uses Groq and OpenAI Whisper Providers

> Discover how Agent-Reach's transcribe command leverages Groq and OpenAI Whisper with provider-agnostic orchestration and automatic fallback for reliable audio transcription.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-17

---

**The transcribe command routes audio transcription through Groq and OpenAI Whisper APIs using a provider-agnostic orchestration layer that automatically falls back from Groq to OpenAI when errors occur.**

The `transcribe` command in the Agent-Reach repository converts audio files or URLs into text by leveraging Whisper-compatible APIs from Groq and OpenAI. This implementation follows a robust provider-routing strategy that prioritizes cost-effective transcription while ensuring reliability through automatic fallback mechanisms.

## Provider Architecture and Routing Logic

The transcription system maintains a static registry of supported providers and implements dynamic selection logic to determine which API to call.

### The Provider Catalog

In [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), the `PROVIDERS` dictionary (lines 30-40) defines the endpoint URLs, model names, and configuration keys for each vendor. This catalog enables the system to treat Groq and OpenAI as interchangeable transcription backends while maintaining their specific API requirements.

### Dynamic Provider Selection

The `_provider_order` helper function translates user input into an ordered list of providers. When the CLI receives `--provider auto` (the default), the function returns `["groq", "openai"]`, prioritizing Groq's typically faster and cheaper Whisper implementation (lines 99-104). Users can override this by specifying `--provider groq` or `--provider openai` to force a single vendor.

## Transcription Workflow and Fallback Strategy

The command processes audio through a multi-stage pipeline that handles large files via chunking and implements resilient error handling across providers.

### Input Processing and Chunking

Before sending data to any API, the system downloads remote audio using **yt-dlp**, compresses it to Whisper-friendly formats with **ffmpeg**, and splits files exceeding the 24 MiB Whisper limit into segments of 10 minutes or less (lines 77-91). This preprocessing ensures compatibility with both Groq and OpenAI's file size constraints.

### The Fallback Mechanism

The `_transcribe_with_fallback` function implements the core resilience logic (lines 49-70). It iterates through the provider list established by `_provider_order`, skipping any provider lacking a configured API key. The function attempts transcription with each available provider in sequence, returning the first successful response or re-raising the final exception if all providers fail.

### Individual Chunk Transcription

For each audio chunk, `transcribe_chunk` constructs a multipart POST request containing the audio file, the selected Whisper model, and an `Authorization: Bearer <API-key>` header (lines 71-89). The function enforces a default 120-second timeout per chunk and wraps HTTP errors or non-200 status codes in a `TranscribeError` for consistent error handling.

## Configuration and API Key Validation

The system validates API key availability before processing audio. In [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 22-26), the function checks `Config` for at least one valid provider key, raising `NoProviderConfigured` if neither Groq nor OpenAI credentials are present. This early validation prevents wasted computation on audio preprocessing when transcription is impossible.

## CLI Usage and Programmatic Integration

The CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 1113-1120) forwards arguments to the library function, handling output formatting and file writing.

**Auto-select provider (Groq preferred):**

```bash
agent-reach transcribe "https://www.youtube.com/watch?v=example"

```

**Force specific provider:**

```bash
agent-reach transcribe "https://example.com/podcast.mp3" --provider groq

```

**Programmatic usage with error handling:**

```python
from agent_reach.transcribe import transcribe, TranscribeError

try:
    text = transcribe("https://youtu.be/example")
    print(text)
except TranscribeError as exc:
    print(f"Transcription failed: {exc}")

```

**Direct provider bypass (advanced):**

```python
from agent_reach.transcribe import transcribe_chunk, Config
from pathlib import Path

cfg = Config()
chunk_path = Path("chunk_001.m4a")
groq_text = transcribe_chunk(chunk_path, "groq", config=cfg)
print(groq_text)

```

## Summary

- The `transcribe` command uses a provider-agnostic architecture defined in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) to abstract Groq and OpenAI Whisper implementations.
- Provider selection follows a priority order (Groq first, then OpenAI) when using `--provider auto`, with fallback logic in `_transcribe_with_fallback`.
- Audio preprocessing includes yt-dlp downloading, ffmpeg compression, and intelligent chunking to respect the 24 MiB API limits.
- API keys are validated early against the `Config` class to prevent unnecessary processing, raising `NoProviderConfigured` when credentials are missing.
- Each chunk is transmitted via multipart POST with Bearer authentication and 120-second timeouts, with errors normalized to `TranscribeError`.

## Frequently Asked Questions

### What happens if both Groq and OpenAI API keys are configured?

When both keys are present and `--provider auto` is used (the default), the system attempts transcription with Groq first. Only if Groq returns an error or timeout does it fall back to OpenAI. If Groq succeeds, OpenAI is never called for that specific chunk.

### Can I use the transcribe function without the CLI?

Yes. Import `transcribe` from `agent_reach.transcribe` to use the function programmatically. The function accepts file paths, URLs, and optional parameters for output directory and provider selection, returning the complete transcript as a string.

### Why does the command split audio into chunks?

Both Groq and OpenAI impose a 24 MiB file size limit on Whisper API requests. The transcribe command automatically splits larger files into 10-minute segments using ffmpeg, processes each chunk independently through the provider fallback chain, and concatenates the results with newline separators.

### How does the system handle network timeouts?

The `transcribe_chunk` function implements a default 120-second timeout per chunk. If a provider fails to respond within this window or returns a non-200 HTTP status, the error is caught and wrapped in `TranscribeError`, triggering the fallback to the next configured provider if available.