DisMu

A powerful Discord Music Bot with comprehensive audio playback capabilities

Features • Installation • Configuration • Contributing

---

📋 Table of Contents

• ✨ Features
• 📋 Prerequisites
• 🚀 Installation
  • 🐳 Docker Installation (Recommended)
  • 🔧 Manual Installation
• ⚙️ Configuration
• 🎯 Usage
• ⚠️ Known Issues
• 🗺️ Roadmap
• 🤝 Contributing
• 👥 Contributors
• 📄 License
• 🙏 Credits

✨ Features

🎶 Core Features

• YouTube Integration: Play music from URLs, playlists, and search results
• Multi-Guild Support: Individual settings and queues per Discord server
• Advanced Queue Management: Add, remove, shuffle, bump, and reorder tracks
• Playlist Support: Import entire YouTube playlists with automatic shuffling
• Interactive Search: Browse and select from YouTube search results
• Paginated Interfaces: Clean, navigable embeds for queues and search results
• Auto-Cleanup: Automatic message deletion to keep channels tidy
• Error Handling: Graceful error management with user-friendly messages

📋 Prerequisites

🐳 Docker Installation (Recommended)

• Docker installed on your system
• Docker Compose (usually included with Docker)

🔧 Manual Installation

• Python: 3.12 or higher
• FFmpeg: Download and install
• Python Dependencies: Choose one option:
  • Use requirements.txt with pip
  • Use pyproject.toml with Poetry
  • Install manually: discord.py(latest), davey 0.1.4+, PyNaCl 1.6.2+, python-dotenv 1.2.2+, yt-dlp (latest)

🚀 Installation

Step 1: Environment Configuration

1. Clone the repository

   git clone https://github.com/giabb/DisMu.git
   cd DisMu

2. Create environment file

   cp .env.sample .env

3. Get your Discord Bot Token

   • Follow this comprehensive guide
   • Ensure your bot has these Discord permissions:
     • ✅ Connect to Voice Channels
     • ✅ Speak in Voice Channels
     • ✅ Send Messages
     • ✅ Embed Links
     • ✅ Read Message History
     • ✅ Manage Messages (for cleanup)

4. Configure your .env file

   # Required
   BOT_TOKEN=your_discord_bot_token_here
   
   # Optional (defaults provided)
   DEFAULT_PREFIX=%
   DEFAULT_DELETE_TIME=15
   EMBED_AUTODELETE=60
   SEARCH_TIMEOUT=60

🐳 Docker Installation (Recommended)

Quick Start:

docker compose up --build -d

Reference for other docker compose commands:

docker compose logs -f  # View logs in real time
docker compose down     # Stop and remove the container
docker compose stop     # Stop the container
docker compose restart  # Restart the container (if stopped)

🔧 Manual Installation

1. Install Python dependencies

   Using pip:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

   Using Poetry:

   poetry config virtualenvs.in-project true # This will create the .venv folder inside the project
   poetry install --no-root
   source .venv/bin/activate

2. Run the bot

   python -m src.main

⚙️ Configuration

Environment Variables

Variable	Default	Description
BOT_TOKEN	Required	Your Discord bot token
DEFAULT_PREFIX	%	Command prefix for the bot
DEFAULT_DELETE_TIME	15	Seconds before auto-deleting messages
EMBED_AUTODELETE	60	Seconds before auto-deleting embeds
SEARCH_TIMEOUT	60	Seconds to wait for user search selection

🎯 Usage

Once the bot is running and invited to your server:

1. Test the bot: Type %help (or your configured prefix)
2. Join a voice channel and use %join to connect the bot
3. Play music: %play <YouTube URL> or %search <song name>
4. Explore commands: Use %help to see all available commands

📚 For detailed command documentation, visit the Wiki

⚠️ Known Issues

Currently, there are no known major issues.

If you encounter any problems:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include logs and steps to reproduce

🗺️ Roadmap

🔄 Upcoming Features

• Enhanced Commands: Additional queue management and playback options
• Playlist Persistence: Save and load custom playlists
• Spotify Integration: Play tracks from Spotify playlists

🤝 Contributing

We love contributions! Here's how you can help:

🐛 Bug Reports

• Use the issue tracker
• Include detailed reproduction steps
• Provide error logs and environment details

🚀 Feature Requests

• Describe the feature and its benefits
• Provide use cases and examples
• Discuss implementation approaches

💻 Code Contributions

1. Fork the repository
2. Create a feature branch
3. Make your changes with proper documentation
4. Commit your changes
5. Push to the branch
6. Open a Pull Request

📝 Documentation

• Improve README or Wiki pages
• Add code comments and docstrings
• Create tutorials and guides

👥 Contributors

Project Creator & Maintainer

Giovanbattista Abbate

---

Want to contribute? See the Contributing section above!

📄 License

This project is licensed under the GNU General Public License v3.0.

This means you can:

• ✅ Use the software for any purpose
• ✅ Study and modify the source code
• ✅ Distribute copies of the software
• ✅ Distribute modified versions

Requirements:

• 📋 Include the original license
• 📋 State changes made to the code
• 📋 Make source code available when distributing

See the LICENSE.md file for complete details.

🙏 Credits

• README Template: Inspired by PurpleBooth

---

Made with ❤️ for the Discord community

⭐ Star this repo • 🐛 Report Issues • 💬 Discussions