ddj (Discord DJ) - Setup Guide

🎵 Live Music Control for Discord Sessions

A minimal Discord music bot with real-time web control, manual track selection, tag-based filtering, and smooth crossfading. Perfect for gaming sessions, streams, or any Discord community.

📋 Prerequisites

Required Software

✅ Node.js 20+ - Download from nodejs.org
✅ Python 3.6+ - Required for building native dependencies (sqlite3, sodium)
✅ Discord Bot - Create at discord.com/developers/applications

System Dependencies

✅ FFmpeg - Automatically installed via npm package (no manual setup needed)
✅ yt-dlp - For YouTube audio downloads
✅ Build Tools - build-essential on Linux, or Visual Studio Build Tools on Windows

Installation Commands

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip build-essential

macOS:

# Python usually comes pre-installed
# Install build tools via Xcode Command Line Tools:
xcode-select --install

Windows:

Install Python from python.org
Install Visual Studio Build Tools (see node-gyp requirements)

🚀 Quick Start

1. Clone and Install Dependencies

git clone <your-repo-url>
cd ddj

# Install bot dependencies (includes FFmpeg automatically)
cd bot
npm install

# Install web dependencies
cd ../web
npm install

# Return to project root
cd ..

2. Configure Bot Environment

Copy the example and fill in your details:

cd bot
cp env.example .env

Edit bot/.env:

DISCORD_TOKEN=your_bot_token_here
GUILD_ID=your_server_id_here
VOICE_CHANNEL_ID=your_voice_channel_id_here
MUSIC_DIR=/path/to/your/music/folder
PORT=5140
CROSSFADE_SECS=4
VOLUME=0.35

To get your Discord IDs:

Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode)
Right-click your server → "Copy ID" (for GUILD_ID)
Right-click your voice channel → "Copy ID" (for VOICE_CHANNEL_ID)

Environment Variables:

MUSIC_DIR: Path to your music folder (defaults to ../../music relative to bot directory if not set)
PORT: Web API port (default: 5140)
CROSSFADE_SECS: Crossfade duration in seconds (default: 4)
VOLUME: Default volume 0.0-1.0 (default: 0.35)

3. Add Music and Start Services

First, add some music to your MUSIC_DIR folder, then start the bot:

cd bot
npm start

You should see:

Seeding music database...
✅ Logged in as YourBot#1234
REST API running on: http://localhost:5140/api
Music library: /path/to/your/music/folder

4. Start the Web UI

In a new terminal:

cd web
npm run dev

Open http://localhost:3000 in your browser to access the control panel.

🎮 How to Use

Initial Setup (One-time)

Import Music: Bot automatically scans your MUSIC_DIR on startup
Add Tags: Browse tracks in the web UI and add tags like:
- tavern, combat, peaceful, tense
- mysterious, epic, ambient, dramatic

Live Session Control

The web UI features three main tabs:

🎵 Music Library Tab

Filter by Tags: Click tag buttons to narrow track options
Browse Results: See all matching tracks with metadata and tags
Manual Selection: Click "Play ▶" on any track for instant playback
YouTube Downloads: Paste YouTube URLs to download and add audio tracks
Track Management: Rename tracks, update metadata, or delete tracks

📋 Queue Tab

Queue Management: Add tracks to a playback queue
Reorder Queue: Drag and drop to rearrange track order
Skip Tracks: Skip to next track in queue
Clear Queue: Remove all queued tracks

⚡ Quick Actions Tab

Playback Controls: Play, skip, stop, or force-stop current track
Volume Control: Adjust playback volume (0-100%)
Now Playing: See current track and volume status
Voice Connection: Manually disconnect bot from voice channel

Example Workflow

DM: "You enter a suspicious tavern..."
→ Music Library tab → Filter: "tavern" + "tense"
→ See 5 matching tracks with metadata visible
→ Click "Play" on "Shady_Negotiations.mp3"
→ Smooth 4-second crossfade begins
→ Add "investigation" tag while playing for future sessions
→ Queue next tracks for continuous music flow

🔧 Features

Core Functionality

Manual Control: You choose every track, no random auto-play
Tag-Based Filtering: Build your musical vocabulary over time
Smooth Crossfading: Professional transitions via FFmpeg (configurable duration)
Live Tagging: Add tags during sessions to enhance future discovery
Local-First: Your music, your tags, your control
Real-Time: Instant response to scene changes

Advanced Features

Queue Management: Add, reorder, and manage playback queues
YouTube Integration: Download audio directly from YouTube URLs
Metadata Support: Automatic extraction of title, artist, album from audio files
Custom Naming: Override default track names for better organization
Volume Control: Real-time volume adjustment (0-100%)
Force Stop: Emergency stop for all audio playback
Voice Connection Management: Manual connect/disconnect controls

Technical Features

SQLite Database: Persistent storage for tracks, tags, and metadata
REST API: Full programmatic access to all bot functions
Modern Web UI: Responsive interface built with Next.js + Tailwind CSS
Cross-Platform: Works on Windows, macOS, and Linux
FFmpeg Integration: High-quality audio processing with automatic installation

🛠 Troubleshooting

Bot Issues

Bot won't start:

Check your Discord token is valid and has proper bot permissions
Ensure Python 3.6+ is installed (required for native dependencies)
Verify GUILD_ID and VOICE_CHANNEL_ID are correct (enable Developer Mode in Discord)
Check that build tools are installed for native module compilation

Voice connection fails:

Ensure bot has proper voice channel permissions in your Discord server
Check that the voice channel exists and bot can access it
Try manually disconnecting and reconnecting the bot

Audio playback issues:

Verify FFmpeg is working (automatically installed via npm)
Check audio file formats are supported (.mp3, .flac, .wav, .m4a, .ogg)
Ensure MUSIC_DIR path is correct and accessible

Web UI Issues

Web UI can't connect:

Ensure bot is running on port 5140 (check bot startup logs)
Verify no firewall is blocking localhost connections
Check browser console for network errors

UI not loading:

Ensure Node.js dependencies are installed (npm install in web directory)
Check that port 3000 is available
Try clearing browser cache and cookies

Database Issues

Music not importing:

Check MUSIC_DIR contains valid audio files
Ensure write permissions for database file creation
Try deleting catalog.db and restarting bot to re-import

Tags not saving:

Check database file permissions
Ensure bot has write access to its directory

YouTube Download Issues

Download fails:

Ensure yt-dlp is installed and in system PATH
Check YouTube URL is valid and accessible
Verify write permissions to MUSIC_DIR

📁 Project Structure

ddj/
├── .gitignore              # Git ignore rules
├── README.md               # This file
├── bot/                    # Discord bot backend
│   ├── src/
│   │   ├── index.js        # Main bot entry point & voice connection
│   │   ├── audioEngine.js  # FFmpeg crossfade engine & audio player
│   │   ├── catalog.js      # SQLite database & track management
│   │   └── routes.js       # REST API endpoints
│   ├── catalog.db          # SQLite database (auto-created)
│   ├── env.example         # Environment configuration template
│   ├── package.json        # Bot dependencies
│   └── package-lock.json   # Dependency lock file
└── web/                    # Next.js web interface
    ├── src/
    │   ├── app/
    │   │   ├── layout.tsx  # App layout
    │   │   ├── page.tsx    # Main page
    │   │   └── error.tsx   # Error page
    │   ├── components/
    │   │   ├── LiveDJPanel.tsx      # Main DJ panel
    │   │   ├── MusicCard.tsx        # Individual track component
    │   │   ├── TabbedMusicInterface.tsx # Tabbed interface
    │   │   └── tabs/
    │   │       ├── MusicLibraryTab.tsx  # Music library management
    │   │       ├── QueueTab.tsx         # Queue management
    │   │       └── QuickActionsTab.tsx  # Playback controls
    │   │   └── ui/              # Shadcn/ui components
    │   │       ├── button.tsx
    │   │       ├── card.tsx
    │   │       ├── dialog.tsx
    │   │       ├── dropdown-menu.tsx
    │   │       ├── input.tsx
    │   │       ├── progress.tsx
    │   │       ├── scroll-area.tsx
    │   │       ├── separator.tsx
    │   │       ├── slider.tsx
    │   │       └── badge.tsx
    │   ├── lib/
    │   │   ├── api.ts         # API client utilities
    │   │   └── utils.ts       # Utility functions
    │   └── styles/
    │       └── globals.css    # Global styles
    ├── components.json       # Shadcn/ui configuration
    ├── next.config.js        # Next.js configuration
    ├── package.json          # Web dependencies
    ├── package-lock.json     # Dependency lock file
    ├── postcss.config.js     # PostCSS configuration
    ├── tailwind.config.js    # Tailwind CSS configuration
    └── tsconfig.json         # TypeScript configuration

🚀 Production Deployment

Environment Setup

For production use, you may want to:

Change API_BASE in web UI:

// In web/src/lib/api.ts
const API_BASE = 'https://your-domain.com/api'; // For production

Set up reverse proxy (nginx/apache) to serve both web UI and API from same domain
Configure firewall to allow access to your chosen ports

Use process manager like PM2 for production bot deployment:

npm install -g pm2
cd bot
pm2 start src/index.js --name "ddj-bot"

API Reference

The bot provides a REST API on port 5140 (configurable):

GET /api/health - Health check
GET /api/tracks - List tracks with optional tag filtering
POST /api/play - Play specific track by ID
POST /api/next - Skip to next track
POST /api/stop / POST /api/force-stop - Stop playback
POST /api/volume - Set volume (0.0-1.0)
POST /api/tag/:id - Add tag to track
DELETE /api/tag/:id - Remove tag from track
DELETE /api/track/:id - Delete track
POST /api/youtube/download - Download from YouTube URL
GET/POST /api/queue/* - Queue management endpoints

🎵 Growing Your Musical Vocabulary

Start simple and build over time:

Session 1: tavern, combat, peaceful, tense
Session 5: Add mysterious, epic, dramatic, chase, victory
Session 20: 50+ precise tags for perfect atmospheric control

The system becomes more powerful with every session as your tagging vocabulary expands!

Ready to DJ your next Discord session? 🎵🤖

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
bot		bot
web		web
.gitignore		.gitignore
README.md		README.md

botBehavior/ddj

Folders and files

Latest commit

History

Repository files navigation