# How to Transcribe Audio or Video with Groq or OpenAI Whisper Using Agent-Reach

> Easily transcribe audio and video using Groq or OpenAI Whisper with Agent-Reach. This powerful tool handles downloads, compression, and provider fallback for seamless transcription.

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

---

**Agent-Reach provides a unified `transcribe()` function that automatically downloads audio from URLs, compresses files exceeding 25 MiB, and transcribes them using Groq's free tier or OpenAI's Whisper API with automatic fallback between providers.**

The `agent_reach` library abstracts the complexity of audio transcription into a fully automated pipeline. It handles media extraction from video platforms, format conversion to Whisper-compatible specifications, and API orchestration, allowing you to transcribe audio or video with Groq or OpenAI Whisper using either a URL or a local file path.

## Prerequisites

Before invoking the transcription pipeline, ensure you have configured API credentials and installed the required system binaries.

**API Key Configuration.** The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) resolves credentials by checking `~/.agent-reach/config.yaml` first, then falling back to environment variables. For Groq, use the key `groq_api_key` (or the environment variable `GROQ_API_KEY`). For OpenAI, use `openai_api_key` (or `OPENAI_API_KEY`). If neither is found, the code raises `NoProviderConfigured` at lines 52-55 of [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py).

**System Dependencies.** The pipeline requires `yt-dlp` for downloading audio from URLs and `ffmpeg` for audio compression. The `_require()` helper at lines 56-62 verifies binary availability at runtime and raises `FileNotFoundError` if either is missing.

## The Transcription Pipeline

The `transcribe()` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) implements an eight-step workflow that prepares arbitrary media sources for Whisper APIs.

### Source Handling and Download

The public `transcribe(source, ...)` interface accepts either a web URL or a local filesystem path. When a URL is provided, `download_audio()` invokes `yt-dlp` to extract the audio track in high-quality M4A format (lines 77-95). This eliminates the need for manual pre-downloading when transcribing YouTube videos, Vimeo links, or other streaming content.

### Audio Compression and Chunking

Raw audio is re-encoded to a Whisper-compatible format via `compress_audio()` at lines 101-123. The function uses `ffmpeg` to produce mono, 16 kHz, 32 kbps output, significantly reducing file size while preserving speech clarity.

Whisper APIs enforce a 25 MiB upload limit. If the compressed file exceeds 24 MiB, `chunk_audio()` (lines 126-154) splits the audio into segments of ≤10 minutes, re-encoding each chunk to the same mono specification. This ensures large files—such as hour-long podcasts or lecture recordings—are processed automatically without manual splitting.

### Provider Selection and API Orchestration

The `provider` parameter controls which Whisper endpoint receives the audio:

- **`provider="auto"`** (default): The module attempts transcription with **Groq** first, then falls back to **OpenAI** if Groq fails (lines 99-104 and 198-204).
- **`provider="groq"`**: Forces the Groq API using model `whisper-large-v3`.
- **`provider="openai"`**: Forces the OpenAI API using model `whisper-1`.

Each chunk is transmitted via `transcribe_chunk()` (lines 81-89), which constructs a multipart HTTP request with the appropriate model name and requests plain-text output. Network or API errors are wrapped in `TranscribeError` (lines 91-93).

### Result Aggregation

Successful transcriptions are stripped of leading/trailing whitespace and concatenated with newline characters (lines 42-46). The final aggregated string is returned as the complete transcript, preserving chronological order from the chunked segments.

## Configuration

Store credentials in `~/.agent-reach/config.yaml` with the following structure:

```yaml
groq_api_key: gsk_...
openai_api_key: sk-...

```

Alternatively, export environment variables before running your script:

```bash
export GROQ_API_KEY="gsk_..."
export OPENAI_API_KEY="sk-..."

```

The configuration loader at lines 69-78 of [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) merges these sources, with YAML values taking precedence over environment variables.

## Usage Examples

### Python API

Transcribe a YouTube video using the automatic provider fallback:

```python
from agent_reach.transcribe import transcribe

text = transcribe(
    "https://www.youtube.com/watch?v=example",
    provider="auto",  # Optional: defaults to "auto"

)
print(text)

```

Force OpenAI Whisper for a local file, skipping Groq:

```python
from agent_reach.transcribe import transcribe

text = transcribe(
    "/path/to/local/file.m4a",
    provider="openai",
)
print(text)

```

### Command Line Interface

The [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) module exposes the same functionality via the terminal:

```bash
python -m agent_reach.cli transcribe \
  --source "https://vimeo.com/12345678" \
  --provider groq

```

## Summary

- **Source flexibility**: Accepts URLs (auto-downloaded via `yt-dlp`) or local audio files.
- **Automatic optimization**: Compresses audio to mono 16 kHz and chunks files >24 MiB into ≤10-minute segments.
- **Provider resilience**: Default `"auto"` mode tries Groq first (free tier) then falls back to OpenAI.
- **Credential management**: Reads from `~/.agent-reach/config.yaml` or environment variables `GROQ_API_KEY` and `OPENAI_API_KEY`.
- **Error handling**: Raises `NoProviderConfigured` for missing keys and `TranscribeError` for API failures.

## Frequently Asked Questions

### What file formats does Agent-Reach support for transcription?

The pipeline accepts any audio or video format that `yt-dlp` can extract or `ffmpeg` can decode, including MP4, MP3, WAV, M4A, and WebM. The `compress_audio()` function automatically converts these to the required 16 kHz mono MP3 before sending to Whisper APIs.

### Why does the transcription fail with a "NoProviderConfigured" error?

This error occurs when neither `groq_api_key` nor `openai_api_key` is found in `~/.agent-reach/config.yaml` and the corresponding environment variables (`GROQ_API_KEY`, `OPENAI_API_KEY`) are unset. Verify your configuration file exists and contains valid credentials, or export the environment variables before execution.

### How does the automatic provider fallback work?

When `provider="auto"`, the `_transcribe_with_fallback()` logic first attempts to send chunks to the Groq API. If Groq returns an error or the request times out, the code catches the exception and retries the same chunk using the OpenAI API. This ensures maximum availability without manual intervention.

### What is the maximum audio length Agent-Reach can process?

There is no explicit duration limit. The `chunk_audio()` function automatically splits audio exceeding 24 MiB into ≤10-minute segments, each under the 25 MiB API limit. This allows processing of multi-hour recordings, with the final transcript concatenating all segments in chronological order.