audio-transcribe-cli-mcp 0.1.0__tar.gz

audio_transcribe_cli_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OstrichHermit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

audio_transcribe_cli_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: audio-transcribe-cli-mcp
+Version: 0.1.0
+Summary: 音视频转文字 CLI / MCP Server：阿里云百炼录音文件识别，支持说话人分离与微信语音 SILK
+Author: OstrichHermit
+License: MIT
+Project-URL: Homepage, https://github.com/OstrichHermit/audio-transcribe
+Project-URL: Issues, https://github.com/OstrichHermit/audio-transcribe/issues
+Keywords: asr,speech-to-text,transcription,dashscope,qwen,audio,video,mcp,whisper-alternative
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dashscope
+Dynamic: license-file
+
+# audio-transcribe
+
+**音视频转文字，支持 CLI、MCP Server 两种形态：说话人分离，长音频免切片，原生支持微信语音 SILK 格式。**
+
+Audio/video transcription in both CLI and MCP Server flavors: speaker diarization, long-audio support with no manual splitting, and native WeChat SILK decoding.
+
+[English](README_EN.md) | 简体中文
+
+基于阿里云百炼录音文件识别接口（qwen-audio-asr 系列 / paraformer）。不依赖 Claude Code：可作为独立命令行工具，也可接入任意 MCP 客户端（Claude Desktop、Cursor 等）。
+
+## 功能特性
+
+- **全格式输入**：mp3 / wav / m4a / aac / flac / ogg / opus / amr / wma 及 mp4 / mkv / mov 等所有 ffmpeg 支持的音视频格式（视频自动抽取音轨）
+- **微信语音 SILK 原生支持**：自动识别并剥离微信 `0x02 + #!SILK_V3` 文件头，通过 [uv](https://docs.astral.sh/uv/) 临时环境调用 [pilk](https://github.com/foyoux/pilk) 解码（仅转写 silk 文件时需要 uv，其余格式零额外依赖）
+- **说话人分离**：多人对话按 `说话人N：内容` 分段输出；单一说话人自动退化为整段纯文本
+- **长音频免切片**：走百炼录音文件识别（filetrans）异步接口，一次上传整段处理，DashScope 临时存储转完自动删除
+- **清晰的输出约定**：stdout 只输出转写文本，进度 / 耗时 / 计费估算走 stderr，方便脚本和 Agent 调用
+- **内置 MCP Server**：`audio-transcribe-mcp` 命令，手写 MCP stdio 协议（JSON-RPC 2.0），仅标准库零第三方依赖，任意 MCP 客户端即插即用
+
+## 安装
+
+```bash
+pip install audio-transcribe-cli-mcp
+```
+
+也可从源码安装：
+
+```bash
+git clone https://github.com/OstrichHermit/audio-transcribe.git
+cd audio-transcribe
+pip install .
+```
+
+安装后会得到两个命令：`asr`（CLI）和 `audio-transcribe-mcp`（MCP Server）。
+
+### 安装为 Agent Skill（可选）
+
+仓库内附带 Agent Skill（`skills/audio-transcribe/SKILL.md`），把它复制到你所用 AI Agent 的 skills 目录，Agent 即可自动掌握本工具的用法。以 Claude Code 为例：
+
+```bash
+cp -r skills/audio-transcribe ~/.claude/skills/audio-transcribe
+```
+
+### 1. 安装依赖
+
+- Python 3.10+（`pip install .` 会自动安装 dashscope 依赖）
+- [ffmpeg / ffprobe](https://ffmpeg.org/) 自行安装并加入 PATH
+- 仅转写微信 SILK 文件时额外需要 [uv](https://docs.astral.sh/uv/)（脚本自动创建 Python 3.11 临时环境安装 pilk，无需手动操作）
+
+### 2. 配置 API Key
+
+在[阿里云百炼控制台](https://bailian.console.aliyun.com/)创建 API Key，配置到环境变量：
+
+```bash
+# Windows
+setx DASHSCOPE_API_KEY "sk-xxxx"
+
+# macOS / Linux
+echo 'export DASHSCOPE_API_KEY="sk-xxxx"' >> ~/.bashrc
+```
+
+默认直连百炼官方主域名，开箱即用。使用业务空间专属 key（`sk-ws-` 前缀）且分配了专属域名的用户，额外设置 `DASHSCOPE_BASE_URL` 即可（见下文[环境变量](#环境变量)）。
+
+## 使用方法
+
+```bash
+asr "<音频或视频文件路径>"
+asr "<文件>" --no-speakers   # 关闭说话人分离
+asr "<文件>" --out 结果.txt   # 保存到文件
+asr "<文件>" --keep-workdir   # 保留中间文件（调试）
+```
+
+示例：
+
+```bash
+$ asr meeting.mp4
+[1/4] ffmpeg 预处理: meeting.mp4
+[2/4] 上传音频（32.5 分钟）...
+[3/4] 提交识别任务...
+识别模型: qwen-audio-3.1-asr-flash-filetrans
+  识别中... 45s
+[4/4] 完成，耗时 78s，音频 32.5 分钟（计费约 0.06 元，按 3.1 Token 计费估算）
+说话人1：大家好，今天我们讨论一下项目排期……
+说话人2：好的，我先说下我这边的情况……
+```
+
+### 微信语音（SILK）
+
+微信语音消息文件（`*.silk`，含 `0x02 + #!SILK_V3` 头）直接作为输入传入即可，脚本自动完成剥头、pilk 解码（24kHz PCM）→ ffmpeg 封装 WAV → 正常识别管线。
+
+## 作为 MCP Server 接入
+
+任意支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）都能接入：
+
+```bash
+# Claude Code
+claude mcp add audio-transcribe -- audio-transcribe-mcp
+```
+
+其他客户端在 MCP 配置 JSON 中添加（`env` 里按需配置 API Key，也可继承系统环境变量）：
+
+```json
+{
+  "mcpServers": {
+    "audio-transcribe": {
+      "command": "audio-transcribe-mcp",
+      "env": {
+        "DASHSCOPE_API_KEY": "sk-xxxx"
+      }
+    }
+  }
+}
+```
+
+也可以用模块方式启动：`python -m audio_transcribe_cli.mcp_server`。
+
+接入后客户端会得到一个 `transcribe` 工具：`file_path` 必填，`speakers`（说话人分离，默认开）和 `out_path`（结果另存）可选。
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `DASHSCOPE_API_KEY` | 百炼 API Key（必需） |
+| `DASHSCOPE_BASE_URL` | API 域名（可选）。默认 `https://dashscope.aliyuncs.com/api/v1`（官方主域名，开箱即用）；使用业务空间专属域名的用户设置为你的专属域名，例如 `https://xxxx.cn-beijing.maas.aliyuncs.com/api/v1` |
+| `ASR_WORKSPACE` | 中间文件（转码 / 切片临时目录）的根目录（可选）。默认系统临时目录，转写完成自动清理 |
+
+## 计费说明
+
+- 主模型 `qwen-audio-3.1-asr-flash-filetrans` 按 Token 计费（输入 25 Token/秒 × 0.8 元/百万 + 输出 2.7 元/百万），约 **0.11 元/小时**音频
+- 识别失败自动降级尝试 `paraformer-v2`
+- 脚本结束会在 stderr 输出本次计费估算
+
+## 已知限制
+
+- 同步提交的文件大小受 DashScope 限制，超长音频依赖 filetrans 异步接口（脚本已处理，无需切片）
+- 说话人编号（说话人1 / 说话人2）与真实人物的对应关系需要结合内容自行判断
+- SILK 解码依赖 pilk 的预编译 wheel（cp311 及以下），通过 uv 临时环境解决，首次运行需下载环境，之后走缓存

audio_transcribe_cli_mcp-0.1.0/README.md

@@ -0,0 +1,137 @@
+# audio-transcribe
+
+**音视频转文字，支持 CLI、MCP Server 两种形态：说话人分离，长音频免切片，原生支持微信语音 SILK 格式。**
+
+Audio/video transcription in both CLI and MCP Server flavors: speaker diarization, long-audio support with no manual splitting, and native WeChat SILK decoding.
+
+[English](README_EN.md) | 简体中文
+
+基于阿里云百炼录音文件识别接口（qwen-audio-asr 系列 / paraformer）。不依赖 Claude Code：可作为独立命令行工具，也可接入任意 MCP 客户端（Claude Desktop、Cursor 等）。
+
+## 功能特性
+
+- **全格式输入**：mp3 / wav / m4a / aac / flac / ogg / opus / amr / wma 及 mp4 / mkv / mov 等所有 ffmpeg 支持的音视频格式（视频自动抽取音轨）
+- **微信语音 SILK 原生支持**：自动识别并剥离微信 `0x02 + #!SILK_V3` 文件头，通过 [uv](https://docs.astral.sh/uv/) 临时环境调用 [pilk](https://github.com/foyoux/pilk) 解码（仅转写 silk 文件时需要 uv，其余格式零额外依赖）
+- **说话人分离**：多人对话按 `说话人N：内容` 分段输出；单一说话人自动退化为整段纯文本
+- **长音频免切片**：走百炼录音文件识别（filetrans）异步接口，一次上传整段处理，DashScope 临时存储转完自动删除
+- **清晰的输出约定**：stdout 只输出转写文本，进度 / 耗时 / 计费估算走 stderr，方便脚本和 Agent 调用
+- **内置 MCP Server**：`audio-transcribe-mcp` 命令，手写 MCP stdio 协议（JSON-RPC 2.0），仅标准库零第三方依赖，任意 MCP 客户端即插即用
+
+## 安装
+
+```bash
+pip install audio-transcribe-cli-mcp
+```
+
+也可从源码安装：
+
+```bash
+git clone https://github.com/OstrichHermit/audio-transcribe.git
+cd audio-transcribe
+pip install .
+```
+
+安装后会得到两个命令：`asr`（CLI）和 `audio-transcribe-mcp`（MCP Server）。
+
+### 安装为 Agent Skill（可选）
+
+仓库内附带 Agent Skill（`skills/audio-transcribe/SKILL.md`），把它复制到你所用 AI Agent 的 skills 目录，Agent 即可自动掌握本工具的用法。以 Claude Code 为例：
+
+```bash
+cp -r skills/audio-transcribe ~/.claude/skills/audio-transcribe
+```
+
+### 1. 安装依赖
+
+- Python 3.10+（`pip install .` 会自动安装 dashscope 依赖）
+- [ffmpeg / ffprobe](https://ffmpeg.org/) 自行安装并加入 PATH
+- 仅转写微信 SILK 文件时额外需要 [uv](https://docs.astral.sh/uv/)（脚本自动创建 Python 3.11 临时环境安装 pilk，无需手动操作）
+
+### 2. 配置 API Key
+
+在[阿里云百炼控制台](https://bailian.console.aliyun.com/)创建 API Key，配置到环境变量：
+
+```bash
+# Windows
+setx DASHSCOPE_API_KEY "sk-xxxx"
+
+# macOS / Linux
+echo 'export DASHSCOPE_API_KEY="sk-xxxx"' >> ~/.bashrc
+```
+
+默认直连百炼官方主域名，开箱即用。使用业务空间专属 key（`sk-ws-` 前缀）且分配了专属域名的用户，额外设置 `DASHSCOPE_BASE_URL` 即可（见下文[环境变量](#环境变量)）。
+
+## 使用方法
+
+```bash
+asr "<音频或视频文件路径>"
+asr "<文件>" --no-speakers   # 关闭说话人分离
+asr "<文件>" --out 结果.txt   # 保存到文件
+asr "<文件>" --keep-workdir   # 保留中间文件（调试）
+```
+
+示例：
+
+```bash
+$ asr meeting.mp4
+[1/4] ffmpeg 预处理: meeting.mp4
+[2/4] 上传音频（32.5 分钟）...
+[3/4] 提交识别任务...
+识别模型: qwen-audio-3.1-asr-flash-filetrans
+  识别中... 45s
+[4/4] 完成，耗时 78s，音频 32.5 分钟（计费约 0.06 元，按 3.1 Token 计费估算）
+说话人1：大家好，今天我们讨论一下项目排期……
+说话人2：好的，我先说下我这边的情况……
+```
+
+### 微信语音（SILK）
+
+微信语音消息文件（`*.silk`，含 `0x02 + #!SILK_V3` 头）直接作为输入传入即可，脚本自动完成剥头、pilk 解码（24kHz PCM）→ ffmpeg 封装 WAV → 正常识别管线。
+
+## 作为 MCP Server 接入
+
+任意支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）都能接入：
+
+```bash
+# Claude Code
+claude mcp add audio-transcribe -- audio-transcribe-mcp
+```
+
+其他客户端在 MCP 配置 JSON 中添加（`env` 里按需配置 API Key，也可继承系统环境变量）：
+
+```json
+{
+  "mcpServers": {
+    "audio-transcribe": {
+      "command": "audio-transcribe-mcp",
+      "env": {
+        "DASHSCOPE_API_KEY": "sk-xxxx"
+      }
+    }
+  }
+}
+```
+
+也可以用模块方式启动：`python -m audio_transcribe_cli.mcp_server`。
+
+接入后客户端会得到一个 `transcribe` 工具：`file_path` 必填，`speakers`（说话人分离，默认开）和 `out_path`（结果另存）可选。
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `DASHSCOPE_API_KEY` | 百炼 API Key（必需） |
+| `DASHSCOPE_BASE_URL` | API 域名（可选）。默认 `https://dashscope.aliyuncs.com/api/v1`（官方主域名，开箱即用）；使用业务空间专属域名的用户设置为你的专属域名，例如 `https://xxxx.cn-beijing.maas.aliyuncs.com/api/v1` |
+| `ASR_WORKSPACE` | 中间文件（转码 / 切片临时目录）的根目录（可选）。默认系统临时目录，转写完成自动清理 |
+
+## 计费说明
+
+- 主模型 `qwen-audio-3.1-asr-flash-filetrans` 按 Token 计费（输入 25 Token/秒 × 0.8 元/百万 + 输出 2.7 元/百万），约 **0.11 元/小时**音频
+- 识别失败自动降级尝试 `paraformer-v2`
+- 脚本结束会在 stderr 输出本次计费估算
+
+## 已知限制
+
+- 同步提交的文件大小受 DashScope 限制，超长音频依赖 filetrans 异步接口（脚本已处理，无需切片）
+- 说话人编号（说话人1 / 说话人2）与真实人物的对应关系需要结合内容自行判断
+- SILK 解码依赖 pilk 的预编译 wheel（cp311 及以下），通过 uv 临时环境解决，首次运行需下载环境，之后走缓存

audio_transcribe_cli_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "audio-transcribe-cli-mcp"
+version = "0.1.0"
+description = "音视频转文字 CLI / MCP Server：阿里云百炼录音文件识别，支持说话人分离与微信语音 SILK"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "OstrichHermit" }]
+requires-python = ">=3.10"
+keywords = ["asr", "speech-to-text", "transcription", "dashscope", "qwen", "audio", "video", "mcp", "whisper-alternative"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "dashscope",
+]
+
+[project.urls]
+Homepage = "https://github.com/OstrichHermit/audio-transcribe"
+Issues = "https://github.com/OstrichHermit/audio-transcribe/issues"
+
+[project.scripts]
+asr = "audio_transcribe_cli.cli:main"
+audio-transcribe-mcp = "audio_transcribe_cli.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

audio_transcribe_cli_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli/__init__.py

@@ -0,0 +1,5 @@
+"""audio-transcribe：音视频转文字（阿里云百炼，支持说话人分离）
+
+CLI 入口：``asr``；MCP Server 入口：``audio-transcribe-mcp``。
+"""
+__version__ = "0.1.0"

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli/cli.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""音视频转文字（带说话人分离）：阿里云百炼录音文件识别 + diarization
+
+流程：ffmpeg 统一音频 → DashScope 临时存储上传 → 录音文件识别（说话人分离）→ 轮询取结果
+stdout 输出转写文本，stderr 输出进度信息。
+
+依赖：dashscope SDK（Python314 环境）、ffmpeg、DASHSCOPE_API_KEY 环境变量。
+微信语音 SILK 格式：自动剥 0x02 前缀 → uv+pilk 解码为 wav（pilk 仅 cp311，走 uv 临时环境）。
+"""
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.request
+from pathlib import Path
+
+import dashscope
+from dashscope.audio.asr import Transcription
+
+# DashScope API 域名：默认官方主域名，开箱即用；使用业务空间专属域名（sk-ws- 前缀的
+# 业务空间 key）的用户请设置环境变量 DASHSCOPE_BASE_URL 覆盖
+dashscope.base_http_url = os.environ.get(
+    "DASHSCOPE_BASE_URL",
+    "https://dashscope.aliyuncs.com/api/v1",
+)
+
+# 中间文件存放的临时根目录，默认系统临时目录，可通过 ASR_WORKSPACE 环境变量覆盖
+WORKSPACE = Path(os.environ.get("ASR_WORKSPACE", tempfile.gettempdir()))
+MODEL = "qwen-audio-3.1-asr-flash-filetrans"
+FALLBACK_MODELS = ["paraformer-v2"]
+SUPPORTED_EXTS = {
+    ".mp3", ".wav", ".m4a", ".aac", ".flac", ".ogg", ".opus", ".amr", ".wma",
+    ".mp4", ".mkv", ".mov", ".avi", ".webm", ".flv", ".ts", ".m4v", ".wmv",
+    ".silk",
+}
+
+# uv 用于 SILK 解码（pilk 仅提供 cp311 及以下 wheel，本机 Python314 装不上）
+_UV_FALLBACK = Path(r"C:\Users\ASUS\AppData\Local\Programs\Python\Python314\Scripts\uv.exe")
+
+
+def eprint(*a):
+    print(*a, file=sys.stderr, flush=True)
+
+
+def run(cmd):
+    r = subprocess.run([str(c) for c in cmd], capture_output=True, text=True,
+                       encoding="utf-8", errors="replace")
+    if r.returncode != 0:
+        raise RuntimeError(f"命令失败: {' '.join(str(c) for c in cmd)}\n{r.stderr[-2000:]}")
+    return r.stdout.strip()
+
+
+def prepare_audio(src: Path, workdir: Path) -> Path:
+    """视频抽音轨、统一转 16kHz 单声道 mp3（小体积、通用格式）"""
+    audio = workdir / "audio.mp3"
+    run(["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", src,
+         "-vn", "-ac", "1", "-ar", "16000", "-b:a", "64k", audio])
+    return audio
+
+
+def decode_silk(src: Path, workdir: Path) -> Path:
+    """微信语音 SILK 解码为 wav：剥 0x02 前缀 → pilk 解码 24kHz mono pcm → ffmpeg 封装
+
+    微信 silk 头部为 0x02 + "#!SILK_V3"；pilk.decode 输出 24kHz 16bit 单声道 pcm。
+    """
+    data = src.read_bytes()
+    if data[:10] == b"\x02#!SILK_V3":
+        data = data[1:]
+    if data[:9] != b"#!SILK_V3":
+        raise RuntimeError("不是有效的 SILK 文件（头部不匹配 #!SILK_V3）")
+    clean_silk = workdir / "clean.silk"
+    clean_silk.write_bytes(data)
+
+    uv_exe = shutil.which("uv") or (_UV_FALLBACK if _UV_FALLBACK.exists() else None)
+    if uv_exe is None:
+        raise RuntimeError("未找到 uv 可执行文件，无法解码 SILK")
+    eprint("  SILK 格式：pilk 解码中（uv 临时环境，首次运行较慢）...")
+    pcm = workdir / "audio.pcm"
+    code = f"import pilk\npilk.decode(r'{clean_silk}', r'{pcm}')\n"
+    run([uv_exe, "run", "--python", "3.11", "--with", "pilk", "python", "-c", code])
+    if not pcm.exists() or pcm.stat().st_size == 0:
+        raise RuntimeError("SILK 解码失败：pcm 输出为空")
+
+    wav = workdir / "silk_audio.wav"
+    run(["ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+         "-f", "s16le", "-ar", "24000", "-ac", "1", "-i", pcm, wav])
+    return wav
+
+
+def upload_to_dashscope(audio: Path):
+    """上传到 DashScope 托管存储，返回 (file_id, 签名下载URL)"""
+    f = dashscope.Files.upload(file_path=str(audio), purpose="file-extract",
+                               api_key=dashscope.api_key)
+    if f.status_code != 200:
+        raise RuntimeError(f"上传失败: {f.code} {f.message}")
+    file_id = f.output["uploaded_files"][0]["file_id"]
+    g = dashscope.Files.get(file_id=file_id, api_key=dashscope.api_key)
+    if g.status_code != 200:
+        raise RuntimeError(f"获取下载链接失败: {g.code} {g.message}")
+    return file_id, g.output["url"]
+
+
+def submit_task(url: str):
+    """提交识别任务，依次尝试主模型和备选模型"""
+    models = [MODEL] + FALLBACK_MODELS
+    last = None
+    for model in models:
+        try:
+            resp = Transcription.async_call(model=model, file_urls=[url],
+                                            diarization_enabled=True)
+        except Exception as ex:
+            last = f"{model}: {ex}"
+            continue
+        if resp.status_code == 200:
+            eprint(f"识别模型: {model}")
+            return model, resp.output.task_id
+        last = f"{model}: {resp.status_code} {resp.code} {resp.message}"
+    raise RuntimeError(f"所有识别模型提交失败: {last}")
+
+
+def wait_result(task_id: str, audio_seconds: float, timeout: float = None):
+    """轮询任务直到完成。filetrans 排队+识别一般数十秒到数分钟"""
+    if timeout is None:
+        timeout = max(180, min(audio_seconds * 2, 3600))
+    t0 = time.time()
+    while time.time() - t0 < timeout:
+        time.sleep(3)
+        r = Transcription.fetch(task=task_id)
+        if r.output.task_status == "SUCCEEDED":
+            t_url = getattr(r.output, "transcription_url", None)
+            if not t_url:
+                t_url = r.output["results"][0]["transcription_url"]
+            with urllib.request.urlopen(t_url, timeout=60) as fh:
+                return json.load(fh)
+        if r.output.task_status == "FAILED":
+            code = ""
+            msg = ""
+            try:
+                code = r.output["code"]
+                msg = r.output["message"]
+            except Exception:
+                pass
+            raise RuntimeError(f"识别任务失败: {code} {msg}")
+        eprint(f"  识别中... {time.time() - t0:.0f}s")
+    raise RuntimeError("等待识别结果超时")
+
+
+def format_text(data: dict, with_speakers: bool) -> str:
+    """按说话人分段输出；若只有单一说话人则输出整段纯文本"""
+    transcripts = data.get("transcripts", [])
+    if not with_speakers:
+        return "\n".join(tr.get("text", "").strip() for tr in transcripts if tr.get("text"))
+
+    speakers_used = set()
+    all_sentences = []
+    for tr in transcripts:
+        all_sentences.extend(tr.get("sentences", []))
+        for s in tr.get("sentences", []):
+            if s.get("speaker_id") is not None:
+                speakers_used.add(s["speaker_id"])
+
+    if len(speakers_used) < 2:
+        return "\n".join(tr.get("text", "").strip() for tr in transcripts if tr.get("text"))
+
+    lines = []
+    cur_spk, buf = None, []
+    for s in all_sentences:
+        spk = s.get("speaker_id")
+        if spk != cur_spk:
+            if buf:
+                lines.append(f"说话人{cur_spk}：{''.join(buf)}")
+            cur_spk, buf = spk, []
+        buf.append(s["text"])
+    if buf:
+        lines.append(f"说话人{cur_spk}：{''.join(buf)}")
+    return "\n".join(lines)
+
+
+def transcribe_file(src: Path, with_speakers: bool = True, out: str = None,
+                    keep_workdir: bool = False) -> str:
+    """核心流程：预处理 → 上传 → 识别 → 格式化，返回转写文本（CLI 与 MCP 共用）"""
+    tmp_root = WORKSPACE / "temp"
+    tmp_root.mkdir(parents=True, exist_ok=True)
+    workdir = Path(tempfile.mkdtemp(prefix="asr_", dir=tmp_root))
+    file_id = None
+    t0 = time.time()
+
+    try:
+        eprint(f"[1/4] ffmpeg 预处理: {src.name}")
+        if src.suffix.lower() == ".silk":
+            src = decode_silk(src, workdir)
+        audio = prepare_audio(src, workdir)
+        dur_out = run(["ffprobe", "-v", "error", "-show_entries", "format=duration",
+                       "-of", "default=nw=1:nk=1", audio])
+        dur = float(dur_out)
+        eprint(f"[2/4] 上传音频（{dur / 60:.1f} 分钟）...")
+        file_id, dl_url = upload_to_dashscope(audio)
+
+        eprint("[3/4] 提交识别任务...")
+        _, task_id = submit_task(dl_url)
+        result = wait_result(task_id, dur)
+
+        text = format_text(result, with_speakers=with_speakers)
+        eprint(f"[4/4] 完成，耗时 {time.time() - t0:.0f}s，音频 {dur / 60:.1f} 分钟"
+               f"（计费约 {dur / 3600 * 0.11:.2f} 元，按 3.1 Token 计费估算）")
+
+        if out:
+            out_path = Path(out).expanduser().resolve()
+            out_path.parent.mkdir(parents=True, exist_ok=True)
+            out_path.write_text(text + "\n", encoding="utf-8")
+            eprint(f"已保存: {out_path}")
+        return text
+    finally:
+        if file_id:
+            try:
+                dashscope.Files.delete(file_id=file_id, api_key=dashscope.api_key)
+            except Exception:
+                pass
+        if keep_workdir:
+            eprint(f"中间文件保留: {workdir}")
+        else:
+            shutil.rmtree(workdir, ignore_errors=True)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="音视频转文字（阿里云百炼，支持说话人分离）")
+    ap.add_argument("input", help="音频或视频文件路径")
+    ap.add_argument("--no-speakers", action="store_true", help="关闭说话人分离，输出纯文本")
+    ap.add_argument("--out", default=None, help="结果保存路径（默认只打印）")
+    ap.add_argument("--keep-workdir", action="store_true", help="保留中间文件（调试用）")
+    args = ap.parse_args()
+
+    if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+
+    src = Path(args.input).expanduser().resolve()
+    if not src.exists():
+        eprint(f"文件不存在: {src}")
+        sys.exit(1)
+    if src.suffix.lower() not in SUPPORTED_EXTS:
+        eprint(f"不支持的格式: {src.suffix}")
+        sys.exit(1)
+    if not os.environ.get("DASHSCOPE_API_KEY"):
+        eprint("未设置 DASHSCOPE_API_KEY 环境变量")
+        sys.exit(1)
+
+    print(transcribe_file(src, with_speakers=not args.no_speakers,
+                          out=args.out, keep_workdir=args.keep_workdir))
+
+
+if __name__ == "__main__":
+    main()

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli/mcp_server.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""MCP stdio server：音视频转文字工具
+
+手写 MCP 协议（newline-delimited JSON-RPC 2.0），仅用标准库，无第三方 MCP 依赖。
+复用包内 cli 模块的转写流程。进度与日志全部输出到 stderr，
+stdout 仅输出协议消息。
+
+依赖：dashscope SDK、ffmpeg、DASHSCOPE_API_KEY 环境变量（同 cli 模块）。
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import cli as transcribe
+
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_INFO = {"name": "audio-transcribe", "version": "1.0.0"}
+
+TOOLS = [
+    {
+        "name": "transcribe",
+        "description": (
+            "音视频转文字，支持说话人分离。支持 mp3/wav/m4a/flac/ogg/aac/amr/wma、"
+            "mp4/mkv/mov/avi/webm/flv/ts 等常见音视频格式及微信语音 silk。"
+            "返回转写文本，多说话人音频按说话人分段（说话人0/1/2...）。"
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string", "description": "音频或视频文件路径"},
+                "speakers": {
+                    "type": "boolean",
+                    "description": "是否启用说话人分离（默认 true，单说话人时输出纯文本）",
+                    "default": True,
+                },
+                "out_path": {"type": "string", "description": "可选，结果另存为此路径"},
+            },
+            "required": ["file_path"],
+        },
+    }
+]
+
+
+def log(*a):
+    print(*a, file=sys.stderr, flush=True)
+
+
+def write(obj):
+    sys.stdout.write(json.dumps(obj, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def reply(msg_id, result):
+    write({"jsonrpc": "2.0", "id": msg_id, "result": result})
+
+
+def reply_error(msg_id, code, message):
+    write({"jsonrpc": "2.0", "id": msg_id, "error": {"code": code, "message": message}})
+
+
+def run_tool(args) -> str:
+    if "file_path" not in args:
+        raise ValueError("缺少必填参数: file_path")
+    src = Path(str(args["file_path"])).expanduser().resolve()
+    if not src.exists():
+        raise FileNotFoundError(f"文件不存在: {src}")
+    if src.suffix.lower() not in transcribe.SUPPORTED_EXTS:
+        raise ValueError(f"不支持的格式: {src.suffix}")
+    if not os.environ.get("DASHSCOPE_API_KEY"):
+        raise RuntimeError("未设置 DASHSCOPE_API_KEY 环境变量")
+    return transcribe.transcribe_file(
+        src,
+        with_speakers=bool(args.get("speakers", True)),
+        out=args.get("out_path"),
+    )
+
+
+def handle(msg: dict):
+    method = msg.get("method")
+    msg_id = msg.get("id")
+    params = msg.get("params") or {}
+
+    if method == "initialize":
+        requested = params.get("protocolVersion")
+        version = requested if isinstance(requested, str) else PROTOCOL_VERSION
+        reply(msg_id, {
+            "protocolVersion": version,
+            "capabilities": {"tools": {}},
+            "serverInfo": SERVER_INFO,
+        })
+    elif method == "notifications/initialized" or method == "notifications/cancelled":
+        pass
+    elif method == "tools/list":
+        reply(msg_id, {"tools": TOOLS})
+    elif method == "tools/call":
+        name = params.get("name")
+        args = params.get("arguments") or {}
+        if name != "transcribe":
+            reply_error(msg_id, -32602, f"未知工具: {name}")
+            return
+        try:
+            text = run_tool(args)
+            reply(msg_id, {"content": [{"type": "text", "text": text}]})
+        except Exception as ex:
+            reply(msg_id, {
+                "content": [{"type": "text", "text": f"转写失败: {ex}"}],
+                "isError": True,
+            })
+    elif method == "ping":
+        reply(msg_id, {})
+    elif msg_id is not None:
+        reply_error(msg_id, -32601, f"方法不存在: {method}")
+
+
+def main():
+    if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    log(f"{SERVER_INFO['name']} v{SERVER_INFO['version']} 已启动（stdio，等待客户端）")
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError as ex:
+            reply_error(None, -32700, f"JSON 解析失败: {ex}")
+            continue
+        handle(msg)
+
+
+if __name__ == "__main__":
+    main()

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli_mcp.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: audio-transcribe-cli-mcp
+Version: 0.1.0
+Summary: 音视频转文字 CLI / MCP Server：阿里云百炼录音文件识别，支持说话人分离与微信语音 SILK
+Author: OstrichHermit
+License: MIT
+Project-URL: Homepage, https://github.com/OstrichHermit/audio-transcribe
+Project-URL: Issues, https://github.com/OstrichHermit/audio-transcribe/issues
+Keywords: asr,speech-to-text,transcription,dashscope,qwen,audio,video,mcp,whisper-alternative
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dashscope
+Dynamic: license-file
+
+# audio-transcribe
+
+**音视频转文字，支持 CLI、MCP Server 两种形态：说话人分离，长音频免切片，原生支持微信语音 SILK 格式。**
+
+Audio/video transcription in both CLI and MCP Server flavors: speaker diarization, long-audio support with no manual splitting, and native WeChat SILK decoding.
+
+[English](README_EN.md) | 简体中文
+
+基于阿里云百炼录音文件识别接口（qwen-audio-asr 系列 / paraformer）。不依赖 Claude Code：可作为独立命令行工具，也可接入任意 MCP 客户端（Claude Desktop、Cursor 等）。
+
+## 功能特性
+
+- **全格式输入**：mp3 / wav / m4a / aac / flac / ogg / opus / amr / wma 及 mp4 / mkv / mov 等所有 ffmpeg 支持的音视频格式（视频自动抽取音轨）
+- **微信语音 SILK 原生支持**：自动识别并剥离微信 `0x02 + #!SILK_V3` 文件头，通过 [uv](https://docs.astral.sh/uv/) 临时环境调用 [pilk](https://github.com/foyoux/pilk) 解码（仅转写 silk 文件时需要 uv，其余格式零额外依赖）
+- **说话人分离**：多人对话按 `说话人N：内容` 分段输出；单一说话人自动退化为整段纯文本
+- **长音频免切片**：走百炼录音文件识别（filetrans）异步接口，一次上传整段处理，DashScope 临时存储转完自动删除
+- **清晰的输出约定**：stdout 只输出转写文本，进度 / 耗时 / 计费估算走 stderr，方便脚本和 Agent 调用
+- **内置 MCP Server**：`audio-transcribe-mcp` 命令，手写 MCP stdio 协议（JSON-RPC 2.0），仅标准库零第三方依赖，任意 MCP 客户端即插即用
+
+## 安装
+
+```bash
+pip install audio-transcribe-cli-mcp
+```
+
+也可从源码安装：
+
+```bash
+git clone https://github.com/OstrichHermit/audio-transcribe.git
+cd audio-transcribe
+pip install .
+```
+
+安装后会得到两个命令：`asr`（CLI）和 `audio-transcribe-mcp`（MCP Server）。
+
+### 安装为 Agent Skill（可选）
+
+仓库内附带 Agent Skill（`skills/audio-transcribe/SKILL.md`），把它复制到你所用 AI Agent 的 skills 目录，Agent 即可自动掌握本工具的用法。以 Claude Code 为例：
+
+```bash
+cp -r skills/audio-transcribe ~/.claude/skills/audio-transcribe
+```
+
+### 1. 安装依赖
+
+- Python 3.10+（`pip install .` 会自动安装 dashscope 依赖）
+- [ffmpeg / ffprobe](https://ffmpeg.org/) 自行安装并加入 PATH
+- 仅转写微信 SILK 文件时额外需要 [uv](https://docs.astral.sh/uv/)（脚本自动创建 Python 3.11 临时环境安装 pilk，无需手动操作）
+
+### 2. 配置 API Key
+
+在[阿里云百炼控制台](https://bailian.console.aliyun.com/)创建 API Key，配置到环境变量：
+
+```bash
+# Windows
+setx DASHSCOPE_API_KEY "sk-xxxx"
+
+# macOS / Linux
+echo 'export DASHSCOPE_API_KEY="sk-xxxx"' >> ~/.bashrc
+```
+
+默认直连百炼官方主域名，开箱即用。使用业务空间专属 key（`sk-ws-` 前缀）且分配了专属域名的用户，额外设置 `DASHSCOPE_BASE_URL` 即可（见下文[环境变量](#环境变量)）。
+
+## 使用方法
+
+```bash
+asr "<音频或视频文件路径>"
+asr "<文件>" --no-speakers   # 关闭说话人分离
+asr "<文件>" --out 结果.txt   # 保存到文件
+asr "<文件>" --keep-workdir   # 保留中间文件（调试）
+```
+
+示例：
+
+```bash
+$ asr meeting.mp4
+[1/4] ffmpeg 预处理: meeting.mp4
+[2/4] 上传音频（32.5 分钟）...
+[3/4] 提交识别任务...
+识别模型: qwen-audio-3.1-asr-flash-filetrans
+  识别中... 45s
+[4/4] 完成，耗时 78s，音频 32.5 分钟（计费约 0.06 元，按 3.1 Token 计费估算）
+说话人1：大家好，今天我们讨论一下项目排期……
+说话人2：好的，我先说下我这边的情况……
+```
+
+### 微信语音（SILK）
+
+微信语音消息文件（`*.silk`，含 `0x02 + #!SILK_V3` 头）直接作为输入传入即可，脚本自动完成剥头、pilk 解码（24kHz PCM）→ ffmpeg 封装 WAV → 正常识别管线。
+
+## 作为 MCP Server 接入
+
+任意支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor 等）都能接入：
+
+```bash
+# Claude Code
+claude mcp add audio-transcribe -- audio-transcribe-mcp
+```
+
+其他客户端在 MCP 配置 JSON 中添加（`env` 里按需配置 API Key，也可继承系统环境变量）：
+
+```json
+{
+  "mcpServers": {
+    "audio-transcribe": {
+      "command": "audio-transcribe-mcp",
+      "env": {
+        "DASHSCOPE_API_KEY": "sk-xxxx"
+      }
+    }
+  }
+}
+```
+
+也可以用模块方式启动：`python -m audio_transcribe_cli.mcp_server`。
+
+接入后客户端会得到一个 `transcribe` 工具：`file_path` 必填，`speakers`（说话人分离，默认开）和 `out_path`（结果另存）可选。
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `DASHSCOPE_API_KEY` | 百炼 API Key（必需） |
+| `DASHSCOPE_BASE_URL` | API 域名（可选）。默认 `https://dashscope.aliyuncs.com/api/v1`（官方主域名，开箱即用）；使用业务空间专属域名的用户设置为你的专属域名，例如 `https://xxxx.cn-beijing.maas.aliyuncs.com/api/v1` |
+| `ASR_WORKSPACE` | 中间文件（转码 / 切片临时目录）的根目录（可选）。默认系统临时目录，转写完成自动清理 |
+
+## 计费说明
+
+- 主模型 `qwen-audio-3.1-asr-flash-filetrans` 按 Token 计费（输入 25 Token/秒 × 0.8 元/百万 + 输出 2.7 元/百万），约 **0.11 元/小时**音频
+- 识别失败自动降级尝试 `paraformer-v2`
+- 脚本结束会在 stderr 输出本次计费估算
+
+## 已知限制
+
+- 同步提交的文件大小受 DashScope 限制，超长音频依赖 filetrans 异步接口（脚本已处理，无需切片）
+- 说话人编号（说话人1 / 说话人2）与真实人物的对应关系需要结合内容自行判断
+- SILK 解码依赖 pilk 的预编译 wheel（cp311 及以下），通过 uv 临时环境解决，首次运行需下载环境，之后走缓存

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/audio_transcribe_cli/__init__.py
+src/audio_transcribe_cli/cli.py
+src/audio_transcribe_cli/mcp_server.py
+src/audio_transcribe_cli_mcp.egg-info/PKG-INFO
+src/audio_transcribe_cli_mcp.egg-info/SOURCES.txt
+src/audio_transcribe_cli_mcp.egg-info/dependency_links.txt
+src/audio_transcribe_cli_mcp.egg-info/entry_points.txt
+src/audio_transcribe_cli_mcp.egg-info/requires.txt
+src/audio_transcribe_cli_mcp.egg-info/top_level.txt

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli_mcp.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+asr = audio_transcribe_cli.cli:main
+audio-transcribe-mcp = audio_transcribe_cli.mcp_server:main

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli_mcp.egg-info/requires.txt

@@ -0,0 +1 @@
+dashscope

audio_transcribe_cli_mcp-0.1.0/src/audio_transcribe_cli_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+audio_transcribe_cli