Audio Transcribe — Development skill for Claude Code

audio-transcribe

音视频转文字，支持 CLI、Claude Code Skill、MCP Server 三种形态。基于阿里云百炼录音文件识别接口（qwen-audio-asr 系列 / paraformer），支持说话人分离，长音频免切片，原生支持微信语音 SILK 格式。

不一定需要 Claude Code：可作为独立命令行工具，也可接入任意 MCP 客户端（Claude Desktop、Cursor 等）。

功能特性

• 全格式输入：mp3 / wav / m4a / aac / flac / ogg / opus / amr / wma 及 mp4 / mkv / mov 等所有 ffmpeg 支持的音视频格式（视频自动抽取音轨）
• 微信语音 SILK 原生支持：自动识别并剥离微信 0x02 + #!SILK_V3 文件头，通过 uv 临时环境调用 pilk 解码（仅转写 silk 文件时需要 uv，其余格式零额外依赖）
• 说话人分离：多人对话按 说话人N：内容 分段输出；单一说话人自动退化为整段纯文本
• 长音频免切片：走百炼录音文件识别（filetrans）异步接口，一次上传整段处理，DashScope 临时存储转完自动删除
• 清晰的输出约定：stdout 只输出转写文本，进度 / 耗时 / 计费估算走 stderr，方便脚本和 Agent 调用
• 内置 MCP Server：scripts/mcp_server.py 手写 MCP stdio 协议（JSON-RPC 2.0），仅标准库零第三方依赖，任意 MCP 客户端即插即用

安装

1. 安装依赖

• Python 3.10+，安装 SDK：

  pip install dashscope

• ffmpeg / ffprobe 加入 PATH
• 仅转写微信 SILK 文件时额外需要 uv（脚本自动创建 Python 3.11 临时环境安装 pilk，无需手动操作）

2. 配置 API Key

在[阿里云百炼控制台](https://bailian.console.aliyun.com/)创建 API Key，配置到环境变量：

# Windows
setx DASHSCOPE_API_KEY "sk-xxxx"

# macOS / Linux
echo 'export DASHSCOPE_API_KEY="sk-xxxx"' >> ~/.bashrc

使用业务空间专属 key（`sk-ws-` 前缀）时无需其他配置；使用普通百炼 key 请额外设置 `DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1`（见下文[环境变量](#环境变量)）。

3. 部署文件

仓库中每个文件的用途和建议放置位置：

文件	用途	放到哪里
scripts/transcribe.py	主脚本，所有逻辑都在这里	不需要单独移动，跟随安装方式即可
scripts/mcp_server.py	MCP stdio server，复用 transcribe.py 的转写流程	不需要单独移动，跟随安装方式即可
SKILL.md	Claude Code Skill 定义文件，告诉 Agent 何时以及如何调用	必须与 scripts/ 在同一目录
bin/asr / bin/asr.cmd	全局命令包装器示例（git-bash / cmd），可选	复制到 PATH 中的任意目录，并改写其中的两个路径

按使用方式二选一（或都装）：

**方式 A：作为 Claude Code Skill（推荐）**

把整个仓库克隆到 Agent 的 skill 目录：

# macOS / Linux（用户级，所有项目可用）
git clone https://github.com/OstrichHermit/audio-transcribe.git ~/.claude/skills/audio-transcribe

# Windows P