# How to Transcribe Xiaoyuzhou Podcasts with Agent Reach: 3 Prerequisites Explained

> Easily transcribe Xiaoyuzhou podcasts with Agent Reach. Learn the 3 essential prerequisites including ffmpeg, the transcribe.sh script, and your Groq Whisper API key.

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

---

**To transcribe Xiaoyuzhou (小宇宙播客) podcasts with Agent Reach, you must have ffmpeg installed, the transcribe.sh helper script present in `~/.agent-reach/tools/xiaoyuzhou/`, and a valid Groq Whisper API key configured via environment variable or Agent Reach configuration.**

Agent Reach enables automated transcription of Chinese podcasts from the Xiaoyuzhou platform by orchestrating audio processing and speech-to-text APIs. Based on the source code in the Panniantong/Agent-Reach repository, this guide explains the three mandatory components required to enable Xiaoyuzhou podcast transcription with Agent Reach.

## Prerequisites for Xiaoyuzhou Podcast Transcription

Agent Reach requires three distinct components to process Xiaoyuzhou audio streams. The system validates each dependency in the `check` method of `XiaoyuzhouChannel` before attempting transcription.

### FFmpeg Audio Processing

Agent Reach relies on **ffmpeg** to decode, re-encode, and slice podcast streams into chunks compatible with the Whisper model. According to [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py), the channel executes `ffmpeg -version` via the `probe_command` utility (defined in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py)) to verify the binary is available. If ffmpeg is missing, the channel reports "off" or "error" and provides installation instructions.

Install ffmpeg using your package manager:

```bash

# Debian/Ubuntu

sudo apt install -y ffmpeg

# macOS

brew install ffmpeg

```

### Transcription Script Deployment

The transcription workflow depends on a bash wrapper script located at **`~/.agent-reach/tools/xiaoyuzhou/transcribe.sh`**. This script downloads the episode, invokes ffmpeg for audio processing, and streams chunks to the Groq Whisper API. The `check` method in `XiaoyuzhouChannel` verifies the script file exists; if absent, it prompts you to run `agent-reach install --env=auto` or manually copy the file.

Deploy the script using the CLI:

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

```

### Groq Whisper API Key

Authentication requires a **Groq Whisper API key** to access the speech-to-text model. The channel implementation in [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) checks for the `GROQ_API_KEY` environment variable first; if unset, it falls back to `Config().get("groq_api_key")` from [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). Without a valid key, the channel emits a warning with registration guidance.

Configure your key using either method:

```bash

# Environment variable (session-only)

export GROQ_API_KEY="gsk_XXXXXXXXXXXXXXXX"

# Persistent configuration

agent-reach configure groq-key gsk_XXXXXXXXXXXXXXXX

```

## How Agent Reach Validates the Setup

Before processing any URL, Agent Reach performs a validation sequence in the `check` method of `XiaoyuzhouChannel` ([`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py)). The system:

- Probes for ffmpeg using `probe_command` from [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py)
- Verifies the existence of `~/.agent-reach/tools/xiaoyuzhou/transcribe.sh`
- Locates the Groq API key via environment variable or config fallback

Only when all three checks pass does the channel set `self.active_backend = "groq-whisper"` and report status "ok". If any prerequisite is missing, the channel aborts early with a descriptive error, preventing failed transcription attempts.

## Running the Transcription Process

Once prerequisites are satisfied, transcribing a Xiaoyuzhou episode follows this workflow:

1. **URL Detection**: The `can_handle` method in `XiaoyuzhouChannel` identifies Xiaoyuzhou URLs (e.g., `https://www.xiaoyuzhoufm.com/episode/123456`)
2. **Pre-flight Check**: The `check` method validates the three dependencies
3. **Execution**: The `agent_reach.transcribe` function (or CLI shortcut) invokes the transcription script

Execute transcription via CLI:

```bash

# Using the agent-reach CLI

agent-reach transcribe https://www.xiaoyuzhoufm.com/episode/123456

# Direct script invocation (advanced usage)

~/.agent-reach/tools/xiaoyuzhou/transcribe.sh https://www.xiaoyuzhoufm.com/episode/123456

```

The script downloads the episode audio, processes it through ffmpeg into PCM or FLAC chunks, sends each chunk to the Groq Whisper API, and assembles the final transcript to stdout.

## Key Source Files

Understanding the implementation requires familiarity with these specific files in the Panniantong/Agent-Reach repository:

- **[`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py)**: Defines `XiaoyuzhouChannel` class with `can_handle` and `check` methods
- **[`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py)**: Provides `probe_command` for external binary verification
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)**: Handles configuration fallback for the Groq API key
- **`~/.agent-reach/tools/xiaoyuzhou/transcribe.sh`**: The downloaded helper script that orchestrates ffmpeg and API calls

## Summary

- **ffmpeg** must be installed and accessible in your system PATH; Agent Reach verifies this via `probe_command` in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py)
- The **transcribe.sh** script must exist at `~/.agent-reach/tools/xiaoyuzhou/`; install it using `agent-reach install --env=auto`
- A valid **Groq Whisper API key** is required, sourced from either the `GROQ_API_KEY` environment variable or Agent Reach configuration
- Only when all three components pass validation does `XiaoyuzhouChannel` set `self.active_backend = "groq-whisper"` and enable transcription

## Frequently Asked Questions

### What happens if ffmpeg is not installed on my system?

Agent Reach will detect the missing dependency during the `check` method execution and report "off" or "error" status. The system prints installation hints for your operating system and prevents the transcription process from starting, avoiding runtime failures during audio processing.

### How do I obtain a Groq API key for transcription?

You must register for a Groq account and generate an API key from the Groq console. The free tier supports Whisper transcription. Once obtained, store the key using `export GROQ_API_KEY="your_key"` for temporary use or `agent-reach configure groq-key your_key` for persistent storage across sessions.

### Can I modify the transcription script or use a different audio backend?

The [`transcribe.sh`](https://github.com/Panniantong/Agent-Reach/blob/main/transcribe.sh) script at `~/.agent-reach/tools/xiaoyuzhou/` is a bash wrapper that you can examine and modify. However, the channel's `check` method specifically validates this file's existence. To use a different backend, you would need to modify [`agent_reach/channels/xiaoyuzhou.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaoyuzhou.py) to change the `active_backend` assignment and adjust the validation logic accordingly.

### Where does Agent Reach install the transcription tools?

By default, the `agent-reach install --env=auto` command deploys helper scripts to `~/.agent-reach/tools/xiaoyuzhou/`. The channel checks this specific path when verifying prerequisites. You can manually place the script there if you prefer not to use the automated installer.