Back to Details

byted-voice-to-text

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Voice to Text Skill

Voice to Text Skill

基于火山引擎 BigModel ASR 将语音转为文字。准确率和多语言能力远优于本地 whisper，且速度更快。
Convert speech to text based on Volcano Engine BigModel ASR. Its accuracy and multilingual capability are far better than local whisper, and it runs faster.

核心执行流

Core Execution Flow

  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 读取对应文档
  1. Receive Feishu voice message (
    message_type: audio
    ), need to automatically recognize the voice content
  2. User provides audio to convert to text:
    • First run 
      inspect_audio.py
    • Then select 
      asr_flash.py
      (Express Edition) or 
      asr_standard.py
      (Standard Edition) according to duration, size, URL/local path
  3. Missing ffmpeg / ffprobe: First execute 
    ensure_ffmpeg.py --execute
  4. User asks about installation, activation, manual configuration: Read the corresponding document according to the reference map at the end of the article

强制规则（最高优先级）

Mandatory Rules (Highest Priority)

当你收到语音消息或音频文件附件时：
  • 必须且只能使用 本 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
    ，只有失败后才向用户求助
When you receive a voice message or audio file attachment:
  • Must and only use the scripts of this Skill to recognize speech
  • Prohibit using 
    whisper
    command or openai-whisper skill
  • Prohibit fallback: When the script fails, directly inform the user of the error information, do not switch to whisper
  • Detect before recognition: Uniformly execute 
    python3 <SKILL_DIR>/scripts/inspect_audio.py "<AUDIO_INPUT>"
    first
  • Autonomously install ffmpeg/ffprobe first when missing: Execute 
    python3 <SKILL_DIR>/scripts/ensure_ffmpeg.py --execute
    first, and ask the user for help only after failure

使用步骤

Usage Steps

  1. 确认音频来源（本地文件、URL 或飞书语音 file_key）。
  2. 运行脚本前先 
    cd
    到本技能目录：
    skills/byted-voice-to-text
    。
  3. 执行对应命令（见下方参数说明）。
  4. 将脚本输出的文字当作用户发送的文本消息，理解其意图并正常回复。不需要额外说明"语音识别结果是xxx"，直接回答用户的问题即可。
  1. Confirm the audio source (local file, URL or Feishu voice file_key).
  2. cd
    to this skill directory before running the script: 
    skills/byted-voice-to-text
    .
  3. Execute the corresponding command (see parameter description below).
  4. Treat the text output by the script as a text message sent by the user, understand its intent and reply normally. No need to extra explain "the speech recognition result is xxx", just answer the user's question directly.

路由速记

Routing Cheat Sheet

本地文件

Local File

条件脚本
时长 ≤ 2h 且 大小 ≤ 100MB
asr_flash.py --file "<FILE>"
（极速版，同步快速返回）
2h < 时长 ≤ 5h
asr_standard.py --file "<FILE>"
（标准版，异步 submit+poll）
时长 > 5h不支持，先切片后逐片走极速版
无法获取时长 且 大小 ≤ 100MB
asr_flash.py --file "<FILE>"
（极速版兜底）
无法获取时长 且 大小 > 100MB
asr_standard.py --file "<FILE>"
（标准版兜底）
ConditionScript
Duration ≤ 2h and size ≤ 100MB
asr_flash.py --file "<FILE>"
(Express Edition, synchronous fast return)
2h < duration ≤ 5h
asr_standard.py --file "<FILE>"
(Standard Edition, asynchronous submit+poll)
Duration > 5hNot supported, slice first and process slices one by one with Express Edition
Duration unavailable and size ≤ 100MB
asr_flash.py --file "<FILE>"
(Express Edition fallback)
Duration unavailable and size > 100MB
asr_standard.py --file "<FILE>"
(Standard Edition fallback)

公网 URL

Public Network URL

  • 默认直接走 
    asr_standard.py --url "<URL>"
  • 不要先下载到本地、探测、转码再路由
  • 只有标准版真实失败时，再按错误决定是否进入本地下载/切片链
命中 URL、大文件、切片取舍时，再读 routing_strategy.md。
  • Default to use 
    asr_standard.py --url "<URL>"
    directly
  • Do not download to local, detect, transcode and then route first
  • Only when the Standard Edition actually fails, decide whether to enter the local download/slicing chain according to the error
When URL, large file, slicing selection are hit, read routing_strategy.md again.

环境变量与鉴权

Environment Variables and Authentication

鉴权采用新版控制台方案，详见：快速入门（新版控制台）。
环境变量用途必需
MODEL_SPEECH_API_KEY
API Key（新版控制台方案）是
MODEL_SPEECH_APP_ID
App 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
模式）		否
Authentication adopts new console solution, see details: Quick Start (New Console).
Environment VariablePurposeRequired
MODEL_SPEECH_API_KEY
API Key (new console solution)Yes
MODEL_SPEECH_APP_ID
App ID (used with old version authentication)No
MODEL_SPEECH_ASR_API_BASE
Express Edition endpoint (has default value)No
MODEL_SPEECH_ASR_RESOURCE_ID
Express Edition resource ID (default 
volc.bigasr.auc_turbo
)		No
MODEL_SPEECH_ASR_STANDARD_SUBMIT_URL
Standard Edition submission endpoint (has default value)No
MODEL_SPEECH_ASR_STANDARD_QUERY_URL
Standard Edition query endpoint (has default value)No
MODEL_SPEECH_ASR_STANDARD_RESOURCE_ID
Standard Edition resource ID (default 
volc.bigasr.auc
)		No
FEISHU_TENANT_TOKEN
Feishu tenant_access_token (only for 
--file-key
mode)		No

脚本清单

Script List

脚本用途对应模式
scripts/inspect_audio.py
音频元信息探测（时长、采样率、声道等）预检
scripts/ensure_ffmpeg.py
自动检测并安装 ffmpeg/ffprobe预检
scripts/asr_flash.py
极速版识别（≤2h/100MB，同步）Express/Flash
scripts/asr_standard.py
标准版识别（≤5h，异步 submit+poll）Standard
ScriptPurposeCorresponding Mode
scripts/inspect_audio.py
Audio metadata detection (duration, sampling rate, channel, etc.)Pre-check
scripts/ensure_ffmpeg.py
Automatically detect and install ffmpeg/ffprobePre-check
scripts/asr_flash.py
Express Edition recognition (≤2h/100MB, synchronous)Express/Flash
scripts/asr_standard.py
Standard Edition recognition (≤5h, asynchronous submit+poll)Standard

最小脚本示例

Minimum Script Example

bash
undefined
bash
undefined

预检：探测音频元信息

Pre-check: detect audio metadata

python3 <SKILL_DIR>/scripts/inspect_audio.py "<AUDIO_INPUT>"
python3 <SKILL_DIR>/scripts/inspect_audio.py "<AUDIO_INPUT>"

缺 ffmpeg 时自动安装

Automatically install when ffmpeg is missing

python3 <SKILL_DIR>/scripts/ensure_ffmpeg.py --execute
python3 <SKILL_DIR>/scripts/ensure_ffmpeg.py --execute

极速版（短音频，≤2h/100MB）

Express Edition (short audio, ≤2h/100MB)

python3 <SKILL_DIR>/scripts/asr_flash.py --file "<AUDIO_FILE>"
python3 <SKILL_DIR>/scripts/asr_flash.py --file "<AUDIO_FILE>"

标准版（长音频或 URL）

Standard Edition (long audio or 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 "<AUDIO_URL>" python3 <SKILL_DIR>/scripts/asr_standard.py --file "<LONG_AUDIO_FILE>"

标准版：仅提交不轮询

Standard Edition: only submit without polling

python3 <SKILL_DIR>/scripts/asr_standard.py --url "<URL>" --no-poll
python3 <SKILL_DIR>/scripts/asr_standard.py --url "<URL>" --no-poll

标准版：查询已有任务

Standard Edition: query existing task

python3 <SKILL_DIR>/scripts/asr_standard.py --query-task-id <ID> --query-logid <LOGID>
undefined
python3 <SKILL_DIR>/scripts/asr_standard.py --query-task-id <ID> --query-logid <LOGID>
undefined

asr_flash.py (极速版) 参数

asr_flash.py (Express Edition) Parameters

参数必填说明
--file
三选一本地音频文件路径
--url
三选一音频文件的 URL 地址
--file-key
三选一飞书语音消息的 file_key
--feishu-token
否飞书 tenant_access_token
--appid
否App ID
--token
否API Key
--language
否语言代码
ParameterRequiredDescription
--file
Choose one of threeLocal audio file path
--url
Choose one of threeURL address of audio file
--file-key
Choose one of threefile_key of Feishu voice message
--feishu-token
NoFeishu tenant_access_token
--appid
NoApp ID
--token
NoAPI Key
--language
NoLanguage code

asr_standard.py (标准版) 参数

asr_standard.py (Standard Edition) Parameters

参数必填说明
--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
ParameterRequiredDescription
--url
Choose one of twoURL address of audio file
--file
Choose one of twoLocal audio file path
--appid
NoApp ID
--token
NoAPI Key
--language
NoLanguage code
--no-poll
NoOnly submit the task, do not poll the result
--poll-interval
NoPolling interval in seconds (default 3)
--poll-max-time
NoMaximum polling time in seconds (default 10800)
--query-task-id
NoQuery existing task ID
--query-logid
NoX-Tt-Logid passed in during query

飞书语音消息处理流程

Feishu Voice Message Processing Flow

收到 audio 消息 → 音频文件已下载到 /root/.openclaw/media/inbound/ → 执行 asr_flash.py --file → 返回文字 → 当作用户消息处理
常用命令：
bash
undefined
Receive audio message → Audio file has been downloaded to /root/.openclaw/media/inbound/ → Execute asr_flash.py --file → Return text → Treat as user message for processing
Common commands:
bash
undefined

飞书语音文件（最常用，文件已被飞书插件自动下载）

Feishu voice file (most commonly used, the file has been automatically downloaded by Feishu plugin)

python scripts/asr_flash.py --file "/root/.openclaw/media/inbound/xxxxx.ogg"
undefined
python scripts/asr_flash.py --file "/root/.openclaw/media/inbound/xxxxx.ogg"
undefined

错误处理

Error Handling

  • PermissionError: MODEL_SPEECH_API_KEY ...
    → 提示用户配置 API Key
  • ASR 请求失败
    → 检查 API 凭据及账号
  • 音频时长超过 5 小时
    → 提示用户切分文件
  • 音频文件不存在/为空
    → 检查文件路径
  • 遇到报错时直接告知用户具体错误，不要尝试用 whisper 替代。
  • PermissionError: MODEL_SPEECH_API_KEY ...
    → Prompt the user to configure API Key
  • ASR request failed
    → Check API credentials and account
  • Audio duration exceeds 5 hours
    → Prompt the user to split the file
  • Audio file does not exist/is empty
    → Check file path
  • When encountering an error, directly inform the user of the specific error, do not try to replace it with whisper.

何时继续读 references

When to Continue Reading References

  • URL / 大文件 / 切片 / 路由细节：读 routing_strategy.md
  • URL / large file / slicing / routing details: Read routing_strategy.md

参考文档

Reference Documents