# How to Configure Xiaoyuzhou Podcast Transcription with the Groq API in Agent Reach

> Easily configure Xiaoyuzhou podcast transcription with the Groq API in Agent Reach. Set your Groq API key, install dependencies, and transcribe podcasts efficiently.

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

---

**Configure the Groq API key via `agent-reach configure groq-key <key>` or set the `GROQ_API_KEY` environment variable, ensure `ffmpeg` is installed, and install the Xiaoyuzhou transcription script with `agent-reach install --env=auto` to transcribe podcasts from xiaoyuzhoufm.com using Groq's Whisper model.**

The **Agent-Reach** repository provides automated podcast transcription capabilities for Xiaoyuzhou (小宇宙) via the Groq API. To enable this functionality, you must satisfy three prerequisite checks implemented in the Xiaoyuzhou channel handler. This guide walks you through configuring the Xiaoyuzhou podcast transcription with the Groq API using the source code from `Panniantong/Agent-Reach`.

## Prerequisites Check in the Xiaoyuzhou Channel

The Xiaoyuzhou channel implementation in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) enforces three mandatory checks before allowing transcription operations.

### Verify ffmpeg Installation

The channel requires `ffmpeg` for audio conversion. In [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) lines 24-36, the code probes for the `ffmpeg` executable using `probe_command("ffmpeg", ["-version"], ...)` and raises an error if the binary is not found in your system path.

### Install the Transcription Helper Script

The channel looks for a helper script at `~/.agent-reach/tools/xiaoyuzhou/transcribe.sh` (verified in lines 38-45 of [`xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaoyuzhou.py)). Install this dependency using the built-in installer:

```bash
agent-reach install --env=auto

```

This command copies the shell wrapper that streams audio chunks to the Groq API endpoint into the expected location.

## Configure the Groq API Key

The Xiaoyuzhou channel authenticates with Groq using either an environment variable or the Agent-Reach configuration file. The credential resolution logic resides in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) lines 47-60, where the code checks `os.environ.get("GROQ_API_KEY")` first, then falls back to `Config().get("groq_api_key")`.

### Method 1: CLI Configuration (Recommended)

Use the built-in `configure` command to persist your API key to the Agent-Reach configuration file:

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

```

This command writes the key to `~/.agent-reach/config.yaml` under the `groq_api_key` field. The CLI handling for this operation is implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) approximately lines 80-110, which invokes the `Config` class from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to persist the value.

### Method 2: Environment Variable

Alternatively, export the key in your shell session:

```bash
export GROQ_API_KEY=gsk_youractualkeyhere

```

The channel handler prioritizes the environment variable over the config file value, as implemented in the conditional logic at lines 47-60 of [`xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaoyuzhou.py).

## Run Xiaoyuzhou Podcast Transcription

Once configured, trigger transcription using the generic `read` command. The URL routing logic in [`xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaoyuzhou.py) lines 16-20 (`can_handle` method) automatically detects xiaoyuzhoufm.com URLs and routes requests to the appropriate channel:

```bash
agent-reach read https://xiaoyuzhoufm.com/episode/12345

```

The workflow proceeds as follows:

1. Validates `ffmpeg` availability via `probe_command`
2. Confirms the transcribe script exists at `~/.agent-reach/tools/xiaoyuzhou/transcribe.sh`
3. Retrieves the Groq API key from your configured source (environment or config)
4. Downloads the podcast audio and invokes the transcription script
5. Returns the transcribed text processed through Groq's Whisper model

## Summary

- **Install dependencies**: Ensure `ffmpeg` is available on your system path (checked in [`xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaoyuzhou.py) lines 24-36)
- **Deploy helper script**: Run `agent-reach install --env=auto` to install `~/.agent-reach/tools/xiaoyuzhou/transcribe.sh` (verified in lines 38-45)
- **Configure API credentials**: Use `agent-reach configure groq-key <key>` to write to `~/.agent-reach/config.yaml` or set the `GROQ_API_KEY` environment variable (logic in lines 47-60)
- **Execute transcription**: Use `agent-reach read <xiaoyuzhou_url>` to automatically route to the Xiaoyuzhou channel (`can_handle` logic in lines 16-20)

## Frequently Asked Questions

### Where does Agent-Reach store the Groq API key?

Agent-Reach stores the key in `~/.agent-reach/config.yaml` under the `groq_api_key` field when configured via the CLI. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) handles reading and writing this YAML file, with fallback to the `GROQ_API_KEY` environment variable if present.

### What happens if ffmpeg is not installed?

The Xiaoyuzhou channel will raise a prerequisite error before attempting transcription. Specifically, the `check` method in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) lines 24-36 probes for the `ffmpeg` executable using `probe_command` and halts execution with a descriptive error message if the binary is missing from your system path.

### Can I use the Groq API without installing the transcribe script?

No. The channel explicitly verifies the existence of `~/.agent-reach/tools/xiaoyuzhou/transcribe.sh` in lines 38-45 of [`xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/xiaoyuzhou.py). This shell wrapper is required to chunk audio files and stream them to the Groq API endpoint; transcription will fail with a file-not-found error if this script is absent.

### How does Agent-Reach know to use the Xiaoyuzhou channel for a specific URL?

The `can_handle` method in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) lines 16-20 inspects the URL string using pattern matching and returns `True` for domains matching xiaoyuzhoufm.com. This enables automatic routing when you execute `agent-reach read <url>`, directing Xiaoyuzhou URLs to the appropriate channel handler.