byted-voice-to-text

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 の使用は禁止です
• フォールバックは禁止です：スクリプトが失敗した場合は、エラー情報をそのままユーザーに伝え、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. スクリプトを実行する前に、まず本スキルのディレクトリ skills/byted-voice-to-text に cd します。
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	3つのうちいずれか	ローカル音声ファイルのパス
--url	3つのうちいずれか	音声ファイルの URL
--file-key	3つのうちいずれか	飛書の音声メッセージの file_key
--feishu-token	いいえ	飛書 tenant_access_token
--appid	いいえ	App ID
--token	いいえ	API Key
--language	いいえ	言語コード

asr_standard.py（標準版）のパラメーター

パラメーター	必須	説明
--url	2つのうちいずれか	音声ファイルの URL
--file	2つのうちいずれか	ローカル音声ファイルのパス
--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 の使用