read-xiaoyuzhou-article

Xiaoyuzhou podcast to article

Turn a Xiaoyuzhou episode link (xiaoyuzhoufm.com/episode/xxx) into:

Verbatim transcript(transcription + Chinese punctuation polishing)
Article(rewritten by Claude from the transcript into a readable article)

How it works

小宇宙链接
  → 抓页面里的音频 CDN 直链（无需登录/API）
  → curl 下载音频
  → ffmpeg 转码压缩（单声道 64k mp3）
  → 按 10 分钟/段切片（避免单段过长导致 Whisper 524 超时）
  → Groq Whisper large-v3 转录（language=zh，带 429/5xx 自动重试）
  → 清洗 Whisper 幻觉噪声（"请点赞订阅"、"字幕由 Amara.org 提供"等）
  → Groq Llama 3.3 70B 补中文标点+分段（可选 --polish）
  → 输出逐字文稿
  → Claude 把文稿编写成文章

Prerequisites

1. Tools(must be available on the command line):curl、ffmpeg、ffprobe、perl、python3

Install ffmpeg on macOS:brew install ffmpeg
If brew is unavailable (e.g. the Xcode license has not been accepted), you can download a static binary and put it in ~/.local/bin/(the script will automatically add that directory to PATH). The arm64 static build can be obtained from osxexperts.net ffmpeg/ffprobe。
The script self-checks dependencies at startup and will directly report whichever is missing.

2. Groq API Key (free)— the transcription step requires it:

Register at https://console.groq.com to get a key starting with gsk_ key at the beginning
Set the environment variable:export GROQ_API_KEY=gsk_xxxxx
If it is not set, the script will report an error when run.

Workflow

Step 1: Confirm the link and polishing option

After the user provides a Xiaoyuzhou episode link, it is enabled by default --polish(punctuation polishing, for a better reading experience).

Step 2: Run the transcription script

GROQ_API_KEY=$GROQ_API_KEY bash ~/.claude/skills/read-xiaoyuzhou-article/scripts/transcribe.sh \
  --polish "<小宇宙链接>" "/tmp/podcast_transcript.md"

The script will output the verbatim transcript to /tmp/podcast_transcript.md. Read it as the material for the next step.

Transcribing a long podcast may take several minutes (download + transcoding + multiple API calls). If you hit Groq 429 rate limiting, the script will automatically wait and retry.

Step 3: Write it into an article

Read /tmp/podcast_transcript.md, and rewrite the verbatim transcript into a structured article. Requirements:

Preserve the core viewpoints and key information, remove spoken filler, repetition, and interjections ("yeah yeah yeah", "and then", "that one")
Reorganize the structure: state the topic at the beginning → divide themes with subheadings → wrap up at the end
Stay faithful to the original meaning: do not fabricate facts, data, or viewpoints that are not in the transcript
If the guest has memorable quotes, they can be appropriately cited
Mark the source link and podcast title at the beginning of the article

Save the article as /tmp/podcast_article.md, and tell the user the paths of both outputs (transcript + article).

Notes

Only Xiaoyuzhouepisode pages（/episode/) are supported; podcast homepages are not supported.
The direct audio link is extracted from the page HTML by regex media.xyzcdn.net/*.m4a|mp3; if a Xiaoyuzhou redesign causes extraction to fail, the regex in the script needs to be updated.
Transcription uses Groq's free quota; very heavy use may trigger rate limits.
The article rewriting step is done by Claude and does not consume additional API.