JMusicBot

Note

This is a fork of JMusicBot from jagrosh I started this because it was not maintained and was not working anymore.

A cross-platform Discord music bot with a clean interface, and that is easy to set up and run yourself!

⚠️ Important Notice (Java 25)

• Java 25 Minimum: The bot now requires Java 25 or higher. Please update your hosting environment (check java -version) before running the new JAR.
• Privileged Gateway Intents: You must enable the Message Content Intent in your Discord Developer Portal.
  • Navigate to: Your Application > Bot > Privileged Gateway Intents > Toggle "Message Content Intent" to ON.
  • Without this, the bot will not see your commands.

Features

• Easy to run (just make sure Java is installed, and run!)
• Fast loading of songs
• No external keys needed (besides a Discord Bot token)
• Smooth playback
• Server-specific setup for the "DJ" role that can moderate the music
• Clean and beautiful menus
• Supports many sites, including Youtube, Soundcloud, and more
• Supports many online radio/streams
• Supports local files
• Playlist support (both web/youtube, and local)

Supported sources and formats

JMusicBot supports all sources and formats supported by lavaplayer:

Sources

• YouTube
• SoundCloud
• Bandcamp
• Vimeo
• Twitch streams
• Local files
• HTTP URLs

Formats

• MP3
• FLAC
• WAV
• Matroska/WebM (AAC, Opus or Vorbis codecs)
• MP4/M4A (AAC codec)
• OGG streams (Opus, Vorbis and FLAC codecs)
• AAC streams
• Stream playlists (M3U and PLS)

Example

Setup

Please see the Setup Page to run this bot yourself!

Docker

JMusicBot can be run using Docker for easy deployment and management. Pre-built images are available from the GitHub Container Registry. The container is configured to run headless and automatically generate a default config.txt on first run.

Quick Start

For Existing Users (Migrating from JAR)

If you already have a directory with your config.txt, Playlists/ folder, and other bot files, either provide the path to that directory or run the container from within it:

docker run --rm -it \
  --name jmusicbot \
  -v "$(pwd):/musicbot" \
  ghcr.io/arif-banai/musicbot:latest

This mounts your current directory as the musicbot volume, so the bot will use your existing configuration and playlists.

For New Users

1. Create a directory for your bot and run the container:

   mkdir -p /path/to/jmusicbot
   
   docker run --rm -it \
     --name jmusicbot \
     -v "/path/to/musicbot:/musicbot" \
     ghcr.io/arif-banai/musicbot:latest

2. First Run:

   • On first run, if the mounted directory is empty, the bot will automatically generate a default config.txt file.
   • Edit /path/to/musicbot/config.txt on your host and add your Discord bot token.
   • Run the container again.

Using Docker Compose (Optional)

If you prefer docker-compose, copy the example compose file and update the volume path:

cp docker-compose.example.yml docker-compose.yml
# Edit docker-compose.yml and update the volume path
docker-compose up -d

Example docker-compose.yml:

services:
  jmusicbot:
    image: ghcr.io/arif-banai/musicbot:latest
    container_name: jmusicbot
    volumes:
      - /path/to/musicbot:/musicbot
    restart: unless-stopped

Check the Docker Compose Example for more details.

Important Notes

• Config Persistence: The /musicbot volume must be mounted for your configuration to persist. The bot reads and writes config.txt from /musicbot (the container's working directory).
• First Run: If config.txt doesn't exist, the bot will generate a default one automatically. You'll need to edit it with your bot token before the bot can start.
• Image Tags:
  • Use ghcr.io/arif-banai/musicbot:latest for the latest build from the default branch
  • Use ghcr.io/arif-banai/musicbot:0.6.1 (replace with actual version) to pin a specific release version
  • Recommendation: For production, pin your image tag rather than using latest
• JAVA_OPTS: You can optionally set JAVA_OPTS environment variable to pass additional JVM arguments (e.g., -Xmx512m -Xms256m for memory settings).

To view published images, visit: https://github.com/arif-banai/MusicBot/pkgs/container/musicbot

Development Workflow

This project follows a trunk-based development workflow. The master branch is always releasable, and all work happens in short-lived branches:

• feature/<slug> - New features (e.g., feature/new-player-ui)
• fix/<slug> - Bug fixes (e.g., fix/youtube-oauth)
• chore/<slug> - Maintenance tasks (e.g., chore/update-deps)
• deps/<slug> - Dependency experiments (e.g., deps/youtube-source-pr195)
• release/<version> - Release stabilization (optional, e.g., release/0.6.3)

Branch names are automatically validated by CI to ensure consistency. For detailed information about the development workflow, branch naming rules, and best practices, see DEVELOPMENT_WORKFLOW.md.

Questions/Suggestions/Bug Reports

Please read the Issues List before suggesting a feature. If you have a question, need troubleshooting help, or want to brainstorm a new feature, please start a Discussion. If you'd like to suggest a feature or report a reproducible bug, please open an Issue on this repository. If you like this bot, be sure to add a star to the libraries that make this possible: JDA and lavaplayer!

Editing

This bot (and the source code here) might not be easy to edit for inexperienced programmers. The main purpose of having the source public is to show the capabilities of the libraries, to allow others to understand how the bot works, and to allow those knowledgeable about java, JDA, and Discord bot development to contribute. There are many requirements and dependencies required to edit and compile it, and there will not be support provided for people looking to make changes on their own. Instead, consider making a feature request (see the above section). If you choose to make edits, please do so in accordance with the Apache 2.0 License.