mcpField
F
fun-asr

fun-asr

github.com/wmy2981创意与媒体164 次安装5 周前更新
代码仓库

关于 fun-asr

Fun-ASR 是一项命令行技能，通过 Alibaba Cloud DashScope 的异步 Fun-ASR 服务转写音频。它支持说话人区分、语言提示，以及文本、JSON 或 SRT 输出，适用于音频处理流程。

主要功能

  1. 01通过 Fun-ASR 转写音频
  2. 02支持说话人区分
  3. 03可指定语言提示
  4. 04输出文本、JSON 或 SRT
  5. 05通过兼容 S3 的存储上传音频

适用场景

  1. 01将会议录音转为文本
  2. 02生成带说话人标记的访谈稿
  3. 03为讲座制作 SRT 字幕

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wmy2981/skills --skill fun-asr

安装后在 Claude Code 中输入/fun-asr确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.claude-plugin/
plugin.json
references/
api_doc.md
guide.md
scripts/
.env.example
fun_asr_cli.py
requirements.txt

详细介绍

Fun-ASR：音频转写

使用 Alibaba Cloud DashScope 的 Fun-ASR 非实时语音识别模型转写音频文件。支持说话人分离、多语言识别和多种输出格式（纯文本、JSON、SRT 字幕）。

工作流

Audio → S3 → Fun-ASR async → Poll → Save file → Agent reads

要求

环境变量

将以下变量设置在 ~/.wmyskills/.env（所有技能共享），或 scripts/.env（优先级更高）中。使用 scripts/.env.example 作为模板——将变量添加到 ~/.wmyskills/.env，切勿覆盖已有文件：

变量必填描述
DASHSCOPE_API_KEY是Alibaba Cloud DashScope API 密钥（或使用 BAILIAN_APIKEY）
BAILIAN_APIKEY是*DASHSCOPE_API_KEY 的替代项（Bailian/DashScope）
S3_ENDPOINT是兼容 S3 的存储端点 URL
S3_BUCKET是用于上传音频的 S3 存储桶名称
S3_REGION否S3 区域（默认值：us-east-1）
S3_PREFIX否上传文件的键前缀（默认值：asr-uploads）
AWS_ACCESS_KEY_ID否*AWS 访问密钥（未使用 IAM/默认凭证链时需要）
AWS_SECRET_ACCESS_KEY否*AWS 秘密密钥（未使用 IAM/默认凭证链时需要）

脚本会自动从 ~/.wmyskills/.env 和 scripts/.env 加载 .env 文件（脚本目录优先）。

Python 依赖
pip install boto3 requests python-dotenv
可选：ffmpeg

以下用途需要 ffmpeg/ffprobe：

  • 检测音频声道数
  • 将多声道音频转换为单声道（说话人分离所需）

如果没有 ffmpeg，脚本会跳过单声道转换并使用原始文件。

用法

python fun_asr_cli.py <audio-file> [options]

从 scripts/ 目录运行，或提供 fun_asr_cli.py 的完整路径。

位置参数
参数描述
file音频文件路径（aac、wav、mp3、m4a、flac、ogg 等）
选项
选项默认值描述
--modelfun-asrASR 模型：fun-asr、paraformer-v2、paraformer-v1、fun-asr-mtl、paraformer-mtl-v1
--no-diarization（已启用）禁用说话人分离
--languagezh语言提示：zh、en、ja、ko、yue 等
--channel-id0要转写的音频声道（0 = 第一声道/单声道）
--output自动生成自定义输出文件路径（默认值：~/.wmyskills/fun-asr/outputs/）
--formattext输出格式：text、json、srt
--keep-s3（关闭）转写后保留 S3 上已上传的文件
--version—显示脚本版本并退出
示例
# Basic transcription (text format, Chinese)
python fun_asr_cli.py meeting.mp3

# JSON output with full metadata (timestamps, speaker IDs, confidence)
python fun_asr_cli.py interview.wav --format json

# SRT subtitle output
python fun_asr_cli.py lecture.mp3 --format srt

# Disable speaker diarization
python fun_asr_cli.py meeting.mp3 --no-diarization

# Specify language and model
python fun_asr_cli.py japanese_audio.mp3 --language ja --model paraformer-v2

# Custom output path
python fun_asr_cli.py audio.wav --output ~/Desktop/transcript.txt

输出格式

text（默认）

纯文本，带说话人标签和时间戳：[Speaker N] HH:MM:SS - HH:MM:SS，后接文本内容。

json

包含所有元数据的完整 JSON——时间戳、说话人 ID、置信度分数和原始 API 响应。

srt

标准 SRT 字幕格式：NN \n HH:MM:SS,mmm --> HH:MM:SS,mmm \n [SN] text。

执行规则

直接运行用户请求的命令，不要预先检查依赖项、环境变量或配置。如果有问题，脚本会报错并给出清晰提示——届时再检查并修复。

Agent 指令

转写完成后

转写输出会保存到文件中——文本内容不会打印到 stdout。stdout 中唯一打印的行是 Output file: <path>，用于告知结果文件的保存位置。默认输出目录为 ~/.wmyskills/fun-asr/outputs/。

转写成功时，stdout 中仅包含：Output file: <path>。信息和错误日志会发送到 stderr。

成功后，你必须向用户提供结果：

  1. 从 stdout 中解析 Output file: 路径
  2. 读取文件内容并呈现给用户
  3. 提供简短摘要：音频时长、检测到的说话人数（如果启用了说话人分离），以及内容概要
错误场景

脚本会以特定代码退出，便于程序处理：

  • 代码 2 — 配置错误：缺少环境变量。argparse 遇到无效参数时（例如未知标志、无效模型名称）也会使用此代码。
  • 代码 3 — 文件错误：文件不存在、文件过大或超出限制。
  • 代码 4 — API/网络错误：提交或轮询失败。
  • 代码 6 — 任务失败：ASR API 返回错误。请查看错误消息。
  • 代码 7 — 超时：转录耗时超过 30 分钟。
重要规则
  • 未检测到有效语音：如果 API 返回 ASR_RESPONSE_HAVE_NO_WORDS 或 SUCCESS_WITH_NO_VALID_FRAGMENT，则音频中没有可检测到的人声（静音、音量过低或纯噪声）。**请立即停止并告知用户。不要自动重试、切换模型或修改音频参数。**只有在用户明确要求时才重试。
  • 说话人分离要求使用时长不超过 2 小时的单声道音频。脚本会通过 ffmpeg 自动转换多声道音频。如果文件时长超过 2 小时，则会自动禁用说话人分离。
  • 说话人分离费用：无论是否启用说话人分离，脚本都按音频秒数收费；启用此功能不额外收费。
  • S3 清理：转录完成后会自动删除 S3 上的临时文件，除非传入 --keep-s3。
  • 定价：Fun-ASR 的费用为每秒音频 CNY 0.00022。脚本会在开始前估算费用，并在完成时报告实际费用。

评论

支持 Markdown