# How the Transcribe Command Works with Groq and OpenAI in Agent Reach

> Discover how Agent Reach's transcribe command uses Groq and OpenAI to convert audio to text. It prioritizes Groq's free whisper-large-v3, then falls back to OpenAI's whisper-1.

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

---

**The `transcribe` command in Agent Reach converts audio to text using a provider-agnostic pipeline that automatically tries Groq's free `whisper-large-v3` model first, then falls back to OpenAI's `whisper-1` if authentication fails or errors occur.**

Agent Reach is an open-source automation framework that simplifies audio transcription through a unified interface supporting multiple AI providers. The **`transcribe`** command—available both as a CLI tool and a Python API—handles everything from audio downloading and compression to provider authentication and error recovery. This article examines the implementation details in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) and [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to show how the system orchestrates Groq and OpenAI Whisper services.

## Architecture of the Transcribe Pipeline

The transcription workflow consists of three distinct layers: the CLI parser, the public Python API, and the provider-specific HTTP handlers.

### CLI Entry Point

User interaction begins in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), where the `_cmd_transcribe` function (lines 1135–1142) parses command-line arguments and forwards them to the core library. This thin wrapper validates that the source path or URL exists before delegating to the transcription engine.

### Core API Function

The public interface lives in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) via the `transcribe(source, *, provider="auto", …)` function (lines 8–13). This orchestrator manages the entire lifecycle: input validation, audio preprocessing, provider selection, and result aggregation. It returns a single string containing the complete transcript.

### Provider Configuration

A static `PROVIDERS` dictionary (lines 32–43) defines the supported backends. Each entry maps the provider name to its API endpoint, model identifier (`whisper-large-v3` for Groq, `whisper-1` for OpenAI), and the configuration key used to retrieve API tokens from the system's config store.

## Provider Selection and Automatic Fallback

Agent Reach eliminates provider lock-in through an intelligent routing system that prioritizes cost-effective options while ensuring reliability.

### The Auto-Detection Logic

The helper `_provider_order(provider)` (lines 49–55) determines execution order. When `provider="auto"` (the default), it returns `["groq", "openai"]`, ensuring Groq's free tier is attempted first. If the user specifies a provider explicitly (e.g., `provider="openai"`), the function returns a single-item list containing only that provider, bypassing the fallback mechanism.

### Chunk-Level Fallback Strategy

For each audio segment, `_transcribe_with_fallback(chunk, order, config)` (lines 306–318) iterates through the ordered provider list. It calls `transcribe_chunk` for each candidate until one succeeds. If all providers return errors, the function raises the last encountered `TranscribeError`, ensuring the user receives actionable diagnostic information.

The actual HTTP request occurs in `transcribe_chunk`, which constructs a multipart form-data POST containing the audio bytes, model identifier, and a request for plain-text output. The function retrieves API keys via the configuration system and validates that responses return HTTP 2xx status codes before extracting the transcript text.

## Audio Processing Pipeline

Before any network request, the system ensures audio files meet Whisper's 25 MiB size limit and format requirements.

### Download and Validation

For remote sources, `download_audio` pulls the file using **yt-dlp**. Immediately afterward, `_assert_safe_public_url` (lines 102–123) validates URLs to prevent Server-Side Request Forgery (SSRF) attacks by blocking private IP ranges, localhost, and non-HTTP(S) schemes.

### Compression and Chunking

The `compress_audio` function forces mono channel, 16 kHz sample rate, and 32 kbps m4a encoding using **ffmpeg**. If the compressed file still exceeds 25 MiB, `chunk_audio` splits it into segments of approximately 10 minutes or less, ensuring each piece complies with API limits while maintaining temporal continuity for accurate transcription.

## Using the Transcribe Command

You can interact with the transcription engine through the Python API or the command line.

### Python API Examples

Use the `transcribe` function directly for programmatic access with automatic fallback:

```python
from agent_reach.transcribe import transcribe

# Automatically tries Groq first, then OpenAI if needed

text = transcribe("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(text)

```

To force a specific provider and handle configuration errors explicitly:

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

try:
    # Explicitly request OpenAI; raises NoProviderConfigured if key missing

    text = transcribe("audio.mp3", provider="openai")
except NoProviderConfigured as e:
    print("Configure your OpenAI key first:", e)

```

### CLI Usage

Transcribe a remote URL with automatic provider selection:

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

```

Save output to a file instead of stdout:

```bash
agent-reach transcribe audio.m4a -o transcript.txt

```

## Summary

- **Provider-agnostic design**: The `transcribe` command abstracts Groq and OpenAI behind a unified interface, routing requests through [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py).
- **Automatic fallback**: Groq's `whisper-large-v3` is prioritized over OpenAI's `whisper-1` when `provider="auto"`, with automatic retry logic handled by `_transcribe_with_fallback`.
- **Audio preprocessing**: The pipeline automatically downloads, compresses (via ffmpeg), and chunks audio to meet the 25 MiB API limit.
- **Security**: URL inputs are validated by `_assert_safe_public_url` to prevent SSRF attacks.
- **Flexible interface**: Available as both a CLI command (`agent-reach transcribe`) and a Python function (`transcribe(source, provider="auto")`).

## Frequently Asked Questions

### What happens if both Groq and OpenAI fail?

If Groq returns an error (including authentication failures) and OpenAI also fails, the `_transcribe_with_fallback` function raises the last `TranscribeError` encountered. This ensures the user receives the specific error message from the final provider attempted, making debugging straightforward.

### How does Agent Reach handle large audio files?

The system automatically compresses audio to mono, 16 kHz, 32 kbps m4a format using ffmpeg. If the file still exceeds 25 MiB after compression, the `chunk_audio` function splits it into ≤10-minute segments. Each chunk is transcribed sequentially and concatenated into a single result string.

### Can I force the transcribe command to use only OpenAI?

Yes. Pass `provider="openai"` to the Python API or use the `--provider openai` flag in the CLI. When specified, the `_provider_order` function returns only that provider, skipping Groq entirely and raising `NoProviderConfigured` if the OpenAI API key is not set in the configuration.

### Is it safe to transcribe arbitrary URLs?

Agent Reach validates all URLs through `_assert_safe_public_url`, which blocks private IP addresses, localhost, and non-HTTP(S) schemes to prevent SSRF attacks. Only public internet resources reachable via standard web protocols are processed, ensuring the `transcribe` command cannot be used to probe internal network infrastructure.