Discord Voice

# Discord Voice Plugin for Clawdbot

在 Discord 语音频道中进行实时语音对话。加入语音频道，说话，您的语音将被转录，由 Claude 处理，然后朗读回放。

## 功能

- **加入/离开语音频道**：通过斜杠命令、CLI 或代理工具 - **语音活动检测 (VAD)**：自动检测用户何时在说话 - **语音转文字 (STT)**：Whisper API (OpenAI)、Deepgram 或 Local Whisper (离线) - **流式 STT**：使用 Deepgram WebSocket 进行实时转录（延迟减少约 1 秒） - **代理集成**：转录的语音通过 Clawdbot 代理路由 - **文字转语音 (TTS)**：OpenAI TTS、ElevenLabs 或 Kokoro (本地/离线) - **音频播放**：响应在语音频道中朗读回放 - **插话支持**：当用户开始说话时立即停止朗读 - **自动重连**：自动心跳监控和断线重连

## 系统要求

- 具有语音权限的 Discord 机器人（连接、说话、使用语音活动） - STT 和 TTS 提供商的 API 密钥 - 语音相关的系统依赖： - `ffmpeg`（音频处理） - `@discordjs/opus` 和 `sodium-native` 的原生构建工具

## 安装

### 1. 安装系统依赖

```bash # Ubuntu/Debian sudo apt-get install ffmpeg build-essential python3

# Fedora/RHEL sudo dnf install ffmpeg gcc-c++ make python3

# macOS brew install ffmpeg ```

### 2. 通过 ClawdHub 安装

```bash clawdhub install discord-voice ```

或手动安装：

```bash cd ~/.clawdbot/extensions git clone <repository-url> discord-voice cd discord-voice npm install ```

### 3. 在 clawdbot.json 中配置

```json5 { plugins: { entries: { "discord-voice": { enabled: true, config: { sttProvider: "local-whisper", ttsProvider: "openai", ttsVoice: "nova", vadSensitivity: "medium", allowedUsers: [], // Empty = allow all users silenceThresholdMs: 1500, maxRecordingMs: 30000, openai: { apiKey: "sk-...", // Or use OPENAI_API_KEY env var }, }, }, }, }, } ```

### 4. Discord 机器人设置

确保您的 Discord 机器人拥有以下权限：

- **Connect** - 加入语音频道 - **Speak** - 播放音频 - **Use Voice Activity** - 检测用户何时说话

将这些添加到您机器人的 OAuth2 URL 或在 Discord 开发者门户中配置。

## 配置

| 选项 | 类型 | 默认值 | 描述 | | -------------------- | -------- | ------------------ | ------------------------------------------------- | | `enabled` | boolean | `true` | 启用/禁用该插件 | | `sttProvider` | string | `"local-whisper"` | `"whisper"`、`"deepgram"` 或 `"local-whisper"` | | `streamingSTT` | boolean | `true` | 使用流式 STT（仅限 Deepgram，快约 1 秒） | | `ttsProvider` | string | `"openai"` | `"openai"` 或 `"elevenlabs"` | | `ttsVoice` | string | `"nova"` | TTS 的语音 ID | | `vadSensitivity` | string | `"medium"` | `"low"`、`"medium"` 或 `"high"` | | `bargeIn` | boolean | `true` | 当用户说话时停止朗读 | | `allowedUsers` | string[] | `[]` | 允许的用户 ID（留空则允许所有） | | `silenceThresholdMs` | number | `1500` | 处理前的静音时间（毫秒） | | `maxRecordingMs` | number | `30000` | 最大录制时长（毫秒） | | `heartbeatIntervalMs`| number | `30000` | 连接健康检查间隔 | | `autoJoinChannel` | string | `undefined` | 启动时自动加入的频道 ID |

### 提供商配置

#### OpenAI (Whisper + TTS)

```json5 { openai: { apiKey: "sk-...", whisperModel: "whisper-1", ttsModel: "tts-1", }, } ```

#### ElevenLabs (仅 TTS)

```json5 { elevenlabs: { apiKey: "...", voiceId: "21m00Tcm4TlvDq8ikWAM", // Rachel modelId: "eleven_multilingual_v2", }, } ```

#### Deepgram (仅 STT)

```json5 { deepgram: { apiKey: "...", model: "nova-2", }, } ```

## 使用方法

### 斜杠命令 (Discord)

向 Discord 注册后，使用以下命令：

- `/discord_voice join <channel>` - 加入语音频道 - `/discord_voice leave` - 离开当前语音频道 - `/discord_voice status` - 显示语音连接状态

### CLI 命令

```bash # Join a voice channel clawdbot discord_voice join <channelId>

# Leave voice clawdbot discord_voice leave --guild <guildId>

# Check status clawdbot discord_voice status ```

### 代理工具

代理可以使用 `discord_voice` 工具：

``` Join voice channel 1234567890 ```

该工具支持以下操作：

- `join` - 加入语音频道（需要 channelId） - `leave` - 离开语音频道 - `speak` - 在语音频道中朗读文本 - `status` - 获取当前语音状态

## 工作原理

1. **加入**：机器人加入指定的语音频道 2. **监听**：VAD 检测用户何时开始/停止说话 3. **录制**：用户说话时音频被缓冲 4. **转录**：静音时，音频被发送到 STT 提供商 5. **处理**：转录的文本被发送到 Clawdbot 代理 6. **合成**：代理响应通过 TTS 转换为音频 7. **播放**：音频在语音频道中播放回放

## 流式 STT (Deepgram)

当使用 Deepgram 作为 STT 提供商时，默认启用流模式。这提供了：

- **端到端延迟快约 1 秒** - **实时反馈**，带有临时转录结果 - **自动保活**，以防止连接超时 - **回退**机制，如果流式传输失败则回退到批量转录

要使用流式 STT：

```json5 { sttProvider: "deepgram", streamingSTT: true, // default deepgram: { apiKey: "...", model: "nova-2", }, } ```

## 插话支持

启用后（默认），如果用户开始说话，机器人将立即停止朗读。这创造了更自然的对话流程，您可以打断机器人。

要禁用（让机器人说完）：

```json5 { bargeIn: false, } ```

## 自动重连

该插件包含自动连接健康监控：

- **心跳检查** 每 30 秒一次（可配置） - **自动重连**，断开连接时采用指数退避策略 - **最多尝试 3 次**，然后放弃

如果连接断开，您将看到如下日志：

``` [discord-voice] Disconnected from voice channel [discord-voice] Reconnection attempt 1/3 [discord-voice] Reconnected successfully ```

## VAD 灵敏度

- **low**：拾取轻声说话，可能会被背景噪音触发 - **medium**：平衡（推荐） - **high**：需要更大声、更清晰的语音

## 故障排除

### "Discord client not available"

确保已配置 Discord 频道，并且在使用语音之前机器人已连接。

### Opus/Sodium 构建错误

安装构建工具：

```bash npm install -g node-gyp npm rebuild @discordjs/opus sodium-native ```

### 听不到音频

1. 检查机器人是否有“连接 + 说话”权限 2. 检查机器人是否未被服务器静音 3. 验证 TTS API 密钥是否有效

### 转录不工作

1. 检查 STT API 密钥是否有效 2. 检查是否正在录制音频（查看调试日志） 3. 尝试调整 VAD 灵敏度

### 启用调试日志

```bash DEBUG=discord-voice clawdbot gateway start ```

## 环境变量

| 变量 | 描述 | | ------------------ | --------------------------------- | | `DISCORD_TOKEN` | Discord 机器人令牌（必需） | | `OPENAI_API_KEY` | OpenAI API 密钥 (Whisper + TTS) | | `ELEVENLABS_API_KEY`| ElevenLabs API 密钥 | | `DEEPGRAM_API_KEY` | Deepgram API 密钥 |

## 限制

- 每个服务器同时只能接入一个语音频道 - 最大录制时长：30 秒（可配置） - 实时音频需要稳定的网络 - 由于合成原因，TTS 输出可能会有轻微延迟

## 许可证

MIT