🎵 Discord Music Bot

A powerful Discord bot that streams system audio directly to voice channels, perfect for tabletop RPG sessions, music sharing, and collaborative listening experiences.

📖 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📋 Prerequisites
• 🛠️ Installation
  • Linux Setup
  • Windows Setup
  • macOS Setup
• 🤖 Bot Registration
• ⚙️ Configuration
• 📚 Usage
  • Slash Commands
  • Mention Commands
• 🎯 Use Cases
• 🔧 Troubleshooting
• 🤝 Contributing
• 📄 License

✨ Features

• 🎵 System Audio Streaming: Stream any system audio directly to Discord voice channels
• 🎮 Perfect for D&D: Share ambient music, sound effects, and audio during tabletop sessions
• 🌍 Multi-language Support: Commands work in English, Ukrainian, and Russian
• ⚡ Dual Interface: Both slash commands and mention-based natural language commands
• 🔄 Auto-disconnect: Automatically leaves empty voice channels to save resources
• 📊 Status Monitoring: Real-time status and connection information
• 🛡️ Error Handling: Robust error handling with user-friendly messages
• 🎚️ Audio Controls: Start, stop, and manage audio playback easily

🏆 Why Choose This Bot?

Feature	Our Bot	Typical Music Bots
System Audio	✅ Stream any application	❌ Limited to music files/URLs
Real-time Audio	✅ Live system capture	❌ Pre-recorded content only
D&D Integration	✅ Perfect for ambient sounds	⚠️ Limited RPG features
Multi-language	✅ EN/UK/RU support	❌ English only
Local Control	✅ Stream local applications	❌ External sources only
Low Latency	✅ Optimized for real-time	⚠️ Variable delay

🚀 Quick Start

1. Create virtual audio device (see Installation)
2. Register Discord bot (see Bot Registration)
3. Install dependencies: uv sync
4. Set environment: Create .env with your bot token
5. Run: uv run main.py

📋 Prerequisites

• Python 3.9+
• FFmpeg (for audio processing)
• Virtual Audio Cable (OS-specific)
• Discord Bot Token
• uv package manager (recommended) or pip

System Requirements

OS	CPU	RAM	Additional
Linux	Any x64	512MB+	PulseAudio
Windows	Any x64	512MB+	Virtual Audio Cable
macOS	Any x64/ARM	512MB+	Soundflower/BlackHole

🛠️ Installation

Linux Setup

1. Install System Dependencies

# Ubuntu/Debian
sudo apt update
sudo apt install ffmpeg pulseaudio pavucontrol

# Arch Linux
sudo pacman -S ffmpeg pulseaudio pavucontrol

# Fedora
sudo dnf install ffmpeg pulseaudio pavucontrol

2. Create Virtual Audio Sink

# Create the virtual audio sink
pactl load-module module-null-sink sink_name=discord_sink sink_properties=device.description=DiscordSink

# Make it permanent (add to PulseAudio config)
echo "load-module module-null-sink sink_name=discord_sink sink_properties=device.description=DiscordSink" >> ~/.config/pulse/default.pa

3. Configure Audio Routing

PulseAudio Volume Control configuration

1. Open PulseAudio Volume Control: pavucontrol
2. Go to Playback tab
3. Set applications you want to share to output to "DiscordSink"
4. The bot will capture this audio automatically

4. Install Python Dependencies

# Using uv (recommended)
uv venv
source .venv/bin/activate
uv sync

# Using pip
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Windows Setup

1. Install Virtual Audio Cable

VB-Audio Virtual Cable setup

1. Download VB-Audio Virtual Cable
2. Install and restart your computer
3. You'll see "CABLE Input" and "CABLE Output" in your audio devices

2. Install FFmpeg

# Using Chocolatey
choco install ffmpeg

# Or download from https://ffmpeg.org/download.html
# Add to PATH environment variable

3. Configure Audio

1. Control Panel → Sound → Playback
2. Set applications you want to share to output to "CABLE Input"
3. Update bot configuration to use Windows audio source:

# In main.py, update AUDIO_CONFIG
AUDIO_CONFIG = {
    "format": "s16le",
    "channels": 2,
    "sample_rate": 48000,
    "source": "dshow:audio=\"CABLE Output (VB-Audio Virtual Cable)\""
}

4. Install Python Dependencies

# Using uv
uv venv
.venv/Scripts/activate.ps1
uv sync

# Using pip
python -m venv .venv
.venv/Scripts/activate.ps1
pip install -r requirements.txt

macOS Setup

1. Install Virtual Audio Driver

BlackHole audio driver configuration

# Install BlackHole (recommended)
brew install blackhole-2ch

# Alternative: Soundflower (legacy)
brew install soundflower

2. Install FFmpeg

brew install ffmpeg

3. Configure Audio

1. Open Audio MIDI Setup (/Applications/Utilities/)
2. Create Multi-Output Device including BlackHole
3. Set applications to output to this device
4. Update bot source to: "BlackHole 2ch"

4. Install Python Dependencies

# Using uv
uv venv
source .venv/bin/activate
uv sync

# Using pip
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

🤖 Bot Registration

Step 1: Create Discord Application

Discord Developer Portal - New Application

1. Go to Discord Developer Portal
2. Click "New Application"
3. Enter your bot name (e.g., "Audio Streamer Bot")
4. Accept ToS and create

Step 2: Create Bot User

Creating the bot user

1. Go to "Bot" section
2. Copy the Token (keep it secure!)
3. Enable "Message Content Intent"

Step 3: Invite Bot to Server

https://discord.com/oauth2/authorize?client_id=YOUR_BOT_ID&permissions=3148800&scope=bot%20applications.commands

Replace YOUR_BOT_ID with your application ID from the General Information page.

⚙️ Configuration

Environment Variables

Create a .env file in your project root:

# Discord Bot Token (required)
TOKEN=your_discord_bot_token_here

# Optional: Custom audio source
AUDIO_SOURCE=discord_sink.monitor

# Optional: Logging level
LOG_LEVEL=INFO

Advanced Configuration

Edit the AUDIO_CONFIG dictionary in main.py:

AUDIO_CONFIG = {
    "format": "s16le",      # Audio format
    "channels": 2,          # Stereo
    "sample_rate": 48000,   # Discord's preferred rate
    "source": "discord_sink.monitor"  # Your virtual audio device
}

📚 Usage

Slash Commands

Using slash commands

Command	Description
/connect	Connect to your voice channel
/play	Start streaming system audio
/stop	Stop audio playback
/disconnect	Leave voice channel
/status	Show bot status and connection info

Mention Commands

You can also control the bot by mentioning it with natural language:

@MusicBot connect
@MusicBot підійди сюда     (Ukrainian: "come here")
@MusicBot play music
@MusicBot включи музику    (Russian: "turn on music")
@MusicBot disconnect
@MusicBot уйди            (Russian: "go away")

Natural language mention commands

Supported Keywords

Action	English	Ukrainian	Russian
Connect	connect, join, in	сюда, підійди	подключись
Play	music, play, start	гра, музику, грай	включи
Disconnect	disconnect, leave, out, exit, stop	лівні	уйди, отключись

🎯 Use Cases

🎲 Tabletop RPG Sessions

Perfect for D&D ambient audio

• Ambient Music: Stream atmospheric music during gameplay
• Sound Effects: Play combat sounds, environmental audio
• Voice Modulation: Use with voice changers for NPCs
• Background Audio: Tavern sounds, dungeon ambience

Example Workflow:

1. Set your media player to output to virtual cable
2. Join voice channel with players: /connect
3. Start streaming: /play
4. Control music/sounds from your media player
5. Players hear everything in real-time

🎵 Music Sharing

• Local Music Library: Share your personal music collection
• Streaming Services: Share from Spotify, YouTube, etc.
• Live Audio: Stream microphone input, instruments
• Podcast Listening: Listen to podcasts together

🎮 Gaming

• Game Audio: Share game sounds and music
• Commentary: Stream while playing games
• Tutorials: Audio guides and explanations
• Collaboration: Share audio during development

🎤 Presentations & Meetings

• Screen Recording Audio: Share system audio during presentations
• Music Background: Add background music to meetings
• Audio Demos: Demonstrate audio applications
• Training Sessions: Share instructional audio

🔧 Troubleshooting

Common Issues

"No audio playing" / "Silent output"

Symptoms: Bot connects but no audio is heard

Solutions:

1. Check Virtual Cable: Ensure virtual audio device is created

   pactl list sinks | grep discord_sink  # Linux

2. Verify Audio Routing: Applications must output to virtual cable
3. Test FFmpeg: Run FFmpeg command manually

   ffmpeg -f pulse -i discord_sink.monitor -f s16le -ac 2 -ar 48000 test.wav

"Bot won't connect to voice channel"

Symptoms: Connection errors or timeouts

Solutions:

1. Check Permissions: Bot needs Connect and Speak permissions
2. Voice Channel Limit: Ensure channel isn't full
3. Bot Status: Use /status to check connection state

FFmpeg errors

Symptoms: FileNotFoundError or audio processing errors

Solutions:

1. Install FFmpeg: Ensure FFmpeg is in PATH

   ffmpeg -version  # Should show version info

2. Update Audio Source: Check virtual device name
3. Try Alternative Sources:

   # Linux alternatives
   "default"  # Default audio device
   "alsa_output.pci-0000_00_1f.3.analog-stereo.monitor"

High CPU usage

Solutions:

1. Reduce Buffer Size: Lower the bufsize parameter
2. Close Unused Applications: Free up system resources
3. Check Sample Rate: Ensure 48000 Hz (Discord standard)

Debug Mode

Enable debug logging:

# Add to main.py
logging.basicConfig(level=logging.DEBUG)

Getting Help

1. Check Logs: Review console output for errors
2. Test Components: Verify FFmpeg, virtual audio, bot permissions
3. Update Dependencies: Ensure latest versions
4. Community Support: Join our Discord server [link]

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Discord.py - Excellent Discord API wrapper
• FFmpeg - Powerful multimedia framework
• PulseAudio/VB-Cable - Virtual audio solutions
• Community - Thanks to all contributors and users!

---

⭐ Star this repository if you found it helpful!

🐛 Report Bug • ✨ Request Feature

Made with ❤️ for the D&D and music sharing community