Voice to Text Skill#

基于 火山引擎 BigModel ASR 将语音转为文字。准确率和多语言能力远优于本地 whisper，且速度更快。

核心执行流#

1. 收到飞书语音消息（ message_type: audio），需要自动识别语音内容

2. 用户给音频要转文字：

   • 先跑 inspect_audio.py
   • 再按时长、大小、URL/本地路径选择 asr_flash.py（极速版）或 asr_standard.py（标准版）

3. 缺 ffmpeg / ffprobe：先执行 ensure_ffmpeg.py --execute

4. 用户问安装、开通、手工配置：按文末 reference map 读取对应文档

强制规则（最高优先级）#

当你收到语音消息或音频文件附件时：

• 必须且只能使用 本 Skill 的脚本来识别语音
• 禁止使用 whisper 命令或 openai-whisper skill
• 禁止 fallback：脚本失败时直接将错误信息告知用户，不要改用 whisper
• 先探测后识别：统一先执行 python3 <SKILL_DIR>/scripts/inspect_audio.py "<AUDIO_INPUT>"
• 缺 ffmpeg/ffprobe 先自治安装：先执行 python3 <SKILL_DIR>/scripts/ensure_ffmpeg.py --execute，只有失败后才向用户求助

使用步骤#

1. 确认音频来源（本地文件、URL 或飞书语音 file_key）。
2. 运行脚本前先 cd 到本技能目录： skills/byted-voice-to-text。
3. 执行对应命令（见下方参数说明）。
4. 将脚本输出的文字 当作用户发送的文本消息，理解其意图并正常回复。不需要额外说明"语音识别结果是xxx"，直接回答用户的问题即可。

路由速记#

本地文件#

条件脚本时长 ≤ 2h 且 大小 ≤ 100MBasr_flash.py --file "<FILE>" （极速版，同步快速返回）2h < 时长 ≤ 5hasr_standard.py --file "<FILE>" （标准版，异步 submit+poll）时长 > 5h不支持，先切片后逐片走极速版无法获取时长 且 大小 ≤ 100MBasr_flash.py --file "<FILE>" （极速版兜底）无法获取时长 且 大小 > 100MBasr_standard.py --file "<FILE>" （标准版兜底）

公网 URL#

• 默认直接走 asr_standard.py --url "<URL>"
• 不要先下载到本地、探测、转码再路由
• 只有标准版真实失败时，再按错误决定是否进入本地下载/切片链

命中 URL、大文件、切片取舍时，再读 routing_strategy.md。

环境变量与鉴权#

鉴权采用 新版控制台方案，详见： 快速入门（新版控制台）。

环境变量用途必需MODEL_SPEECH_API_KEYAPI Key（新版控制台方案）是MODEL_SPEECH_APP_IDApp ID（旧版鉴权时配合使用）否MODEL_SPEECH_ASR_API_BASE极速版端点（有默认值）否MODEL_SPEECH_ASR_RESOURCE_ID极速版资源 ID（默认 volc.bigasr.auc_turbo）否MODEL_SPEECH_ASR_STANDARD_SUBMIT_URL标准版提交端点（有默认值）否MODEL_SPEECH_ASR_STANDARD_QUERY_URL标准版查询端点（有默认值）否MODEL_SPEECH_ASR_STANDARD_RESOURCE_ID标准版资源 ID（默认 volc.bigasr.auc）否FEISHU_TENANT_TOKEN飞书 tenant_access_token（仅 --file-key 模式）否

脚本清单#

脚本用途对应模式scripts/inspect_audio.py音频元信息探测（时长、采样率、声道等）预检scripts/ensure_ffmpeg.py自动检测并安装 ffmpeg/ffprobe预检scripts/asr_flash.py极速版识别（≤2h/100MB，同步）Express/Flashscripts/asr_standard.py标准版识别（≤5h，异步 submit+poll）Standard

最小脚本示例#

bash

# 预检：探测音频元信息
python3 <SKILL_DIR>/scripts/inspect_audio.py "<AUDIO_INPUT>"

# 缺 ffmpeg 时自动安装
python3 <SKILL_DIR>/scripts/ensure_ffmpeg.py --execute

# 极速版（短音频，≤2h/100MB）
python3 <SKILL_DIR>/scripts/asr_flash.py --file "<AUDIO_FILE>"

# 标准版（长音频或 URL）
python3 <SKILL_DIR>/scripts/asr_standard.py --url "<AUDIO_URL>"
python3 <SKILL_DIR>/scripts/asr_standard.py --file "<LONG_AUDIO_FILE>"

# 标准版：仅提交不轮询
python3 <SKILL_DIR>/scripts/asr_standard.py --url "<URL>" --no-poll

# 标准版：查询已有任务
python3 <SKILL_DIR>/scripts/asr_standard.py --query-task-id <ID> --query-logid <LOGID>

asr_flash.py (极速版) 参数#

参数必填说明--file三选一本地音频文件路径--url三选一音频文件的 URL 地址--file-key三选一飞书语音消息的 file_key--feishu-token否飞书 tenant_access_token--appid否App ID--token否API Key--language否语言代码

asr_standard.py (标准版) 参数#

参数必填说明--url二选一音频文件的 URL 地址--file二选一本地音频文件路径--appid否App ID--token否API Key--language否语言代码--no-poll否仅提交任务，不轮询结果--poll-interval否轮询间隔秒数（默认 3）--poll-max-time否最大轮询时间秒数（默认 10800）--query-task-id否查询已有任务 ID--query-logid否查询时传入的 X-Tt-Logid

飞书语音消息处理流程#

text

收到 audio 消息 → 音频文件已下载到 /root/.openclaw/media/inbound/ → 执行 asr_flash.py --file → 返回文字 → 当作用户消息处理

常用命令：

bash

# 飞书语音文件（最常用，文件已被飞书插件自动下载）
python scripts/asr_flash.py --file "/root/.openclaw/media/inbound/xxxxx.ogg"

错误处理#

• PermissionError: MODEL_SPEECH_API_KEY ... → 提示用户配置 API Key
• ASR 请求失败 → 检查 API 凭据及账号
• 音频时长超过 5 小时 → 提示用户切分文件
• 音频文件不存在/为空 → 检查文件路径
• 遇到报错时直接告知用户具体错误，不要尝试用 whisper 替代。

何时继续读 references#

• URL / 大文件 / 切片 / 路由细节：读 routing_strategy.md

参考文档#

• 火山引擎 BigModel ASR
• 快速入门（新版控制台） — 鉴权与开通
• API Key 使用