xiaoyuzhou-asr

使用本地 Qwen3-ASR（Metal/CUDA 加速）将小宇宙播客节目转录为文本。

必需服务：该功能不直接调用小宇宙 API。需预先安装并运行一个兼容的 ultrazg/xyz API 服务端。 默认基础 URL 为 http://localhost:23020；可通过环境变量 XYZ_BASE_URL 覆盖。若未运行该服务，则登录、搜索、单集查询及音频 URL 获取等功能均不可用。

前提条件

1. xyz API 服务端 —— 从小宇宙获取单集数据与音频 URL

   git clone https://github.com/ultrazg/xyz.git && cd xyz && go run .
   # 默认端口：23020，可通过 -p 参数修改
   

2. ffmpeg —— 音频格式转换（brew install ffmpeg）
3. Qwen3-ASR 模型 —— 下载（Hugging Face Hub 不提供 tokenizer.json）：

   python3 -c "
   from huggingface_hub import snapshot_download
   snapshot_download('Qwen/Qwen3-ASR-0.6B', local_dir='models/0.6B')
   "
   

4. qwen3-asr-rs —— 从源码构建：

   git clone https://github.com/alan890104/qwen3-asr-rs.git && cd qwen3-asr-rs
   cargo build --release --example local_transcribe
   

5. tokenizer.json —— 首次运行转录脚本时自动从 vocab.json 与 merges.txt 生成，无需手动操作。

快速开始

# 1. 登录（仅首次需要，凭证保存至 ~/.xiaoyuzhou-asr.json）
python3 scripts/transcribe_podcast.py --login

# 2. 检查所有依赖项
python3 scripts/transcribe_podcast.py --check-env

# 3. 转录单个单集
python3 scripts/transcribe_podcast.py --keyword "早咖啡" -o output.md

# 或转录分享链接形式的单集 URL
python3 scripts/transcribe_podcast.py --url "https://www.xiaoyuzhoufm.com/episode/EPISODE_ID" -o output.md

CLI 命令

身份验证

# 交互式登录 —— 向手机发送验证码，保存访问令牌
python3 scripts/transcribe_podcast.py --login

发现与检索

# 搜索播客并显示 PID（用于批处理模式）
python3 scripts/transcribe_podcast.py --podcast-info --keyword "声动早咖啡"

# 列出某播客最近的单集
python3 scripts/transcribe_podcast.py --list-episodes --pid PODCAST_ID --count 10

转录

# 按关键词转录单个单集（取搜索结果第一条）
python3 scripts/transcribe_podcast.py --keyword "关键词" -o output.md

# 按 EID 转录单个单集
python3 scripts/transcribe_podcast.py --eid EPISODE_ID -o output.md

# 按小宇宙 URL 转录单个单集
python3 scripts/transcribe_podcast.py --url "https://www.xiaoyuzhoufm.com/episode/EPISODE_ID" -o output.md

# 批处理：转录某播客最近 5 期单集
python3 scripts/transcribe_podcast.py --pid PODCAST_ID --count 5 -o ./transcripts/

# 指定输出格式
python3 scripts/transcribe_podcast.py --eid EPISODE_ID --format srt -o output.srt

诊断

# 检查全部依赖项（ffmpeg、xyz API、token、ASR 可执行文件、模型）
python3 scripts/transcribe_podcast.py --check-env

输出格式

批处理模式

• 转录某播客最近 N 期单集（--pid --count N）
• 每个单集单独保存为输出目录下的一个文件
• 断点续传：跳过输出目录中已存在的单集文件

配置

配置项按以下优先级顺序解析：CLI 参数 > 环境变量 > 配置文件。

配置文件（~/.xiaoyuzhou-asr.json）

由 --login 自动创建，亦可手动添加路径配置：

{
  "token": "x-jike-access-token",
  "refresh_token": "x-jike-refresh-token",
  "model_dir": "/path/to/models/0.6B",
  "asr_bin": "/path/to/local_transcribe"
}

环境变量

令牌管理

• --login 会自动将令牌保存至配置文件
• 若 API 返回 401 错误，将自动使用 refresh token 刷新访问令牌
• 若无有效令牌，将提示用户重新登录

参考文档

• xyz API 接口与认证机制：references/xyz-api.md
• Qwen3-ASR 使用方式与性能说明：references/qwen3-asr.md

约束条件

• 必须对音频分段：为保障 Metal GPU 运行稳定，需将音频切分为 ≤3 分钟的片段（脚本自动完成）
• 音频格式须为 WAV、16kHz、单声道（脚本自动转换）
• tokenizer.json 在首次运行时自动生成（基于 vocab.json 与 merges.txt）
• xyz API 要求使用中国大陆手机号（+86）进行登录
• 所有处理均在本地完成 —— 音频数据永不离开本机
• 网络失败时最多重试下载 3 次

脚本复用

本项目属于技能型工具（skill project），并非封装好的 Python 库。推荐优先使用上述 CLI 方式。本仓库中其他脚本仍可直接导入 scripts/transcribe_podcast.py：

from transcribe_podcast import (
    search_episodes, transcribe_episode, format_output,
    TranscriptionError, ApiError, TokenExpiredError,
)

try:
    episodes, _ = search_episodes(token, "早咖啡")
    episode, transcript, timings = transcribe_episode(token, eid, model_dir, asr_bin)
    output = format_output(episode, transcript)
except TranscriptionError as e:
    print(f"Error: {e}")