whatsappVoiceOpenSkill

# WhatsApp Voice Talk

将 WhatsApp 语音消息转换为实时对话。此技能提供完整的流水线：**语音 → 转录 → 意图检测 → 响应生成 → 文本转语音**。

非常适合： - WhatsApp 上的语音助手 - 免提命令界面 - 多语言聊天机器人 - IoT 语音控制（无人机、智能家居等）

## 快速开始

### 1. 安装依赖

```bash pip install openai-whisper soundfile numpy ```

### 2. 处理语音消息

```javascript const { processVoiceNote } = require('./scripts/voice-processor'); const fs = require('fs');

// Read a voice message (OGG, WAV, MP3, etc.) const buffer = fs.readFileSync('voice-message.ogg');

// Process it const result = await processVoiceNote(buffer);

console.log(result); // { // status: 'success', // response: "Current weather in Delhi is 19°C, haze. Humidity is 56%.", // transcript: "What's the weather today?", // intent: 'weather', // language: 'en', // timestamp: 1769860205186 // } ```

### 3. 运行自动监听器

用于自动处理传入的 WhatsApp 语音消息：

```bash node scripts/voice-listener-daemon.js ```

这会每 5 秒监视一次 `~/.clawdbot/media/inbound/` 并处理新的语音文件。

## 工作原理

``` Incoming Voice Message ↓ Transcribe (Whisper API) ↓ "What's the weather?" ↓ Detect Language & Intent ↓ Match against INTENTS ↓ Execute Handler ↓ Generate Response ↓ Convert to TTS ↓ Send back via WhatsApp ```

## 主要特性

✅ **零设置复杂度** - 无需 FFmpeg，无复杂依赖。使用 soundfile + Whisper。

✅ **多语言** - 自动检测英语/印地语。易于扩展。

✅ **意图驱动** - 使用关键词和处理程序定义自定义意图。

✅ **实时处理** - 每条消息 5-10 秒（首次模型加载后）。

✅ **可定制** - 添加天气、状态、命令或其他任何内容。

✅ **生产就绪** - 基于 Clawdbot 中的真实使用构建。

## 常见用例

### 天气机器人 ```javascript // User says: "What's the weather in Bangalore?" // Response: "Current weather in Delhi is 19°C..."

// (Built-in intent, just enable it) ```

### 智能家居控制 ```javascript // User says: "Turn on the lights" // Handler: Sends signal to smart home API // Response: "Lights turned on" ```

### 任务管理器 ```javascript // User says: "Add milk to shopping list" // Handler: Adds to database // Response: "Added milk to your list" ```

### 状态检查器 ```javascript // User says: "Is the system running?" // Handler: Checks system status // Response: "All systems online" ```

## 自定义

### 添加自定义意图

编辑 `voice-processor.js`：

1. **添加到 INTENTS 映射：** ```javascript const INTENTS = { 'shopping': { keywords: ['shopping', 'list', 'buy', 'खरीद'], handler: 'handleShopping' } }; ```

2. **添加处理程序：** ```javascript const handlers = { async handleShopping(language = 'en') { return { status: 'success', response: language === 'en' ? "What would you like to add to your shopping list?" : "आप अपनी शॉपिंग लिस्ट में क्या जोड़ना चाहते हैं?" }; } }; ```

### 支持更多语言

1. 更新 `detectLanguage()` 以适配您语言的 Unicode： ```javascript const urduChars = /[\u0600-\u06FF]/g; // Add this ```

2. 添加语言代码到返回值： ```javascript return language === 'ur' ? 'Urdu response' : 'English response'; ```

3. 在 `transcribe.py` 中设置语言： ```python result = model.transcribe(data, language="ur") ```

### 更改转录模型

在 `transcribe.py` 中： ```python model = whisper.load_model("tiny") # Fastest, 39MB model = whisper.load_model("base") # Default, 140MB model = whisper.load_model("small") # Better, 466MB model = whisper.load_model("medium") # Good, 1.5GB ```

## 架构

**脚本：** - `transcribe.py` - Whisper 转录 (Python) - `voice-processor.js` - 核心逻辑（意图解析、处理程序） - `voice-listener-daemon.js` - 监听新消息的自动监听器

**参考：** - `SETUP.md` - 安装和配置 - `API.md` - 详细的函数文档

## 与 Clawdbot 集成

如果作为 Clawdbot 技能运行，请挂接到消息事件：

```javascript // In your Clawdbot handler const { processVoiceNote } = require('skills/whatsapp-voice-talk/scripts/voice-processor');

message.on('voice', async (audioBuffer) => { const result = await processVoiceNote(audioBuffer, message.from); // Send response back await message.reply(result.response); // Or send as voice (requires TTS) await sendVoiceMessage(result.response); }); ```

## 性能

- **首次运行：** 约 30 秒（下载 Whisper 模型，约 140MB） - **通常：** 每条消息 5-10 秒 - **内存：** 约 1.5GB（基础模型） - **语言：** 英语、印地语（易于扩展）

## 支持的音频格式

OGG (Opus)、WAV、FLAC、MP3、CAF、AIFF 以及通过 libsndfile 支持的更多格式。

WhatsApp 默认使用 Opus 编码的 OGG —— 开箱即用。

## 故障排除

**"No module named 'whisper'"** ```bash pip install openai-whisper ```

**"No module named 'soundfile'"** ```bash pip install soundfile ```

**语音消息未处理？** 1. 检查：`clawdbot status`（是否正在运行？） 2. 检查：`~/.clawdbot/media/inbound/`（文件是否到达？） 3. 手动运行守护进程：`node scripts/voice-listener-daemon.js`（查看日志）

**转录速度慢？** 使用较小的模型：`whisper.load_model("base")` 或 `"tiny"`

## 延伸阅读

- **设置指南：** 详细安装和配置请参阅 `references/SETUP.md` - **API 参考：** 函数签名和示例请参阅 `references/API.md` - **示例：** 可用代码请查看 `scripts/`

## 许可证

MIT - 自由使用、自定义、回馈贡献！

---

专为 Clawdbot 中的实际使用而构建。经多种语言和用例实战检验。