Play isolated music in Simple Voice Chat groups with YouTube, Spotify & SoundCloud support.
GroupMusic
Discord-like music bot for Simple Voice Chat groups on Paper servers.
Developed by muhfajrigg (@muhfajrigg).
(Baca dokumentasi dalam Bahasa Indonesia)
๐ Overview
GroupMusic provides isolated, high-fidelity music playback inside Minecraft server voice groups. Players create or join a group in Simple Voice Chat (press V) and can queue, play, loop, and control music that is heard only by members of that group.
Each group has an independent queue and audio stream. Audio is streamed via YouTube with seamless SoundCloud fallback, and metadata can be resolved from Spotify, Apple Music, Deezer, and more.
๐ Why GroupMusic?
While other voice chat music plugins exist, most rely on outdated players that easily break when YouTube updates its anti-bot ciphers or require complicated API keys. GroupMusic was engineered from the ground up to solve these pain points:
| Feature | Standard SVC Music Plugins | GroupMusic |
|---|---|---|
| YouTube Cipher & SABR Blocks | โ Frequently breaks with 403 Forbidden | โ Remote cipher decoder + automatic SoundCloud fallback |
| YouTube URL Search | โ ๏ธ Requires awkward ytsearch: prefixes | โ Paste any direct link or title naturally |
| Spotify Playlists & Albums | โ Requires Spotify Developer tokens / API setup | โ Built-in public embed scraper (Zero setup required) |
| Discovery / Search | โ ๏ธ Keyword-only exact match | โ Optional AI Assistant for mood & typo recovery |
| Network Security | โ Vulnerable to local network SSRF probes | โ Built-in SSRF protection blocking private IPs |
| Thread Safety & TPS | โ ๏ธ Can cause main-thread stuttering | โ 100% Asynchronous Netty worker audio pipeline |
โจ Features
- โก๏ธ Asynchronous & Zero-Lag Architecture: The entire track search pipeline, YouTube cipher resolution, Spotify embed scraping, and audio streaming execute 100% asynchronously off the main server thread. Audio frames are delivered directly to Simple Voice Chat via dedicated worker threads, ensuring server TPS remains rock-solid at 20.0.
- ๐ง Per-Group Isolation: Each voice chat group operates its own music session and queue without overlapping with other groups.
- ๐ Loop Modes: Supports single track loop, full queue loop, and shuffle.
- ๐ Smart Link Resolution:
- Direct playback: YouTube, SoundCloud, Bandcamp.
- Web metadata lookup: Spotify, Apple Music, Deezer, TIDAL, Amazon Music, Genius, Shazam.
- Spotify album & playlist support via official API or public embed parsing (no Spotify API/Premium required).
- ๐ก๏ธ Built-in Resilience & Fallback:
- If a YouTube video fails to play (e.g. login or SABR cipher restrictions), GroupMusic automatically cleans the title and finds a replacement on SoundCloud.
- SSRF protection rejecting non-public IPs, limiting payload sizes, and validating redirects.
- ๐ In-Game YouTube OAuth Login (
/musiclogin):- Captures Google verification codes directly from logs to show clickable login links and copyable codes in player chat and on-screen titles.
- Refresh token automatically saved to
youtube.ymlwithout needing server restart.
- ๐ค AI-Assisted Search & Suggestions (Optional):
- Use
/music search <vibe or description>(e.g./music search relaxing lofi study beats). - Automatic typo and lyric-snippet correction.
- Compatible with OpenAI, Groq, OpenRouter, Google Gemini, Ollama, and Anthropic Claude.
- Use
- ๐ Interactive Bossbar & Volume Control:
- Real-time animated bossbar showing track progress and status.
- Integrated with Simple Voice Chat's volume settings: players can customize music volume in the client menu (
press V).
- ๐ฑ Bedrock / Geyser Aware: Detects Floodgate players and gives clear instructions for browser-based voice bridges.
๐ Requirements
- Java 21 or newer
- Paper 1.20.6 / 1.21+ (or modern Paper forks)
- Simple Voice Chat 2.6.0+ on server & clients
๐ฆ Building from Source
git clone https://github.com/muhfajrigg/GroupMusic.git
cd GroupMusic
mvn clean package
The compiled JAR will be in target/GroupMusic-1.0.0.jar. Place it into your server's plugins/ directory.
๐ Usage & Quick Command Cheatsheet
GroupMusic can be controlled using the primary commands /music or /lagu (shortcut /l). Below is a quick command reference for everyday use:
| Command | Aliases | Description | Permission |
|---|---|---|---|
/lagu play <judul/url> |
/l p, /music play |
Play or add a song to the voice chat group queue | groupmusic.use |
/lagu pause / /lagu resume |
/l pause, /l resume |
Pause or resume track playback | groupmusic.use |
/lagu skip |
/l s, /music skip |
Skip the currently playing track | groupmusic.use |
/lagu queue |
/l q, /music queue |
View the current group track queue | groupmusic.use |
/lagu volume <0-100> |
/l vol, /music volume |
Adjust the group audio volume | groupmusic.use |
/lagu loop [off/track/queue] |
/l lp, /music loop |
Configure track loop mode | groupmusic.use |
/lagu search <deskripsi> |
/l cari, /music search |
Smart AI-powered song search (optional) | groupmusic.use |
/lagu stop |
/l stop, /music stop |
Stop playback and clear the queue | groupmusic.use |
/lagu help |
/l h, /music help |
View interactive command guide | groupmusic.use |
/lagureload |
/musicreload |
Reload configuration files without server restart | groupmusic.admin |
๐ฎ All Commands & Permissions
All standalone commands also support English and Indonesian aliases:
| Command | Aliases | Description | Permission |
|---|---|---|---|
/music <title or link> |
/lagu, /play, /gm, /l |
Queue and play a track directly | groupmusic.use |
/musicsearch <description> |
/lagucari, /search |
Search songs using AI mood/vibe | groupmusic.search |
/musicstop |
/lagustop, /mstop |
Stop playback and clear the queue | groupmusic.use |
/musicpause |
/lagupause, /pause |
Pause or resume current track | groupmusic.use |
/musicskip |
/laguskip, /skip |
Skip currently playing track | groupmusic.use |
/musicqueue |
/laguqueue, /queue |
View upcoming tracks in queue | groupmusic.use |
/musicnow |
/lagunow, /np |
Display current track info | groupmusic.use |
/musicloop [track|queue|off] |
/lagulagi, /loop |
Set or toggle loop mode | groupmusic.use |
/musicshuffle |
/lagushuffle, /shuffle |
Shuffle tracks in queue | groupmusic.use |
/musicvolume [0-100] |
/laguvolume, /volume |
View or adjust group volume | groupmusic.use |
/musicbar |
/lagubar, /mbar |
Toggle bossbar visibility | groupmusic.use |
/musiclogin |
/lagulogin |
Authorize YouTube Google account | groupmusic.admin |
/musicreload |
/lagureload |
Reload configs and language files | groupmusic.admin |
Permissions
groupmusic.use: Allows using basic music commands (default: all players).groupmusic.search: Allows using AI-assisted search (default: all players).groupmusic.ai.bypass-cooldown: Bypasses cooldown on AI search (default: OP).groupmusic.admin: Administrative access for login and reload (default: OP).
โ๏ธ Configuration
Configuration files are located in plugins/GroupMusic/:
| File | Description | Reloadable via /musicreload |
|---|---|---|
config.yml |
Queue limits, track duration, idle timeout, bossbar, language (locale) |
Yes |
messages.yml |
Player-facing messages in English (MiniMessage format) | Yes |
messages_id.yml |
Player-facing messages in Indonesian | Yes |
sources.yml |
Allowed domains, Spotify API credentials, and search providers | Yes (Spotify keys: restart) |
youtube.yml |
YouTube client order, remote cipher URL, and OAuth tokens | Requires restart |
ai.yml |
AI API provider, model, keys, prompts, and rate limits | Yes |
To switch language to Indonesian, set locale: id in config.yml and run /musicreload.
๐ YouTube Authentication (Recommended One-Time Setup)
Due to YouTube's strict anti-bot measures, playing official music videos or age-restricted tracks may require authentication. GroupMusic features a built-in OAuth login command directly in-game:
- Type
/musiclogin(or/lagulogin) in console or in-game (requiresgroupmusic.admin). - Open the displayed Google authentication link and enter the provided pairing code.
- Log in using a spare / burner Google account (recommended best practice to protect your personal account).
- Once verified, session tokens are securely saved in
youtube.yml. You only need to do this once!
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
Copyright (c) 2026 muhfajrigg (@muhfajrigg).
Information
Pinned Versions
- R1.20โ26.2
Pages
Members
1
Owner