Voice to Text Skill

Core Execution Flow

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)

• 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. 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

asr_flash.py --file "<FILE>"

asr_standard.py --file "<FILE>"

asr_flash.py --file "<FILE>"

asr_standard.py --file "<FILE>"

Public Network URL

• 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

Environment Variables and Authentication

MODEL_SPEECH_API_KEY

MODEL_SPEECH_APP_ID

MODEL_SPEECH_ASR_API_BASE

MODEL_SPEECH_ASR_RESOURCE_ID

volc.bigasr.auc_turbo

MODEL_SPEECH_ASR_STANDARD_SUBMIT_URL

MODEL_SPEECH_ASR_STANDARD_QUERY_URL

MODEL_SPEECH_ASR_STANDARD_RESOURCE_ID

volc.bigasr.auc

FEISHU_TENANT_TOKEN

--file-key

Script List

scripts/inspect_audio.py

scripts/ensure_ffmpeg.py

scripts/asr_flash.py

scripts/asr_standard.py

Minimum Script Example

# Pre-check: detect audio metadata
python3 <SKILL_DIR>/scripts/inspect_audio.py "<AUDIO_INPUT>"

# Automatically install when ffmpeg is missing
python3 <SKILL_DIR>/scripts/ensure_ffmpeg.py --execute

# Express Edition (short audio, ≤2h/100MB)
python3 <SKILL_DIR>/scripts/asr_flash.py --file "<AUDIO_FILE>"

# 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>"

# Standard Edition: only submit without polling
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>

asr_flash.py (Express Edition) Parameters

--file

--url

--file-key

--feishu-token

--appid

--token

--language

asr_standard.py (Standard Edition) Parameters

--url

--file

--appid

--token

--language

--no-poll

--poll-interval

--poll-max-time

--query-task-id

--query-logid

Feishu Voice Message Processing Flow

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

# 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"

Error Handling

• 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.

When to Continue Reading References

• URL / large file / slicing / routing details: Read routing_strategy.md

Reference Documents

• Volcano Engine BigModel ASR
• Quick Start (New Console) — Authentication and activation
• API Key Usage