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

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, the channel executes ffmpeg -version via the probe_command utility (defined in 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:

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

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 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. Without a valid key, the channel emits a warning with registration guidance.

Configure your key using either method:

# 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). The system:

• Probes for ffmpeg using probe_command from 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:

# 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: Defines XiaoyuzhouChannel class with can_handle and check methods
• agent_reach/probe.py: Provides probe_command for external binary verification
• 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
• 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 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 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.

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