# Agent-Reach Transcribe Feature: Groq Whisper vs OpenAI Whisper Implementation Guide

> Explore Agent-Reach's transcribe feature. Learn how Groq Whisper and OpenAI Whisper work together, including implementation steps. Optimize your transcription workflow today.

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

---

**TLDR:** Agent-Reach provides a unified transcription pipeline in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) that routes audio to Groq Whisper by default, with automatic fallback to OpenAI Whisper, requiring only API key configuration in `~/.agent-reach/config.yaml`.

The Panniantong/Agent-Reach repository offers a provider-agnostic transcription system that converts audio from YouTube videos or local files into text using either Groq's or OpenAI's Whisper implementations. This article examines the architectural differences between these providers and demonstrates how to configure and invoke the **Agent-Reach transcribe feature** through both Python and CLI interfaces.

## Provider Architecture and Configuration

### The PROVIDERS Registry

At the core of the system lies the **`PROVIDERS`** dictionary defined in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py). This registry maps provider identifiers to their respective API endpoints, model names, and configuration key requirements:

```python
PROVIDERS = {
    "groq": {
        "endpoint": "https://api.groq.com/openai/v1/audio/transcriptions",
        "model": "whisper-large-v3",
        "key_field": "groq_api_key",
    },
    "openai": {
        "endpoint": "https://api.openai.com/v1/audio/transcriptions",
        "model": "whisper-1",
        "key_field": "openai_api_key",
    },
}

```

Each entry specifies the HTTP endpoint for audio transcriptions, the specific model identifier (whisper-large-v3 for Groq, whisper-1 for OpenAI), and the configuration key name used to retrieve the API token.

### Configuration Requirements

The configuration system ([`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)) stores user secrets in `~/.agent-reach/config.yaml`. The **Agent-Reach transcribe feature** requires one or both of these keys:
- `groq_api_key` – Enables Groq Whisper access
- `openai_api_key` – Enables OpenAI Whisper access

The `FEATURE_REQUIREMENTS` map in the configuration module validates that at least one provider is properly configured before allowing transcription operations. The `Config.is_configured` helper method checks for these prerequisites, enabling the YouTube channel to advertise transcription capability only when ready.

## Audio Processing Pipeline

### Download and Compression

When processing URLs (particularly YouTube videos), the `download_audio` function utilizes `yt-dlp` to fetch M4A files. The `compress_audio` function then normalizes audio to mono, 16 kHz, 32 kbps, guaranteeing that files remain under the Whisper 25 MiB limit. This compression step is critical for subsequent API transmission.

### Chunking Strategy

For audio exceeding the 25 MiB limit after compression, the `chunk_audio` function splits files into segments defined by **`CHUNK_SECONDS = 600`** (10 minutes). Each chunk is processed independently by `transcribe_chunk`, with results concatenated using newline characters to form the complete transcript.

## Provider Selection and Fallback Logic

The public `transcribe(source, *, provider="auto", …)` function accepts a `provider` argument that determines routing behavior:

- **`provider="auto"`** (default): Uses the internal `_provider_order` list `["groq", "openai"]`, attempting Groq first due to its free tier and fast inference, then falling back to OpenAI if needed.
- **Explicit selection**: Passing `"groq"` or `"openai"` bypasses the order and targets that specific service.

The `_transcribe_with_fallback` internal method implements the retry logic. If a provider fails (e.g., returns a 429 error), the system silently attempts the next configured provider. If no API keys are configured, the `NoProviderConfigured` exception is raised immediately to prevent unnecessary audio downloads. Other specific exceptions include `TranscribeError` for API failures and `MissingDependency` for missing `ffmpeg` or `yt-dlp` binaries.

## Usage Examples

### Python API

Configure Groq Whisper explicitly:

```python
from agent_reach import transcribe as tr
from agent_reach.config import Config

cfg = Config()
cfg.set("groq_api_key", "YOUR_GROQ_KEY")

text = tr.transcribe(
    "https://youtu.be/abc123",
    provider="groq",
    config=cfg,
)
print(text)

```

Utilize automatic fallback to OpenAI:

```python
cfg.set("openai_api_key", "YOUR_OPENAI_KEY")

# With Groq unavailable, auto mode will try OpenAI directly

text = tr.transcribe("my_podcast.m4a", provider="auto", config=cfg)

```

Handle large files with automatic chunking:

```python

# Files >24 MiB automatically split into 10-minute chunks

transcript = tr.transcribe("large_audio.wav", provider="auto", config=cfg)

```

### CLI Interface

Install optional dependencies:

```bash
pip install "agent-reach[transcribe]"

```

Configure your preferred provider:

```bash
agent-reach configure groq-key YOUR_GROQ_KEY

# or

agent-reach configure openai-key YOUR_OPENAI_KEY

```

Transcribe content:

```bash

# Explicit Groq usage

agent-reach transcribe https://youtu.be/abc123 --provider groq

# Auto-fallback (Groq → OpenAI)

agent-reach transcribe https://youtu.be/abc123

```

## Key Source Files

- **[`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py)** – Core orchestration including download, compression, chunking, provider routing, and fallback logic.
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** – YAML-based configuration management, environment-variable overrides, and feature-requirement mapping.
- **[`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py)** – YouTube channel implementation that checks for `yt-dlp`, `ffmpeg`, and Whisper readiness before delegating to the transcribe orchestrator.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Command-line interface entry point exposing the `transcribe` sub-command and configuration helpers.
- **[`tests/test_transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_transcribe.py)** – Test suite validating provider routing, fallback logic, and chunking workflows.

## Summary

- **Agent-Reach transcribe feature** uses a unified `transcribe()` function that abstracts Groq Whisper and OpenAI Whisper behind a single interface.
- The **`PROVIDERS`** registry in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) defines endpoint URLs, model names (`whisper-large-v3` vs `whisper-1`), and required API keys.
- **Automatic fallback** follows the order Groq → OpenAI when `provider="auto"` is specified, with `_transcribe_with_fallback` handling retry logic.
- The **chunking system** automatically processes files larger than 25 MiB by splitting them into 10-minute segments via `chunk_audio`.
- Configuration requires storing `groq_api_key` or `openai_api_key` in `~/.agent-reach/config.yaml`, validated through `Config.is_configured`.

## Frequently Asked Questions

### How does Agent-Reach decide which Whisper provider to use?

When `provider="auto"` is specified (the default), Agent-Reach consults the internal `_provider_order` list `["groq", "openai"]` and attempts Groq first. If Groq returns an error or lacks configuration, `_transcribe_with_fallback` automatically retries with OpenAI. You can override this by passing `provider="groq"` or `provider="openai"` explicitly.

### What audio file limits does the transcribe feature enforce?

The system enforces a 25 MiB limit per API request. The `compress_audio` function normalizes audio to mono, 16 kHz, 32 kbps to stay under this limit. If compression alone is insufficient, `chunk_audio` splits files into 10-minute segments using `CHUNK_SECONDS = 600`, processing each chunk separately and concatenating results.

### Why does Agent-Reach require both `groq_api_key` and `openai_api_key`?

Neither key is strictly required individually; you only need at least one configured provider to use the transcription feature. However, configuring both enables the **fallback mechanism**, allowing the system to automatically switch to OpenAI Whisper if Groq reaches rate limits or experiences outages. The `NoProviderConfigured` exception prevents execution when neither key is present.

### Where does Agent-Reach store configuration and API keys?

According to the source code in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), the system stores secrets in `~/.agent-reach/config.yaml`. The `Config` class manages these values, supporting direct file edits or programmatic setting via `cfg.set("groq_api_key", "value")`. The `FEATURE_REQUIREMENTS` map validates that required keys exist before attempting expensive audio downloads.