📻 BoomBox

BoomBox is a production-grade, high-performance Minecraft Paper plugin built by Melo Development for Paper 26.2 and below. It streams 3D positional audio and custom music directly through Simple Voice Chat API without requiring resource packs or client-side sound modifications.

---

 .---------------------------------------------------.
 |   ___   ___   ___  __  __ ___  ___  _  _          | 
 |  | _ ) / _ \ / _ \|  \/  | _ )/ _ \| \/ |         | 
 |  | _ \| (_) | (_) | |\/| | _ \ (_) |  /\          | 
 |  |___/ \___/ \___/|_|  |_|___/\___/_/  \         | 
 |         M E L O   D E V E L O P M E N T S          | 
 |  .---------------------------------------------.  | 
 |  |  (o)  |  [===] ::  B O O M B O X  :: [===] | (o) | 
 |  '---------------------------------------------'  | 
 '---------------------------------------------------' 

---

🌟 Key Features

• 🎙️ Native Simple Voice Chat Integration: Delivers 48kHz mono Opus audio packets directly through Simple Voice Chat's UDP socket.
• 🗿 Custom 3D Jukebox Player Heads & Holograms: Automatically spawns custom Jukebox Player Heads with floating title holograms displaying the active track and assigned owner.
• 🔒 Speaker Ownership Protection: Server admins can assign owners to speakers via /speaker setowner <speaker> <player>. Only assigned owners or server admins can play, stop, or adjust volume on that speaker box.
• 🎵 Local Music Library Playback: Stream .mp3, .wav, or .ogg files placed directly into plugins/BoomBox/music/.
• 🔁 Track Looping: Toggle track looping per speaker using /music loop <speaker> [true|false].
• 🏷️ Hologram Display Toggle: Turn floating text holograms on or off per speaker box via /speaker hologram <speaker> [true|false].
• 🎼 Pure Java MP3 Audio Decoder (JLayer): Zero external system dependencies (FFmpeg binaries not required). Works seamlessly across Windows, Linux, and Pterodactyl Docker containers.
• 📻 Portable Player Radios: Handheld boombox item that streams audio wherever the player walks.
• 🌍 WorldGuard & Region Audio: Bind positional background music or soundscapes to specific WorldGuard regions.
• 🔑 Melo Development License Verification: Secure licensing system connecting to Melo Development's central verification API (http://in-01.upzare.com:3000/verify).

---

📦 Installation Guide

1. Prerequisites:
   • Paper / Purpur server (Paper 26.2 and below).
   • Simple Voice Chat plugin installed and configured.
2. Download BoomBox-1.0.0.jar and place it in your server's plugins/ directory.
3. Place your local music files (.mp3, .wav, .ogg) into plugins/BoomBox/music/.
4. Start the server to generate plugins/BoomBox/config.yml.
5. Open plugins/BoomBox/config.yml and insert your Melo Development License Key:

   license:
     key: "YOUR-LICENSE-KEY"
   

6. Run /boombox reload or restart your server.

---

📜 Commands & Permissions

🎵 Player Music Commands

Command	Permission	Description
/music play <speaker> <track>	boombox.music.use	Play a local track on a speaker box
/music playhere <track>	boombox.music.use	Create a speaker at your feet and play audio
/music stop <speaker>	boombox.music.use	Stop music playback on a speaker
/music volume <speaker> <0.0-2.0>	boombox.music.use	Adjust speaker audio volume
/music loop <speaker> [true/false]	boombox.music.use	Toggle or set track looping
/music list	boombox.music.use	List all available tracks in the music library

🔊 Admin Speaker Commands

Command	Permission	Description
/speaker create <name> [radius]	boombox.admin	Create a new speaker box at your location
/speaker setowner <name> <player>	boombox.admin	Assign a player as the sole owner of a speaker
/speaker hologram <name> [true/false]	boombox.admin	Toggle floating text hologram display
/speaker move <name>	boombox.admin	Move a speaker box to your feet
/speaker delete <name>	boombox.admin	Delete a speaker box
/speaker head [name]	boombox.admin	Receive a custom 3D Jukebox Player Head item
/speaker list	boombox.admin	List all registered speakers, locations, and owners

⚙️ Main Admin Commands

Command	Permission	Description
/boombox reload	boombox.admin	Reload configuration, license, and audio library
/radio give <player>	boombox.radio.use	Give a portable handheld radio item
/regionmusic set <region> <track>	boombox.region.use	Bind music playback to a WorldGuard region

---

⚙️ Configuration (config.yml)

# ====================================================== #
#                  BoomBox Configuration                 #
# ====================================================== #

# Melo Development License Key (Generated via Discord /genlicense)
license:
  key: "YOUR-LICENSE-KEY"

voicechat:
  # Maximum audible distance for positional audio (in blocks)
  distance: 32
  # Global master volume multiplier (0.0 to 2.0)
  volume: 1.0
  # Enable stereo audio encoding
  stereo: true
  # Opus encoding bitrate in bits per second
  opus-bitrate: 64000

music:
  # Scan the /music folder automatically on plugin startup
  scan-on-start: true
  # Maximum simultaneous active audio streams allowed across the server
  max-active-streams: 32

performance:
  # Decode audio files asynchronously off the main Minecraft thread
  async-decode: true
  # Stream tick update rate in Hz
  update-rate: 20

---

📁 Music Folder

Place .mp3, .wav, or .ogg audio files into plugins/BoomBox/music/. They will be scanned automatically on startup or when using /boombox reload.

---

👥 Credits

Developed with ❤️ by Melo Development.

• Supported Versions: Paper 26.2 and below.
• Audio Engine: JLayer & Simple Voice Chat API 2.5+.