🎵 Soundy

A powerful, self-hostable Discord music bot built with TypeScript

---

✨ Features

• 🎶 High-quality music playback via Lavalink (Shoukaku)
• 📻 Radio mode — stream live Lofi & ambient radios
• 🎯 Blindtest — musical quiz game built-in
• 🗣️ Multi-language — French & English (i18n ready)
• 🎙️ Custom Voice Channels — let users manage their own VC
• 🛡️ DJ Role system — restrict music controls per server
• 💾 MySQL persistence — settings saved per server
• 🎚️ Vote skip with configurable threshold
• 🔁 Loop modes — track / queue / off

---

📋 Commands

🎵 Music

Command	Description
/play <query>	Play a song or YouTube/Spotify URL
/pause	Pause the current track
/resume	Resume playback
/skip	Vote to skip the current track
/force-skip	Force skip (DJ only)
/skip-to <position>	Jump to a track in the queue
/force-skip-to <position>	Force jump (DJ only)
/stop	Stop playback and clear the queue
/loop	Enable loop (track or queue)
/unloop	Disable loop
/shuffle	Shuffle the queue
/get-queue	Display the current queue
/now-playing	Show the currently playing track
/playlist	Manage saved playlists

🛡️ Admin

Command	Description
/set-dj-role <role>	Set the DJ role for the server
/set-volume <1-150>	Set the default volume
/set-skip-percentage <1-100>	Configure the vote skip threshold
/set-custom-voice-channel	Enable custom voice channels
/change-language <lang>	Switch bot language (fr / en-US)
/radio play <station>	Start a live radio stream
/radio stop	Stop the radio

🎯 Blindtest

Command	Description
/blindtest create	Create a new blindtest playlist
/blindtest start	Start a blindtest game
/blindtest stop	Stop the current game
/blindtest pause	Pause the game
/blindtest resume	Resume the game
/blindtest answer	Submit an answer
/blindtest list	List available blindtest playlists
/blindtest delete	Delete a blindtest playlist

💬 General

Command	Description
/help	Show the help menu
/suggestion	Send a suggestion to the developers
/vote	Vote for the bot
/support-server	Get the support server link

🎙️ Custom Voice Channels

When a user joins the designated "Join to Create" channel, a personal voice channel is created. It comes with a full control panel:

• Lock / Unlock the channel
• Ghost / Unghost (make private or visible)
• Limit users (set a user cap)
• Rename the channel
• Permit / Reject specific users or roles

---

🚀 Self-Hosting

Prerequisites

• Node.js v18+
• Lavalink server running
• A MySQL database
• A Discord application & bot token from the Developer Portal

Installation

1. Clone the repository

git clone https://github.com/your-username/soundy.git
cd soundy

2. Install dependencies

npm install

3. Configure environment variables

cp .env.example .env

Then open .env and fill in your values (see Configuration below).

4. Deploy slash commands

npm run deploy-commands

5. Start the bot

Development:

npm run dev

Production (after build):

npm run build
npm start

---

⚙️ Configuration

Copy .env.example to .env and fill in all required fields:

# Discord
DISCORD_TOKEN=your_discord_bot_token
CLIENT_ID=your_discord_application_id

# MySQL Database
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=soundy

# Lavalink
LAVALINK_HOST=localhost:2333
LAVALINK_PASSWORD=youshallnotpass

# Environment
NODE_ENV=development

Note: Make sure your Lavalink server is running and reachable before starting the bot.

---

🏗️ Project Structure

soundy/
├── src/
│   ├── client/          # SoundyClient (Discord.js extension)
│   ├── commands/
│   │   ├── admin/       # Admin-only commands
│   │   ├── blindtest/   # Blindtest game commands
│   │   ├── general/     # General commands
│   │   └── music/       # Music playback commands
│   ├── constants/       # Brand colors, emojis, embed variants
│   ├── database/        # MySQL connection & queries
│   ├── events/          # Discord event handlers
│   ├── handlers/        # Command & event loaders
│   ├── locales/         # i18n files (fr, en-US)
│   ├── menus/           # Select menus (custom VC controls)
│   ├── modals/          # Modal interactions
│   ├── music/           # MusicManager (Shoukaku/Lavalink)
│   ├── services/        # LanguageManager
│   ├── types/           # TypeScript type definitions
│   └── utils/           # Embeds, logger, helpers
├── deploy-commands.ts   # Register slash commands globally
├── refresh-commands.ts  # Reset & re-register all commands
├── .env.example         # Environment variable template
└── tsconfig.json

---

🌍 Internationalization

Soundy supports multiple languages per server. Admins can switch the language with /change-language.

Language	Code
🇫🇷 French	fr
🇺🇸 English	en-US

---

📦 Tech Stack

Technology	Purpose
discord.js v14	Discord API wrapper
Shoukaku v4	Lavalink client
Lavalink	Audio streaming node
mysql2	MySQL client
winston	Logging
TypeScript 5	Type safety
dotenv	Environment config

---

📄 License

This project is licensed under the ISC License.