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

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 script.

Agent Reach treats every external service as a channel that adheres to a common contract defined in 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 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:

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 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:

agent-reach doctor | grep xiaoyuzhou

This executes probe_command("ffmpeg") inside XiaoyuzhouChannel.check (lines 24–63 in 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:

agent-reach configure groq-key gsk_yourkeyhere

The channel reads this value via Config().get("groq_api_key") in 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 ~/.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:

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 to handle xiaoyuzhoufm.com URLs, implementing the can_handle, check, and read contract methods.
• Prerequisites: Valid ffmpeg installation, the 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}