Bump version from 0.7.0 to 0.7.1 for the YouTube playback fixes. The version flows from pom.xml into the jar name and the manifest's Implementation-Version, which is what the bot reports at runtime and what the update checker compares against, so no other file needed changing. The Dockerfile and release workflow already reference the jar by wildcard.
339 lines
15 KiB
Markdown
339 lines
15 KiB
Markdown
<img align="right" src="https://i.imgur.com/zrE80HY.png" height="200" width="200">
|
||
|
||
# JMusicBot
|
||
|
||
> [!NOTE]
|
||
> **This is a fork of a fork.** Credit for the bot belongs to the two people below — this
|
||
> repository only fixes YouTube playback.
|
||
>
|
||
> | Author | Repository | Role |
|
||
> | --- | --- | --- |
|
||
> | **[jagrosh](https://github.com/jagrosh)** | [jagrosh/MusicBot](https://github.com/jagrosh/MusicBot) | Original author of JMusicBot |
|
||
> | **[arif-banai](https://github.com/arif-banai)** | [arif-banai/MusicBot](https://github.com/arif-banai/MusicBot) | Revived and maintains it — dependency updates, Java 25, config migration. **Direct parent of this fork.** |
|
||
>
|
||
> arif-banai's note on their own fork: *"This is a fork of JMusicBot from jagrosh. I started this
|
||
> because it was not maintained and was not working anymore."*
|
||
>
|
||
> Licensed under Apache 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
|
||
|
||
## What's different in this fork
|
||
|
||
### 0.7.1
|
||
|
||
YouTube changed how it serves streams, which broke playback for everyone on the upstream
|
||
0.7.0 release. This version fixes that:
|
||
|
||
- **Signature cipher is no longer tied to OAuth.** Deciphering and authentication are unrelated
|
||
concerns, but the cipher was only applied when OAuth was on — so the default install fell back
|
||
to the bundled extractor and died with `Must find sig function from script: /s/player/…`.
|
||
It is now always applied and configurable via `playback.youtube.remoteCipher.url`.
|
||
- **Added the ANDROID client and reordered the client list by reliability.** ANDROID is currently
|
||
the only client YouTube reliably streams to anonymously; WEB now sits last because YouTube
|
||
answers it with SABR-only responses that contain no playable format.
|
||
- **Sign-in failures are now reported usefully.** The existing hint could never fire: it matched
|
||
on the aggregate exception message rather than the per-client reasons, and compared against an
|
||
ASCII apostrophe while YouTube sends `’` (U+2019).
|
||
- **youtube-source pinned past 1.18.2**, which predates the fixes for the TV client User-Agent
|
||
and for formats that omit `contentLength`.
|
||
|
||
Measured on the tracks that were failing: **5/5 playing, stable across repeat runs** (previously
|
||
1/5). No OAuth or Google account required.
|
||
|
||
[](https://github.com/arif-banai/MusicBot/releases/latest)
|
||
[](https://github.com/arif-banai/MusicBot/stargazers)
|
||
[](https://github.com/arif-banai/MusicBot/releases/latest)
|
||
[](https://github.com/arif-banai/MusicBot/blob/master/LICENSE)
|
||
[](https://discord.gg/cyyUxNmmx6) <br>
|
||
[](https://dl.circleci.com/status-badge/redirect/gh/arif-banai/MusicBot/tree/master)
|
||
[](https://github.com/arif-banai/MusicBot/actions/workflows/build-and-test.yml)
|
||
[](https://www.codefactor.io/repository/github/arif-banai/musicbot)
|
||
|
||
A cross-platform Discord music bot with a clean interface, and that is easy to set up and run yourself!
|
||
|
||
## ⚠️ Check your Java Version and other requirements
|
||
|
||
This version of JMusicBot changes/updates various dependencies. To ensure your bot continues to function correctly, please note the following mandatory changes:
|
||
|
||
* **Java 25 Minimum:** The bot now requires **Java 25 or higher**.
|
||
|
||
* **LibDave/udpqueue:** You **must** have **glibc >= 2.38**. *If you are using Docker, this is already handled for you.*
|
||
* **Privileged Gateway Intents:** You **must** enable the **Message Content Intent** in your [Discord Developer Portal](https://discord.com/developers/applications).
|
||
* *Navigate to: Your Application > Bot > Privileged Gateway Intents > Toggle "Message Content Intent" to ON.*
|
||
* *Without this, the bot will not see your commands.*
|
||
|
||
|
||
[](https://jmusicbot.com/setup)
|
||
|
||
## 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](https://github.com/lavalink-devs/lavaplayer#supported-formats):
|
||
### 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](https://jmusicbot.com/setup) to run this bot yourself!
|
||
|
||
## Running Directly (Without Docker)
|
||
|
||
When running JMusicBot directly (not in Docker), make sure to pass these JVM flags:
|
||
|
||
**Linux / macOS / Windows (CMD):**
|
||
```bash
|
||
java -Dfile.encoding=UTF-8 -Dnogui=true --enable-native-access=ALL-UNNAMED -jar JMusicBot-0.6.2-All.jar
|
||
```
|
||
|
||
**Windows (PowerShell):** PowerShell treats `-D` as its own parameter. Quote each JVM option so they are passed to `java` correctly:
|
||
```powershell
|
||
java "-Dfile.encoding=UTF-8" "-Dnogui=true" "--enable-native-access=ALL-UNNAMED" "-jar" ".\JMusicBot-0.6.2-All.jar"
|
||
```
|
||
Alternatively, use the stop-parsing token so the rest of the line is passed literally: `java --% -Dfile.encoding=UTF-8 -Dnogui=true ...`
|
||
|
||
`-Dfile.encoding=UTF-8` ensures non-English characters (Cyrillic, Japanese, etc.) display correctly in Discord. On Windows or older JDKs, omitting it can cause mojibake in slash-command autocomplete and embeds.
|
||
|
||
### Linux System Requirements
|
||
|
||
**Important:** Your system **must have glibc version 2.38 or higher**. Failure to meet this requirement will result in errors when using JDave and udpqueue.
|
||
|
||
> **Note:** Ubuntu 24.04 "Noble" and Debian 13 "Trixie" already include a compatible glibc version out of the box.
|
||
|
||
You can check your glibc version with:
|
||
```bash
|
||
ldd --version
|
||
```
|
||
|
||
On Debian/Ubuntu-based systems, you may also need to install the following native audio library dependencies:
|
||
|
||
```bash
|
||
# Install required native library dependencies
|
||
sudo apt-get update
|
||
sudo apt-get install -y libopus0 libsodium23
|
||
```
|
||
|
||
|
||
If your version is below 2.38, you will need to upgrade your system or use a compatible runtime. (You can also use Docker, which is recommended.)
|
||
|
||
## 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:
|
||
|
||
```bash
|
||
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:**
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```yaml
|
||
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](docker-compose.example.yml) 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 master 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:** The container uses ZGC and AlwaysPreTouch by default. Set `JAVA_OPTS` to add heap limits (e.g. `-Xms256m -Xmx512m`) or other flags. See [Performance Tuning](#performance-tuning) for details.
|
||
|
||
|
||
To view published images, visit: `https://github.com/arif-banai/MusicBot/pkgs/container/musicbot`
|
||
|
||
## Performance Tuning
|
||
|
||
For optimal audio quality with minimal stuttering, the following JVM and configuration options are recommended.
|
||
|
||
### JVM Flags (Recommended)
|
||
|
||
The bot works best with ZGC (Z Garbage Collector) which provides sub-millisecond pause times:
|
||
|
||
```bash
|
||
java -Dfile.encoding=UTF-8 \
|
||
-XX:+UseZGC \
|
||
-XX:+AlwaysPreTouch \
|
||
-Dnogui=true \
|
||
--enable-native-access=ALL-UNNAMED \
|
||
-jar JMusicBot-*.jar
|
||
```
|
||
|
||
**Flag explanations:**
|
||
- `-Dfile.encoding=UTF-8`: Ensures non-English characters display correctly in Discord (required on Windows or older JDKs)
|
||
- `-XX:+UseZGC`: Sub-millisecond GC pauses (generational mode is default in JDK 24+)
|
||
- `-XX:+AlwaysPreTouch`: Pre-allocates memory at startup to avoid page faults
|
||
- `-Xms` / `-Xmx`: Optional; set heap size if you want to limit or fix memory (e.g. `-Xms256m -Xmx512m`)
|
||
|
||
The Docker image uses ZGC and AlwaysPreTouch by default. Set `JAVA_OPTS` to add heap limits or override:
|
||
```yaml
|
||
environment:
|
||
- JAVA_OPTS=-Xms256m -Xmx512m -XX:+UseZGC -XX:+AlwaysPreTouch
|
||
```
|
||
|
||
### Audio Buffer Configuration
|
||
|
||
The bot includes configurable audio buffers that protect against GC pauses. These can be tuned in `config.txt`:
|
||
|
||
```hocon
|
||
performance {
|
||
# NAS buffer duration in ms (protects against JVM pauses up to this duration)
|
||
nasBufferMs = 800
|
||
|
||
# Lavaplayer frame buffer duration in ms (amount of decoded audio to buffer)
|
||
frameBufferMs = 2000
|
||
}
|
||
```
|
||
|
||
Higher values provide more protection against stuttering but add latency. The defaults (800ms NAS, 2000ms frame buffer) should work well for most setups.
|
||
|
||
## Proxy Configuration
|
||
|
||
JMusicBot supports granular proxy configuration, allowing you to route specific components through a proxy while letting others connect directly. This is useful when you need to proxy audio traffic (e.g., to bypass regional restrictions) without affecting Discord API communication.
|
||
|
||
### Configuration
|
||
|
||
Add the following to your `config.txt`:
|
||
|
||
```hocon
|
||
proxy {
|
||
# Proxy server hostname and port
|
||
host = "127.0.0.1"
|
||
port = 8080
|
||
|
||
# Enable proxy for specific components
|
||
lavaplayer = true # Audio source requests (YouTube, SoundCloud, etc.)
|
||
jda = false # Discord API traffic
|
||
github = false # Version check requests
|
||
}
|
||
```
|
||
|
||
### Common Use Cases
|
||
|
||
**Route only audio traffic through proxy** (most common):
|
||
```hocon
|
||
proxy {
|
||
host = "127.0.0.1"
|
||
port = 18080
|
||
lavaplayer = true
|
||
jda = false
|
||
github = false
|
||
}
|
||
```
|
||
|
||
**Route all traffic through proxy**:
|
||
```hocon
|
||
proxy {
|
||
host = "proxy.example.com"
|
||
port = 8080
|
||
lavaplayer = true
|
||
jda = true
|
||
github = true
|
||
}
|
||
```
|
||
|
||
### Notes
|
||
|
||
- Leave `host` empty or `port` as 0 to disable proxy entirely
|
||
- Each component can be independently enabled/disabled
|
||
- HTTP proxies are supported (SOCKS proxies are not currently supported)
|
||
|
||
## 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](docs/DEVELOPMENT_WORKFLOW.md).
|
||
|
||
## Questions/Suggestions/Bug Reports
|
||
**Please read the [Issues List](https://github.com/arif-banai/MusicBot/issues) before suggesting a feature**.
|
||
|
||
If you have a question, need troubleshooting help, or want to brainstorm a new feature, please start a [Discussion](https://github.com/arif-banai/MusicBot/discussions).
|
||
|
||
The Discord server is also available for questions and suggestions. [Click here to join](https://discord.gg/cyyUxNmmx6).
|
||
|
||
If you'd like to suggest a feature or report a reproducible bug, please open an [Issue](https://github.com/arif-banai/MusicBot/issues) on this repository. If you like this bot, be sure to add a star to the libraries that make this possible:
|
||
- [**JDA**](https://github.com/DV8FromTheWorld/JDA)
|
||
- [**lavaplayer**](https://github.com/lavalink-devs/lavaplayer)
|
||
- [**youtube-source**](https://github.com/lavalink-devs/youtube-source)
|
||
|
||
## 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.
|