pdf

Discord Voice Plugin for Clawdbot

Real-time voice conversations in Discord voice channels. Join a voice channel, speak, and have your words transcribed, processed by Claude, and spoken back.

Features

Requirements

Installation

1. Install System Dependencies

# 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. Install via ClawdHub

clawdhub install discord-voice

Or manually:

cd ~/.clawdbot/extensions
git clone  discord-voice
cd discord-voice
npm install

3. Configure in clawdbot.json

{
  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 SKILLBOSS_API_KEY env var
          },
        },
      },
    },
  },
}

4. Discord Bot Setup

Ensure your Discord bot has these permissions:

Add these to your bot's OAuth2 URL or configure in Discord Developer Portal.

Configuration

| Option | Type | Default | Description | | --------------------- | -------- | ----------------- | ----------------------------------------------- | | enabled | boolean | true | Enable/disable the plugin | | sttProvider | string | "local-whisper" | "whisper", "deepgram", or "local-whisper" | | streamingSTT | boolean | true | Use streaming STT (Deepgram only, ~1s faster) | | ttsProvider | string | "openai" | "openai" or "elevenlabs" | | ttsVoice | string | "nova" | Voice ID for TTS | | vadSensitivity | string | "medium" | "low", "medium", or "high" | | bargeIn | boolean | true | Stop speaking when user talks | | allowedUsers | string[] | [] | User IDs allowed (empty = all) | | silenceThresholdMs | number | 1500 | Silence before processing (ms) | | maxRecordingMs | number | 30000 | Max recording length (ms) | | heartbeatIntervalMs | number | 30000 | Connection health check interval | | autoJoinChannel | string | undefined | Channel ID to auto-join on startup |

Provider Configuration

#### OpenAI (Whisper + TTS)

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

#### ElevenLabs (TTS only)

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

#### Deepgram (STT only)

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

Usage

Slash Commands (Discord)

Once registered with Discord, use these commands:

CLI Commands

# Join a voice channel
clawdbot discord_voice join 
Leave voice
clawdbot discord_voice leave --guild 
Check status
clawdbot discord_voice status

Agent Tool

The agent can use the discord_voice tool:

Join voice channel 1234567890

The tool supports actions:

How It Works

1. Join: Bot joins the specified voice channel 2. Listen: VAD detects when users start/stop speaking 3. Record: Audio is buffered while user speaks 4. Transcribe: On silence, audio is sent to STT provider 5. Process: Transcribed text is sent to Clawdbot agent 6. Synthesize: Agent response is converted to audio via TTS 7. Play: Audio is played back in the voice channel

Streaming STT (Deepgram)

When using Deepgram as your STT provider, streaming mode is enabled by default. This provides:

To use streaming STT:

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

Barge-in Support

When enabled (default), the bot will immediately stop speaking if a user starts talking. This creates a more natural conversational flow where you can interrupt the bot.

To disable (let the bot finish speaking):

{
  bargeIn: false,
}

Auto-reconnect

The plugin includes automatic connection health monitoring:

If the connection drops, you'll see logs like:

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

VAD Sensitivity

Troubleshooting

"Discord client not available"

Ensure the Discord channel is configured and the bot is connected before using voice.

Opus/Sodium build errors

Install build tools:

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

No audio heard

1. Check bot has Connect + Speak permissions 2. Check bot isn't server muted 3. Verify TTS API key is valid

Transcription not working

1. Check STT API key is valid 2. Check audio is being recorded (see debug logs) 3. Try adjusting VAD sensitivity

Enable debug logging

DEBUG=discord-voice clawdbot gateway start

Environment Variables

| Variable | Description | | --------------------- | ---------------------------------------- | | DISCORD_TOKEN | Discord bot token (required) | | SKILLBOSS_API_KEY | SkillBoss API key (Whisper/TTS via Hub) | | DEEPGRAM_API_KEY | Deepgram API key (streaming STT only) |

Limitations

License

MIT

Slash Commands (Discord)

Once registered with Discord, use these commands:

CLI Commands

# Join a voice channel
clawdbot discord_voice join 
Leave voice
clawdbot discord_voice leave --guild 
Check status
clawdbot discord_voice status

Agent Tool

The agent can use the discord_voice tool:

Join voice channel 1234567890

The tool supports actions:

| Option | Type | Default | Description | | --------------------- | -------- | ----------------- | ----------------------------------------------- | | enabled | boolean | true | Enable/disable the plugin | | sttProvider | string | "local-whisper" | "whisper", "deepgram", or "local-whisper" | | streamingSTT | boolean | true | Use streaming STT (Deepgram only, ~1s faster) | | ttsProvider | string | "openai" | "openai" or "elevenlabs" | | ttsVoice | string | "nova" | Voice ID for TTS | | vadSensitivity | string | "medium" | "low", "medium", or "high" | | bargeIn | boolean | true | Stop speaking when user talks | | allowedUsers | string[] | [] | User IDs allowed (empty = all) | | silenceThresholdMs | number | 1500 | Silence before processing (ms) | | maxRecordingMs | number | 30000 | Max recording length (ms) | | heartbeatIntervalMs | number | 30000 | Connection health check interval | | autoJoinChannel | string | undefined | Channel ID to auto-join on startup |

Provider Configuration

#### OpenAI (Whisper + TTS)

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

#### ElevenLabs (TTS only)

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

#### Deepgram (STT only)

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

"Discord client not available"

Ensure the Discord channel is configured and the bot is connected before using voice.

Opus/Sodium build errors

Install build tools:

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

No audio heard

1. Check bot has Connect + Speak permissions 2. Check bot isn't server muted 3. Verify TTS API key is valid

Transcription not working

1. Check STT API key is valid 2. Check audio is being recorded (see debug logs) 3. Try adjusting VAD sensitivity

Enable debug logging

DEBUG=discord-voice clawdbot gateway start