# How to Use the Transcribe Command with Groq or OpenAI Whisper in Agent Reach

> Learn to use the transcribe command in Agent Reach with Groq or OpenAI Whisper. Automate transcription with this powerful tool.

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

---

**Agent Reach's `transcribe` command automatically selects Groq's free `whisper-large-v3` model and falls back to OpenAI's `whisper-1` when needed.**

Agent Reach is a Python-based CLI and library designed to give AI agents unified access to internet platforms. The **transcribe** command converts any audio or video URL—or local media file—into text using Whisper-compatible APIs. According to the Panniantong/Agent-Reach source code, the implementation prioritizes **Groq** for cost-free transcription with seamless **OpenAI** fallback for reliability.

## Setting Up API Keys for the Transcribe Command

Before running the transcribe command, you must configure at least one provider API key in `~/.agent-reach/config.yaml`.

```bash

# Create the config directory and file

mkdir -p ~/.agent-reach
cat > ~/.agent-reach/config.yaml << 'EOF'
groq_api_key: "gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
openai_api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
EOF

```

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) retrieves these keys at runtime. If no valid provider is configured, the system raises `NoProviderConfigured`—a custom exception defined in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py).

## CLI Usage: Transcribe Command with Groq or OpenAI Whisper

### Basic Transcription with Auto Provider Selection

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

```

This command executes the following pipeline as implemented in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py):

1. **URL validation** – `_assert_safe_public_url` ensures the source is public-only (prevents SSRF attacks)
2. **Media download** – `download_audio` invokes `yt-dlp` to fetch the audio stream
3. **Compression** – `compress_audio` re-encodes to mono 16kHz, 32kbps m4a to fit Whisper's 25 MiB limit
4. **Chunking** – Files exceeding 24 MiB are split into ≤10-minute segments via `ffmpeg`
5. **Transcription** – `_transcribe_with_fallback` tries Groq first, then OpenAI

The `_cmd_transcribe` function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handles argument parsing and forwards to this engine.

### Force Specific Provider Selection

```bash

# Skip Groq and use OpenAI directly

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

```

The `--provider` flag accepts three values:

- `auto` (default): Groq → OpenAI fallback order
- `groq`: Groq only, no fallback
- `openai`: OpenAI only, no fallback

The `_provider_order` function in [`transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.py) expands `auto` to `["groq", "openai"]` for sequential retry.

## Python Library: Transcribe with Groq or OpenAI Whisper Programmatically

### Simple API Call

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

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

        provider="auto",                   # Groq → OpenAI fallback

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

```

The `transcribe` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) wraps the full pipeline: download, compress, chunk, and transcribe with fallback logic.

### Advanced: Custom Chunk Size and Direct Chunk Processing

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

# Download and prepare media

src = download_audio("https://example.com/long-audio.mp3", Path("/tmp"))
compressed = compress_audio(src, Path("/tmp"))

# Split into 5-minute chunks instead of default 10-minute

chunks = chunk_audio(compressed, Path("/tmp"), segment_seconds=300)

# Transcribe each chunk with explicit provider

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

```

The `transcribe_chunk` function performs the actual HTTP POST to the provider endpoint using `requests`, with the appropriate bearer token from your config.

## Provider Configuration and Fallback Architecture

The `PROVIDERS` dictionary at the top of [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) defines endpoint and model mappings:

| Provider | Model | Endpoint |
|----------|-------|----------|
| **Groq** | `whisper-large-v3` | `https://api.groq.com/openai/v1/audio/transcriptions` |
| **OpenAI** | `whisper-1` | `https://api.openai.com/v1/audio/transcriptions` |

When `_transcribe_with_fallback` encounters a failure from Groq—quota exhaustion, rate limiting, or service error—it automatically retries with OpenAI. This resilience is hardcoded for `provider="auto"`.

## Required External Dependencies

The transcribe command requires these binaries on your system:

- **`yt-dlp`** – Media download from YouTube and other platforms
- **`ffmpeg`** – Audio re-encoding and chunking

Verify installation with:

```bash
agent-reach doctor

```

The [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) module diagnoses missing dependencies before you attempt transcription.

## Error Handling for the Transcribe Command

Agent Reach implements granular exceptions in [`transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.py):

| Exception | Trigger |
|-----------|---------|
| `NoProviderConfigured` | Missing API keys for requested provider |
| `MissingDependency` | `yt-dlp` or `ffmpeg` not found in PATH |
| `TranscribeError` | General transcription failure (network, API error, invalid source) |
| `UnsafeUrlError` | URL failed public-only safety validation |

Wrap your calls in `try/except TranscribeError` to handle all failure modes gracefully.

## Summary

- The **transcribe command** in Agent Reach prioritizes **Groq's free `whisper-large-v3`** with automatic **OpenAI `whisper-1` fallback**.
- Configure API keys in `~/.agent-reach/config.yaml` before use.
- The CLI entry point is `_cmd_transcribe` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py); the engine lives in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py).
- The pipeline handles download (`yt-dlp`), compression (`ffmpeg`), chunking, and provider failover automatically.
- Use `provider="auto"` for resilience, or specify `"groq"` or `"openai"` explicitly for predictable costs.

## Frequently Asked Questions

### Do I need both Groq and OpenAI API keys to use the transcribe command?

No. You only need at least one configured provider. Configure Groq for free transcription, OpenAI as a paid backup, or both for automatic failover. If neither is configured, Agent Reach raises `NoProviderConfigured` before attempting any download.

### Why does my transcription fail with "MissingDependency: ffmpeg"?

The transcribe command requires `ffmpeg` for audio compression and chunking. Install it system-wide (`apt install ffmpeg`, `brew install ffmpeg`, etc.) and verify with `agent-reach doctor`. The `compress_audio` and `chunk_audio` functions in [`transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.py) shell out to `ffmpeg` directly.

### How does Agent Reach handle large files that exceed Whisper's 25 MiB limit?

Files are automatically compressed to mono 16kHz, 32kbps m4a. If still over 24 MiB, `chunk_audio` splits them into segments (default 10 minutes, configurable) using `ffmpeg -f segment`. Each chunk is transcribed independently and concatenated with newlines in the final output.