Qqbot Voice Transcribe

QQ Bot 语音消息自动识别 v2.0。自动解码 QQ Silk V3 格式，Whisper medium 模型识别，Gateway 集成，用户确认流程。

QQ Bot 语音转文字 Skill

自动识别 QQ Bot 收到的语音消息，将 Silk V3 编码的 .amr 文件转换为文字。

快速开始

1. 安装依赖

bash

# 克隆 silk-v3-decoder
git clone --depth 1 https://github.com/kn007/silk-v3-decoder.git /tmp/silk-v3-decoder

# 安装 Whisper（语音识别）
pip3 install openai-whisper

# 安装 ffmpeg（音频处理）
apt install ffmpeg  # Ubuntu/Debian
# 或
yum install ffmpeg  # CentOS/RHEL

2. 使用脚本处理语音

bash

# 单个文件处理
python3 scripts/process_qq_voice.py /path/to/voice.amr

# 输出：
# ✅ MP3: /path/to/voice.amr.mp3
# 📝 文字：好的 这次解决 QQ 语音识别的问题

3. 集成到 QQ Bot

修改 gateway.ts，在附件处理逻辑中添加：

typescript

} else if (localPath.endsWith(".amr")) {
  const { exec } = await import("node:child_process");
  
  try {
    // 1. 去掉第一个字节 (0x02)
    const data = fs.readFileSync(localPath);
    const fixedPath = localPath + ".fixed";
    fs.writeFileSync(fixedPath, data.slice(1));
    
    // 2. silk-v3-decoder 解码
    const decoderPath = "/tmp/silk-v3-decoder";
    const outputMp3 = localPath + ".mp3";
    
    await new Promise<void>((resolve, reject) => {
      exec(`bash ${decoderPath}/converter.sh ${fixedPath} mp3`, (err) => {
        if (err) reject(err);
        else resolve();
      });
    });
    
    // 3. Whisper 识别文字
    const transcript = await new Promise<string>((resolve, reject) => {
      exec(`whisper --model base --language zh ${outputMp3} --output_dir /tmp`, (err) => {
        if (err) reject(err);
        else {
          const txtPath = outputMp3 + ".txt";
          fs.readFile(txtPath, 'utf-8', (err, data) => {
            if (err) reject(err);
            else resolve(data.trim());
          });
        }
      });
    });
    
    // 4. 添加到消息内容
    if (transcript) {
      audioTranscripts.push(`\n🎤 **语音消息**：${transcript}\n`);
    }
    
    // 5. 清理
    fs.unlinkSync(fixedPath);
    
  } catch (err: any) {
    log?.error(`[qqbot] 语音处理失败：${err.message}`);
  }
}

工作原理

text

QQ 语音文件 (.amr)
    ↓
去掉 0x02 字节头
    ↓
silk-v3-decoder 解码 → MP3
    ↓
Whisper 识别 → 文字
    ↓
添加到 QQ Bot 消息

为什么需要去掉 0x02 字节？

QQ 语音文件结构：

text

┌────────┬─────────────┬──────────┬──────────┐
│ 0x02   │ #!SILK_V3   │ 参数 (3B) │ 音频数据 │
│ 1 字节  │ 9 字节       │ 3 字节    │ 变长      │
└────────┴─────────────┴──────────┴──────────┘

QQ 在标准 Silk V3 格式前添加了 0x02 字节标记，去掉后才是标准格式。

配置选项

环境变量

bash

# Whisper 模型 (tiny/base/small/medium/large)
export WHISPER_MODEL=base

# 语言 (zh/en/ja 等)
export WHISPER_LANGUAGE=zh

# silk-v3-decoder 路径
export SILK_DECODER_PATH=/tmp/silk-v3-decoder

脚本参数

bash

# 指定输出目录
python3 scripts/process_qq_voice.py voice.amr --output /tmp/voice

# 指定模型
python3 scripts/process_qq_voice.py voice.amr --model small

# 批量处理
python3 scripts/process_qq_voice.py --batch /path/to/voices/

性能参考

语音时长	处理时间	备注
10 秒	10-15 秒	base 模型
30 秒	20-30 秒	base 模型
60 秒	40-60 秒	base 模型

首次运行需要编译 silk-v3-decoder，额外 +30 秒。

常见问题

Q: 报错 "Not a valid silk_data"

A: 文件头未正确处理，确保去掉了第一个字节（0x02）

Q: 报错 "ffmpeg not found"

A: 安装 ffmpeg：apt install ffmpeg

Q: 识别速度慢

A: 使用更小的 Whisper 模型：--model tiny

Q: 识别不准确

A: 使用更大的 Whisper 模型：--model small 或 medium

文件结构

text

qqbot-voice-transcribe/
├── SKILL.md              # 本文件
├── scripts/
│   ├── process_qq_voice.py    # 主处理脚本
│   └── batch_process.py       # 批量处理脚本
├── examples/
│   └── gateway-integration.ts # QQ Bot 集成示例
└── README.md             # 详细文档

测试

bash

# 运行测试
python3 scripts/process_qq_voice.py --test

# 测试文件头
xxd voice.amr | head -1
# 应该看到：02 23 21 53 49 4c 4b 5f 56 33  (.#!SILK_V3...)

相关资源

• silk-v3-decoder - Silk V3 解码器
• Whisper - OpenAI 语音识别
• OpenClaw QQ Bot - QQ Bot 插件

更新日志

v2.0.0 (2026-03-01) - Gateway 自动识别集成 🎉

新增功能：

• ✅ Gateway 自动识别 - 集成到 gateway.ts，自动判断并识别语音消息
• ✅ 用户确认流程 - 识别后显示结果，请用户确认再执行
• ✅ txt 路径修复 - 检查多个可能的路径，解决识别结果为空问题
• ✅ medium 模型支持 - 默认使用 medium 模型，准确率 ~95%+
• ✅ 系统优化 - 添加 swap 配置，防止 OOM 崩溃

修复问题：

• ✅ OOM 崩溃（添加 4GB swap）
• ✅ 识别结果为空（txt 路径修复）
• ✅ 提示语错误（纯语音消息处理）
• ✅ 硬盘空间不足（清理 7GB）

性能提升：

typescript

// 自动判断附件类型
const ext = path.extname(localPath).toLowerCase();
const mimeType = att.content_type?.toLowerCase() || '';

if (ext === '.amr' || mimeType.includes('amr')) {
  // 自动识别流程
}

识别效果：

text

🎤 **语音消息识别结果**：今天天气如何

_请确认是否正确，我将按此执行_

v1.0.0 (2026-02-28)

• ✅ 初始版本
• ✅ 支持 QQ Silk V3 格式解码
• ✅ Whisper 中文识别
• ✅ QQ Bot 集成示例
• ✅ 批量处理支持

---

作者： 卡妹 (CyberKamei) 🌸
许可： MIT
问题反馈： https://github.com/openclaw/skills/issues
社区讨论： https://moltbook.forum