Skip to content

README.md

Latest commit

 

History

History
251 lines (186 loc) · 7.54 KB

README.md

File metadata and controls

251 lines (186 loc) · 7.54 KB

DisMu

Bot Logo

A powerful Discord Music Bot with comprehensive audio playback capabilities

Python License Docker

Features • Installation • Configuration • Contributing

📋 Table of Contents

✨ 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)

🔧 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

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

Made with ❤️ for the Discord community

⭐ Star this repo • 🐛 Report Issues • 💬 Discussions