audio-transcribe

会议与播客转录（FunASR + MiMo）

将多说话人音频转录为结构化 Markdown，支持自动说话人分离、热词偏置和可选的 LLM 清理。提供两类 ASR 引擎：FunASR（Paraformer / SenseVoice / Whisper——速度快、成本低，可使用 GPU 或 CPU，支持 99 种语言）和 MiMo-V2.5-ASR（小米的 8B 模型，仅支持本地 GPU，在专有名词和语码转换方面表现更强）。两者使用相同的 VAD + 说话人聚类栈。

所有脚本都可直接从插件目录运行，无需复制。请在每次会话开始时定义此简写：

SCRIPTS=${CLAUDE_PLUGIN_ROOT}/skills/audio-transcribe/scripts

支持的语言

--lang	模型	语言	热词
zh（默认）	SeACo-Paraformer	中文（CER 1.95%）	是
zh-basic	Paraformer-large	中文	否
en	Paraformer-en	英语	否
auto	SenseVoiceSmall	自动检测：zh/en/ja/ko/yue	否
whisper	Whisper-large-v3-turbo	99 种语言	否
mimo	MiMo-V2.5-ASR（本地 8B，仅限 GPU）	zh/en/语码转换/方言	否

所有预设都包含说话人分离（CAM++）和 VAD（FSMN）。 mimo 会在 MiMo 的文本输出上复用 FSMN VAD + CAM++ 栈。

说话人分离注意事项：auto 和 whisper 不会输出逐句时间戳，因此这些预设无法进行说话人分离。需要识别说话人时（例如播客、会议），请使用 zh、zh-basic、en 或 mimo。

工作流

开始转录前，务必询问用户：

1. 音频文件——录音文件路径（必需）
2. 类型——会议、播客还是访谈？（会影响默认设置）
3. 语言——使用什么语言？（默认：中文）
4. 说话人数——有多少位参与者？（有助于改善说话人分离）
5. 说话人姓名——播客：主持人和嘉宾的姓名；会议：参会者名单
6. 辅助文件——询问：

   “你是否有以下任何资料可以帮助提高准确性？”

   • 参会者 / 嘉宾名单——用于热词和说话人映射
   • 会议议程或节目主题——用于热词（术语、姓名）
   • 参考文档（节目说明、先前的笔记）——用于说话人识别和 ASR 校正

根据录音类型调整默认设置：

• 会议：默认 --lang zh，询问是否有辅助文件
• 播客 / 访谈：默认 --lang zh、--num-speakers 2，务必询问主持人和嘉宾的姓名，并建议使用 --speaker-context 指定角色 （不要使用 --lang auto——它缺少说话人分离所需的时间戳）

⚠️ --speakers 必须使用说话人的真实姓名，不能使用播客别名。 传给 --speakers 的值会直接作为转录文本中的说话人标签。务必根据主持人 / 嘉宾的真实姓名填写（例如，从节目说明中的 “Host:” 字段获取），不要使用播客订阅源名称或标题。

示例：如果节目说明列出 “Host: 张三（张三的播客）”，请传入 --speakers '张三' ——不要使用别名“张三的播客”。将真实姓名和别名都加入 hotwords.txt，以便 ASR 识别两种形式。

同时提供 --speakers 和 --reference 时，脚本会在启动时检测此错误，并打印一段标明建议真实姓名的 ACTION REQUIRED 区块。如果看到该区块，请停止运行，并在 Phase 3 之前使用更正后的 --speakers 值重新调用——此警告不会中止流水线。

如果用户提供了辅助资料：

• 提取参与者姓名和关键术语 → 创建 hotwords.txt（包含真实姓名和别名）
• 提取每个人的背景信息 → 创建 speaker-context.json
• 使用 --reference 传入原始参考文档
• 同时使用以上三项以获得最佳效果

快速开始

1. 环境设置

AUTO_YES=1 bash $SCRIPTS/setup_env.sh
# Or force CPU:  AUTO_YES=1 bash $SCRIPTS/setup_env.sh cpu

设置脚本会修补 FunASR 的谱聚类，以实现 O(N²·k) 性能。 否则，超过约 1 小时的录音会在说话人聚类过程中卡住数小时。

2. 运行转录

输出文件将写入当前工作目录。

LLM 清理（阶段 3）为可选功能。 默认情况下，转录会在本地运行，不会联系任何外部服务。若要启用由 LLM 驱动的 ASR 校正和说话人姓名优化，请传入 --model <model-id>。适合使用 LLM 清理的情况：

• 原始转录包含许多 ASR 错误（姓名、技术术语）
• 需要润色后的出版级输出
• 需要根据上下文优化说话人姓名

⚠️ 数据隐私： 通过 --model 启用 LLM 清理后，转录文本片段会发送给外部 LLM 提供商（具体取决于模型 ID，可能是 AWS Bedrock、Anthropic 或 OpenAI）。使用 --skip-llm 或省略 --model，可确保所有数据都保留在本地。对于 Bedrock，boto3 使用标准 AWS 凭证链（IAM 角色、SSO、~/.aws/credentials、环境变量）。

# Chinese meeting with hotwords (local-only, no LLM)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang zh --num-speakers 9 --hotwords hotwords.txt

# English meeting with speaker names
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang en --speakers "Alice,Bob,Carol,Dave"

# Auto-detect language (zh/en/ja/ko/yue)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang auto --num-speakers 6

# Whisper for any language
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang whisper --num-speakers 4

# Enable LLM cleanup for polished output (requires --model)
# Bedrock (uses AWS credential chain: IAM role, SSO, ~/.aws/credentials)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --lang zh --num-speakers 9 --hotwords hotwords.txt \
    --provider bedrock --model us.anthropic.claude-sonnet-4-6

# Bedrock "global" cross-region profile (recent AWS deployments)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --provider bedrock --model global.anthropic.claude-sonnet-4-6

# Bedrock via litellm-style wrapper (supported; prefix is stripped for boto3)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --provider bedrock --model amazon-bedrock/global.anthropic.claude-sonnet-4-6

# Anthropic API (requires ANTHROPIC_API_KEY env var)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --provider anthropic --model claude-sonnet-4-6

# OpenAI-compatible API (requires OPENAI_API_KEY env var)
python3 $SCRIPTS/transcribe.py meeting.wav \
    --provider openai --model gpt-4o

# Full pipeline with all supporting files + LLM (best quality)
python3 $SCRIPTS/transcribe.py episode.m4a \
    --lang zh --num-speakers 2 \
    --hotwords hotwords.txt \
    --speakers "关羽,张飞" \
    --speaker-context speaker-context.json \
    --reference show-notes.md \
    --model us.anthropic.claude-sonnet-4-6

# Resume interrupted LLM cleanup
python3 $SCRIPTS/transcribe.py meeting.wav \
    --skip-transcribe --model us.anthropic.claude-sonnet-4-6

3. 验证说话人标签

如果转录中的说话人标签发生错置（播客中很常见），验证脚本可以通过 LLM 分析检测并修正不匹配：

# Dry-run: check if host/guest are swapped
python3 $SCRIPTS/verify_speakers.py podcast_raw_transcript.json \
    --speakers "关羽,张飞" \
    --speaker-context speaker-context.json

# Apply the fix
python3 $SCRIPTS/verify_speakers.py podcast_raw_transcript.json \
    --speakers "关羽,张飞" \
    --speaker-context speaker-context.json --fix

# Multi-speaker meeting: full reassignment
python3 $SCRIPTS/verify_speakers.py meeting_raw_transcript.json \
    --speakers "Alice,Bob,Carol,Dave" \
    --speaker-context speaker-context.json --fix

# Then regenerate the markdown with corrected labels
python3 $SCRIPTS/transcribe.py original.m4a \
    --skip-transcribe --clean-cache

该脚本会分析前 5 分钟（可通过 --minutes 配置），并自动识别播客（2 位说话人，检测标签错置）或会议（N 位说话人，全面重新分配）。

音频预处理

该脚本会自动将输入音频转换为 16kHz 单声道 FLAC，并验证没有音频丢失（检测静音截断）。

格式	4 小时 14 分会议	质量	建议
FLAC	219MB	无损	默认，最安全
Opus	55MB	有损	长文件有截断风险
WAV	465MB	无损	可用，但文件更大
原始 M4A	173MB	源文件	也可直接使用

请勿拆分长录音——拆分会破坏说话人 ID 的一致性。

MiMo-V2.5-ASR（可选，仅限 GPU）

--lang mimo 会在 CUDA GPU 上本地运行小米的 MiMo-V2.5-ASR。适用于以下情况：

• 希望评估 MiMo 在中文音频上的表现，并与 Paraformer 进行比较。
• 录音中包含大量语码转换、方言（吴语、粤语、闽南语、四川话）、歌词或其他预设容易误转录的罕见专有名词。

要求：

• CUDA ≥12.0，且 显存 ≥20 GB（16 GB 显卡会在推理时出现 OOM）。
• Python 3.12（由 setup_env.sh 强制要求）。
• 下载约 20 GB 的权重（仅需一次），并编译 flash-attn==2.7.4.post1（需要 CUDA 工具包中的 nvcc，耗时 10–30 分钟）。

安装（可选）：

# One-time: install MiMo on top of the standard environment
AUTO_YES=1 INSTALL_MIMO=1 \
    MIMO_WEIGHTS_PATH=/mnt/models/hf \
    bash $SCRIPTS/setup_env.sh

运行：

python3 $SCRIPTS/transcribe.py podcast.m4a \
    --lang mimo --num-speakers 2 \
    --mimo-weights-path /mnt/models/hf

失败后恢复：

python3 $SCRIPTS/transcribe.py podcast.m4a \
    --lang mimo --resume-mimo --mimo-weights-path /mnt/models/hf

限制：

• 不支持热词偏置（MiMo 没有相关 API——--hotwords 会被忽略）。
• 不支持 CPU 回退。
• 在同一块 GPU 上，推理速度低于 Paraformer（8B 模型，相比约 0.3B）；在 A100 上，RTF 约为 0.1–0.2。

关键标志

标志	用途
--lang	zh（默认）、zh-basic、en、auto、whisper
--hotwords	热词文件或字符串——为 ASR 提供偏置（仅支持 zh）
--reference F	用于 LLM ASR 校正的参考文件
--num-speakers N	预期的说话人数（提升说话人分离效果）
--speakers "A,B,C"	按首次出现顺序分配真实姓名
--speaker-context F	包含供 LLM 使用的各说话人角色信息的 JSON
--no-detect-gender	禁用自动说话人性别检测（CAM++ 性别分类器）
--speaker-genders "A:female,B:male"	覆盖各说话人的性别（也接受按位置指定的 female,male）
--audio-format	flac（默认）、opus、wav
--device cpu	强制使用 CPU 模式
--batch-size N	调整内存占用（CPU 使用 60；GPU 内存不足时使用 100）
--phase1-only	第 1 阶段（VAD + ASR + 说话人分离）后退出，跳过第 2 和第 3 阶段
--json-out PATH	将原始转录 JSON 写入指定路径（覆盖默认命名）
--skip-transcribe	从已保存的 *_raw_transcript.json 恢复
--skip-llm	跳过 LLM 清理（未提供 --model 时的默认行为）
--model ID	使用此模型启用 LLM 清理（自动检测 Bedrock/Anthropic/OpenAI）
--title "..."	输出文档标题
--clean-cache	完成后删除 LLM 分块缓存
--output PATH	自定义输出文件路径
--model-cache-dir	ModelScope 模型缓存目录（约 3GB，默认：~/.cache/modelscope/）
--mimo-audio-tag	MiMo 语言提示：<chinese>（默认）、<english>、<auto>
--mimo-batch N	每次 MiMo 调用并行处理的 VAD 片段数（默认 1；H100/80GB 可使用更高值）
--mimo-weights-path DIR	MiMo 权重缓存目录（默认：$HF_HOME → ~/.cache/huggingface）
--resume-mimo	中途运行失败后，从 *_mimo_partial.json 恢复 MiMo 第 1 阶段

输出

• <stem>-transcript.md — 包含说话人标签和时间戳的最终 Markdown
• <stem>_raw_transcript.json — 第 1 阶段的原始输出（用于恢复/分析）

说话人分离技巧

FunASR 的 CAM++ 可能会合并音色相似的说话人。要改善效果：

1. --num-speakers N — 提示预期的说话人数
2. --hotwords — 添加参与者姓名（中文姓名效果最佳）
3. --speaker-context — 提供每个人的关键词，供 LLM 拆分说话人
4. 关键词匹配 — 在 *_raw_transcript.json 中搜索独特短语

说话人性别

默认启用：通过 3D-Speaker 的 CAM++ 性别分类器（iic/speech_campplus_two_class_gender_16k）， 将检测到的每位说话人分类为 male / female。 分类结果会显示在说话人列表表格的每个姓名旁，并会注入 LLM 清理提示词， 以便校正代词（他/她、he/she）。

同时使用时的优先顺序：

1. --speaker-genders "Alice:female,Bob:male"（显式 CLI 设置）——优先级最高
2. 参考文本中的提示，如 主播（女）：韩梅梅 或 Host (male): Alice——覆盖自动检测结果
3. CAM++ 自动检测——回退选项

如果不需要性别信息并希望节省约 500 MB 的模型下载量和额外推理时间， 可使用 --no-detect-gender 禁用此功能。

仅使用 CPU / 内存较少的机器

在资源受限的机器上处理较长录音时，可能会遇到执行超时或因内存不足而被终止。 解决方法请参见 references/pipeline-details.md：

• 使用 systemd-run 或 nohup，避免 Agent 超时
• 使用 swap 和/或 --lang zh-basic（更轻量的模型）防止内存不足

其他资源

• references/pipeline-details.md — 架构、模型规格、基准测试、说话人角色验证、热词效果、聚类补丁
• scripts/transcribe.py — 主要转录工作流
• scripts/verify_speakers.py — 说话人标签验证与修正
• scripts/llm_utils.py — 共享 LLM 基础设施（Bedrock/Anthropic/OpenAI）
• scripts/setup_env.sh — 环境设置（venv + 依赖项 + 补丁）