Byted Voice To Text

语音转文字（ASR）。使用火山引擎 BigModel ASR 识别语音，包含极速版（≤2h/100MB 同步快速返回）和标准版（≤5h 异步识别）两种模式。支持飞书语音消息、本地音频文件及音频 URL。当收到语音消息或音频附件（.ogg/.mp3/.wav）时使用本技能。

Security Scan

The skill implements the described Volcengine ASR flows and looks coherent for voice→text, but it contains unexpected credential-fetching/persistence behavior (api_key.py) and autodetection/install steps that you should review before trusting it with secrets or running autonomously.

Purpose & Capability

Name/description match the code and scripts: the skill implements Volcengine (火山引擎) BigModel ASR calls for short (flash) and long (standard) audio, supports local files, URLs and Feishu file_key. Requested/declared env vars in SKILL.md (MODEL_SPEECH_API_KEY plus several optional ASR/Feishu vars) align with the stated purpose. The only surprise is api_key.py which can attempt to obtain MODEL_SPEECH_API_KEY from an ARK service when MODEL_SPEECH_API_KEY is missing — that behavior is not documented in SKILL.md.

Instruction Scope

SKILL.md instructs the agent to always run the included scripts and never fall back to other ASR (e.g., whisper). The scripts perform network calls to Volcengine endpoints and (when using --file-key) to Feishu. api_key.py may query an external ARK API base (if ARK_SKILL_API_KEY / ARK_SKILL_API_BASE are present) and will persist an obtained key into a .env file in the skill directory. The run/install instructions also direct autonomous installation of ffmpeg via ensure_ffmpeg.py --execute, which will run package-manager commands (possibly via sudo). These runtime actions go beyond pure transcription (credential retrieval/persistence and package installs).

Install Mechanism

No install spec; code is instruction + local Python scripts. ensure_ffmpeg.py intentionally restricts itself to package-manager installs (brew/apt/dnf/yum/winget/choco/zypper) and avoids arbitrary URL downloads. requirements.txt only lists requests. No remote code fetch/install from untrusted URLs is present in the provided files.

Credentials

Declared required env var is MODEL_SPEECH_API_KEY (reasonable). However, api_key.py reads additional environment variables (ARK_SKILL_API_KEY, ARK_SKILL_API_BASE) and, if present, will call that base to list/create API keys and then persist MODEL_SPEECH_API_KEY to a .env file. Those ARK_* variables are not declared in SKILL.md's required list. The skill also reads optional variables (MODEL_SPEECH_APP_ID, FEISHU_TENANT_TOKEN, various MODEL_SPEECH_* endpoints) which are documented as optional. The undocumented ARK-based credential discovery and local persistence increases the credential scope unexpectedly.

Persistence & Privilege

The skill does not request always:true and is user-invocable only. It will, however, attempt to persist a discovered MODEL_SPEECH_API_KEY into a .env file within the skill directory (api_key.py) and may execute system package-manager commands via ensure_ffmpeg.py --execute (which can use sudo if available). These are legitimate behaviors for a local tool but are persistent and can alter the environment and system packages; be cautious running them on sensitive hosts.

What to consider before installing

This skill largely does what it says (calls Volcengine ASR for audio→text, handles Feishu files, and installs ffmpeg via package managers). Before installing or running it: (1) be aware api_key.py can attempt to obtain MODEL_SPEECH_API_KEY automatically if ARK_SKILL_API_KEY and ARK_SKILL_API_BASE are present — and it will write the retrieved key into a .env file in the skill folder; only set those ARK_* env vars if you trust that service. (2) ensure_ffmpeg.py may run package-manager commands (possibly via sudo) to install ffmpeg — run in an environment where that is acceptable. (3) the skill will send audio data to Volcengine endpoints and may download Feishu files if given a token — only provide FEISHU_TENANT_TOKEN or MODEL_SPEECH_API_KEY that you are comfortable having used in this way. (4) the SKILL.md instructs agents to treat transcribed text as if the user typed it (no attribution); consider whether that behavior is appropriate. If you need higher assurance, inspect or run the scripts in an isolated VM/container, remove or audit the api_key.py auto-fetch logic, or set MODEL_SPEECH_API_KEY explicitly and avoid providing ARK_SKILL_* environment variables.

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 且 大小 ≤ 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>" （标准版兜底）

公网 URL

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

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

环境变量与鉴权

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

环境变量	用途	必需
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 模式）	否

脚本清单

脚本	用途	对应模式
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

最小脚本示例

# 预检：探测音频元信息
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

飞书语音消息处理流程

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

常用命令：

# 飞书语音文件（最常用，文件已被飞书插件自动下载）
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 使用