# Agent Reach Transcribe Command: Whisper with Groq and OpenAI Fallback

> Master the Agent Reach transcribe command. Effortlessly use Groq's free Whisper with an OpenAI fallback for efficient audio and video transcription. Handles large files securely.

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

---

**Agent Reach's transcribe command automatically routes audio and video transcription requests to Groq's free whisper-large-v3 model, falling back to OpenAI's whisper-1 when Groq fails, while handling large files through intelligent chunking and SSRF-protected downloads.**

Agent Reach is a Python-based CLI tool that provides AI agents with unified access to internet platforms. The **transcribe command** leverages Whisper-compatible APIs to convert audio and video content into text, implementing a robust **Groq to OpenAI fallback** mechanism. This architecture ensures reliable transcription even when primary rate limits or service interruptions occur.

## How the Transcribe Command Works

The transcription pipeline is orchestrated across several modules with clear separation of concerns between CLI parsing, provider selection, and media processing.

### CLI Entry Point and Provider Selection

Command-line arguments are parsed in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) by the `_cmd_transcribe` function, which forwards user inputs to the transcription engine. Users can specify `--provider auto|groq|openai` to control backend selection.

When `provider="auto"` is used (the default), the `_provider_order` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) expands this to `["groq", "openai"]`, establishing the fallback sequence. The `_transcribe_with_fallback` method iterates through this list until transcription succeeds or all providers are exhausted.

### Provider Configuration and API Models

Provider definitions are centralized in the `PROVIDERS` dictionary at the top of [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py). This configuration maps:
- **Groq**: Uses `whisper-large-v3` via Groq's fast inference endpoint
- **OpenAI**: Uses `whisper-1` as the secondary option

The actual HTTP requests occur in `transcribe_chunk`, which uses `requests.post` with the appropriate endpoint, model name, and bearer token retrieved from the configuration.

### Secure Media Processing Pipeline

The pipeline handles both local files and remote URLs through distinct phases:

1. **Safety Validation**: The `_assert_safe_public_url` function prevents SSRF attacks by validating that URLs are public-only before download.
2. **Download**: For remote sources, `download_audio` utilizes `yt-dlp` to fetch media after safety checks pass.
3. **Compression**: `compress_audio` re-encodes media to mono 16 kHz, 32 kbps m4a to ensure the final size fits Whisper's 25 MiB limit.
4. **Chunking**: Files exceeding `SIZE_LIMIT_BYTES` (24 MiB) are split into ≤10-minute segments via `ffmpeg` to comply with API constraints.

## Configuration and Error Handling

### API Key Management

Credentials are retrieved from `~/.agent-reach/config.yaml` through the `Config.get` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). The system validates that at least one provider key exists; otherwise, it raises `NoProviderConfigured`.

### Exception Hierarchy

The module defines granular exceptions near the top of [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) to provide clear failure modes:
- `TranscribeError`: Base exception for transcription failures
- `MissingDependency`: When `yt-dlp` or `ffmpeg` are not installed
- `NoProviderConfigured`: When no API keys are present in the config file

## Usage Examples

### Basic CLI Transcription with Automatic Fallback

```bash
agent-reach transcribe "https://youtu.be/dQw4w9WgXcQ"

```

This command downloads the YouTube video, compresses it, splits it if necessary, contacts Groq first, and automatically falls back to OpenAI if Groq returns an error. The transcript prints to stdout.

### Explicit Provider Selection

```bash

# Force OpenAI only when Groq quota is exhausted

agent-reach transcribe "https://example.com/podcast.mp3" --provider openai -o transcript.txt

```

The transcript is written to [`transcript.txt`](https://github.com/Panniantong/Agent-Reach/blob/main/transcript.txt).

### Python Library Integration

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

try:
    text = transcribe(
        "https://v.redd.it/abcd1234",      # any public media URL

        provider="auto",                   # default – Groq → OpenAI fallback

    )
    print(text)
except TranscribeError as exc:
    print(f"Transcription failed: {exc}")

```

### Custom Chunk Processing (Advanced)

```python
from pathlib import Path
from agent_reach.transcribe import (
    download_audio,
    compress_audio,
    chunk_audio,
    transcribe_chunk,
)

src = download_audio("https://example.com/long-audio.mp3", Path("/tmp"))
compressed = compress_audio(src, Path("/tmp"))
chunks = chunk_audio(compressed, Path("/tmp"), segment_seconds=300)  # 5‑min chunks

texts = [transcribe_chunk(c, "groq") for c in chunks]
full_transcript = "\n".join(texts)
print(full_transcript)

```

## Summary

- Agent Reach provides a **transcribe command** with automatic **Groq to OpenAI fallback** for Whisper transcription, preferring `whisper-large-v3` over `whisper-1`
- The implementation in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) handles media download via `yt-dlp`, compression, and intelligent chunking for files exceeding 24 MiB
- **Security** is enforced through `_assert_safe_public_url` to prevent SSRF attacks before downloading remote content
- Supports both CLI usage via `_cmd_transcribe` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and direct Python library calls with granular exception handling
- Processes large files by splitting into ≤10-minute chunks using `ffmpeg` to comply with API size limits

## Frequently Asked Questions

### What is the default provider order for Agent Reach's transcribe command?

The default order prioritizes **Groq** using the `whisper-large-v3` model, then falls back to **OpenAI's** `whisper-1` when Groq fails. This is determined by the `_provider_order` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), which expands the `auto` setting to `["groq", "openai"]` and guides the `_transcribe_with_fallback` logic.

### How does Agent Reach handle large audio files that exceed API size limits?

Files exceeding `SIZE_LIMIT_BYTES` (24 MiB) are automatically compressed to mono 16 kHz, 32 kbps m4a and split into ≤10-minute chunks using `ffmpeg`. Each chunk is transcribed individually by `transcribe_chunk` and concatenated with newline separators to form the complete transcript.

### Where does Agent Reach store API keys for Groq and OpenAI?

API keys are read from the user's `~/.agent-reach/config.yaml` file through the `Config.get` method in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). If neither provider is configured, the system raises a `NoProviderConfigured` exception before attempting any transcription.

### What security measures prevent malicious URL attacks when transcribing remote content?

The `_assert_safe_public_url` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) validates that supplied URLs are public-only before the `download_audio` function invokes `yt-dlp`. This prevents Server-Side Request Forgery (SSRF) attacks by ensuring agents cannot access internal network resources.