SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsvoice-to-text

voice-to-text

General & other

View repository

Updated 10-15 17:30

About this skill

Voice to Text Skill

Based onVolcengine BigModel ASR to convert speech to text. Accuracy and multilingual capability are far superior to local whisper, and it is faster.

Use Cases

  1. Received a Feishu voice message (message_type: audio), need to automatically recognize the speech content
  2. Received an audio file attachment (.ogg、.mp3、.wav）
  3. The user mentions "speech recognition", "speech-to-text", "ASR"

Mandatory Rules (Highest Priority)

When you receive a voice message or audio file attachment:

  • Must and can only use this Skill's asr.py script to recognize speech
  • Forbidden to use whisper command or openai-whisper skill
  • Fallback forbidden: if asr.py fails to execute, directly inform the user of the error message, do not switch to whisper

Usage Steps

  1. Confirm the audio source (local file, URL, or Feishu voice file_key).
  2. Before running the script, first cd to this skill directory:skills/voice-to-text。
  3. Execute the corresponding command (see parameter description below).
  4. Treat the text output by the scriptas the text message sent by the user, understand its intent and reply normally. No need to additionally state "the speech recognition result is xxx", just directly answer the user's question.

Environment Variables and Authentication

Authentication usesNew Console Solution, see:Quick Start (New Console)、API Key Usage。

Configuration required before use:

  • Recommended (New Console)：MODEL_SPEECH_API_KEY — Activate the Recording File Recognition Express Edition in the Doubao Speech New Console, and create/obtain an API Key.
  • Compatible with Old Version: if both MODEL_SPEECH_APP_ID and MODEL_SPEECH_API_KEYare configured, the old X-Api-App-Key / X-Api-Access-Key authentication is used.
  • Optional：MODEL_SPEECH_ASR_API_BASE(ASR API endpoint, default BigModel Flash),MODEL_SPEECH_ASR_RESOURCE_ID(Resource ID, default volc.bigasr.auc_turbo）。
  • Feishu-related：FEISHU_TENANT_TOKEN(Feishu tenant_access_token, only needed when using --file-key mode).

Script Parameters

Parameter Required Description
--file Choose one of three Local audio file path
--url Choose one of three URL address of the audio file
--file-key Choose one of three file_key of the Feishu voice message
--feishu-token No Feishu tenant_access_token (can also be set via FEISHU_TENANT_TOKEN environment variable)
--appid No Volcengine ASR App ID (can also be set via MODEL_SPEECH_APP_ID environment variable)
--token No Volcengine ASR API Key (can also be set via MODEL_SPEECH_API_KEY environment variable)
--language No Language code, e.g. zh-CN、ja-JP、en-US(if not passed, automatic recognition)

Return Value Description

The script outputs plain text to stdout, which is what the user says. If it fails, stdout will contain an error message starting with [voice-to-text ERROR] .

Feishu voice message processing flow

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

Common commands:

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

Error handling

  • If the error PermissionError: MODEL_SPEECH_API_KEY ... 需在环境变量中配置is reported: prompt the user to followQuick start (new console)to activate the recording file recognition speed version, and obtain and configure MODEL_SPEECH_API_KEY, write it to the environment variable file under the workspace, and retry.
  • If the error ASR 请求失败is reported: based on the error code and message, prompt the user to check whether the API credentials and account have activated the Doubao voice service.
  • If the error 音频文件不存在 or 音频文件为空is reported: check whether the file path is correct.
  • When an error occurs, directly inform the user of the specific error; do not try to use whisper as a substitute.

Reference documentation

Example

# 本地音频文件（最常用）
python scripts/asr.py --file "/root/.openclaw/media/inbound/xxxxx.ogg"

# 音频 URL
python scripts/asr.py --url "https://example.com/audio.mp3"

# 指定语言
python scripts/asr.py --file "/path/to/audio.ogg" --language "ja-JP"

# 飞书 file_key（需要 tenant_token）
python scripts/asr.py --file-key "file_v2_xxxx" --feishu-token "t-g104xxx"