# How to Set Up Xiaoyuzhou Podcast Transcription with Whisper in Agent Reach

> Learn to set up Xiaoyuzhou podcast transcription with Whisper using Agent Reach. Integrate seamless speech-to-text conversion for your audio content.

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

---

**Agent Reach enables Xiaoyuzhou podcast transcription by routing episode URLs through the `XiaoyuzhouChannel`, which validates ffmpeg and Groq API credentials before orchestrating audio download and Whisper-based speech-to-text conversion via the bundled [`transcribe.sh`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.sh) script.**

Agent Reach treats every external service as a **channel** that adheres to a common contract defined in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py). The `XiaoyuzhouChannel` implementation handles the Xiaoyuzhou Podcast platform specifically, leveraging Groq's hosted Whisper API (`large-v3`) and a local ffmpeg pipeline to convert Chinese podcast episodes into readable text without requiring local GPU resources or model files.

## Architecture and Prerequisites

When a user supplies a Xiaoyuzhou episode URL, the dispatcher in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) selects `XiaoyuzhouChannel` because its `can_handle(url)` method matches the domain `xiaoyuzhoufm.com`. Before transcription begins, the channel's `check` method validates three prerequisites:

- **ffmpeg** is installed and executable for audio download, re-encoding, and segmentation.
- The helper script `~/.agent-reach/tools/xiaoyuzhou/transcribe.sh` exists and is runnable.
- A **Groq API key** is available via the `GROQ_API_KEY` environment variable or the `~/.agent-reach/config.json` configuration file.

If any check fails, the channel reports a status (`off`, `warn`, or `error`) with diagnostic messages. Once validation succeeds, `self.active_backend` is set to `"groq-whisper"` and the channel is ready to process audio.

## Step-by-Step Setup

### Install Agent Reach and Dependencies

Install the package using `pipx` and run the environment setup to automatically download the transcribe script and verify dependencies:

```bash
pipx install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto

```

The `--env=auto` flag creates the `~/.agent-reach/tools/xiaoyuzhou/` directory and installs the [`transcribe.sh`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.sh) script that orchestrates the ffmpeg-to-Whisper pipeline.

### Verify ffmpeg Installation

Run the doctor command to ensure ffmpeg is detected by the channel's probe logic:

```bash
agent-reach doctor | grep xiaoyuzhou

```

This executes `probe_command("ffmpeg")` inside `XiaoyuzhouChannel.check` (lines 24–63 in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py)). You should see an "ok" status indicating the ffmpeg binary is present and executable.

### Configure Groq API Authentication

Store your Groq API key to enable remote Whisper inference. Agent Reach checks for credentials in the following order:

1. Environment variable `GROQ_API_KEY`
2. Configuration file at `~/.agent-reach/config.json`

To persist the key in the config file, run:

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

```

The channel reads this value via `Config().get("groq_api_key")` in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). Because Groq hosts the `large-v3` Whisper model remotely, no local model download is required—only network access and a valid API key.

## How to Transcribe Xiaoyuzhou Episodes

### Command-Line Transcription

Invoke the bundled shell script directly with a Xiaoyuzhou episode URL. The script uses ffmpeg to fetch and slice the audio, then streams chunks to Groq's `/v1/audio/transcriptions` endpoint:

```bash
bash ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh \
    https://www.xiaoyuzhoufm.com/episode/EPISODE_ID

```

The script concatenates the returned Chinese text segments and outputs the full transcript to STDOUT.

### Programmatic Access via Python

For automated workflows, use the Agent Reach Python API to trigger the channel's `read` method:

```python
from agent_reach.core import AgentReach

ar = AgentReach()
transcript = ar.read("https://www.xiaoyuzhoufm.com/episode/EPISODE_ID")
print(transcript)

```

This call routes the URL to `XiaoyuzhouChannel`, executes the prerequisite checks, runs the ffmpeg-to-Whisper pipeline, and returns the complete transcript as a string.

## Summary

- **Channel Architecture**: Agent Reach uses `XiaoyuzhouChannel` in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) to handle `xiaoyuzhoufm.com` URLs, implementing the `can_handle`, `check`, and `read` contract methods.
- **Prerequisites**: Valid ffmpeg installation, the [`transcribe.sh`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.sh) script at `~/.agent-reach/tools/xiaoyuzhou/transcribe.sh`, and a Groq API key stored in `~/.agent-reach/config.json` or the `GROQ_API_KEY` environment variable.
- **Backend**: Transcription uses Groq's hosted Whisper API (`large-v3`), eliminating the need for local GPU resources or model files.
- **Execution**: Use either the shell script directly for CLI workflows or `AgentReach().read()` for Python-based automation.

## Frequently Asked Questions

### Do I need to download Whisper models locally?

No. Agent Reach uses **Groq's hosted Whisper API** (`large-v3`) rather than running inference locally. The [`transcribe.sh`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.sh) script sends audio chunks to Groq's `/v1/audio/transcriptions` endpoint, so you only need a valid API key and network access—no GPU or model storage required.

### Why does the setup require ffmpeg?

The `XiaoyuzhouChannel` relies on ffmpeg for three critical operations: downloading the episode audio from Xiaoyuzhou's streaming servers, re-encoding it to the format required by Groq's API, and segmenting long episodes into chunks that respect the Whisper API's size limits. The `check` method in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) explicitly verifies ffmpeg is executable before allowing transcription.

### Where is the transcribe script installed?

The script is installed at `~/.agent-reach/tools/xiaoyuzhou/transcribe.sh` when you run `agent-reach install --env=auto`. This location is hardcoded in the channel's validation logic and is separate from the Python package installation to allow user-level customization if needed.

### How does Agent Reach know to use the XiaoyuzhouChannel for a URL?

The dispatcher in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) iterates through available channels and calls `XiaoyuzhouChannel.can_handle(url)`, which returns `True` when the URL domain matches `xiaoyuzhoufm.com`. This automatic routing ensures that Xiaoyuzhou URLs trigger the correct ffmpeg-to-Whisper pipeline without manual channel selection.