---

---

📻 How it works in game

🧱 Each placed head works as its own radio

• Sound comes directly from the radio's block
• The music gets quieter as you walk away and stops completely once you leave its configured range
• Directional audio makes it possible to hear whether the radio is on your left or right
• Each radio remembers its selected track, playback state, queue, range and shared volume

🎼 Use your own music files

Drop OGG, MP3, WAV, FLAC, M4A, AAC, OPUS, WMA or AIFF files into the tracks folder and run /radio zip. The plugin will scan the files, read their metadata, convert non-OGG tracks when needed and build the Minecraft resource pack with all required sound definitions.

• OGG Vorbis files can be used directly, so FFmpeg is not required if your library only contains OGG files.
• Other formats are converted automatically and the correct FFmpeg build is downloaded only when it is actually needed.
• When rebuilding the pack, already converted tracks are reused as long as the original files have not changed.
• The finished ZIP can be hosted using the plugin's built-in HTTP server or your own direct URL.

🖥️ Vanilla and modded players can play together

For improved playback, players can optionally install Proximity Radio Client, a separate Fabric mod installed directly on their Minecraft client. It is not included with the server plugin and players do not need it to join the server.

📥 Download Proximity Radio Client on Modrinth

The plugin automatically detects Proximity Radio Client, so players with and without the mod can use the same radio. Vanilla players hear the music through the server’s resource pack, while the mod lets players join a song at its current position and use seek, pause and resume controls. Vanilla playback has some limits when joining a song already in progress, depending on the server settings

Vanilla players	Players with the optional client mod
Accept the server resource pack; no mod is required	Install the external Proximity Radio Client from Modrinth
Minecraft plays generated positional sound events	The client plays the extracted OGG track directly
Joining an active song follows WAIT_FOR_SYNC, PLAY_FROM_START or RESTART_TRACK	Join the song at the server's exact current timestamp
Uses Minecraft's native sound attenuation	Supports LINEAR, SMOOTH and NONE falloff curves
Seeking may require the next synchronization point	Seeking, pause and resume are synchronized immediately

If the mod is missing or its protocol does not match the plugin, that player simply stays on the vanilla resource-pack path.

🎛️ Inside the radio menu

• Start, stop, pause, resume, skip or return to the previous track.
• Browse the allowed tracks, select one directly or build a queue.
• Toggle loop and shuffle separately for each radio.
• Change the radio's shared volume and hearing radius.
• Change only your own listener volume without affecting anyone else.
• See the owner, radio ID, active listeners and current playback position.

✨ Around the radio

• A configurable player-head texture makes the radio a physical part of the build.
• The hologram can show the track, time remaining, next track and listener count.
• Note particles can appear directly above the radio or across a larger ambient area.
• The action bar can display the currently playing track only to listeners in range.
• Crafting recipes may use vanilla materials or exact items from supported item plugins.
• Optional protection covers the radio and its supporting block against pistons, explosions and entity changes.

---

🆚 Free vs Pro

Free and Pro use the same playback engine, menus, client integration, protection and hooks. The difference is the size of the library and the number of radio configurations you can create.

Actual difference	🆓 Free	💎 Pro
Radio tier files	2 bundled, editable tiers	Unlimited custom tiers
Track files in the library	Up to 12	No edition limit*
Length of one track	Up to 6 minutes	No edition limit*

💎 Get the PRO here

_{*Practical limits still depend on your server resources and resource-pack size.}

---

🔌 Integrations

🛡️ WorldGuard

Control placement, usage and breaking independently in every region:

proximity-radio-place: allow|deny
proximity-radio-use: allow|deny
proximity-radio-break: allow|deny

🧩 PlaceholderAPI

Display the current track, artist, playback state, listener count, volume, remaining time and more in scoreboards, tab lists or other plugins.

🧱 Custom item plugins

Crafting recipes can use items from ItemsAdder as well as normal Minecraft materials.

All integrations are optional. ProximityRadio works without them.

---

🎮 Useful Commands

Command	Description
/radio help	Display the command help.
/radio volume <0-100>	Set personal radio volume.
/radio mute [on|off]	Mute or unmute all radios for yourself.
/radio streamermode [on|off]	Quickly toggle global personal mute.
/radio info	Show information about the nearest radio.
/radio status	Check client, mute and nearby playback status.
/radio track list [page]	Browse tracks available to the nearby radio.
/radio track play <id>	Select a track when you can control the radio.
/radio queue <list|add|clear>	Manage the nearby radio's queue.
/radio trust <radio-id> <list|add|remove>	Manage trusted players for an owned radio.
/radio zip	Build or rebuild the music resource pack.
/radio reload	Reload configuration, tiers and integrations.
/radio give <player> <tier> [amount]	Give radio items to a player.
/radio diagnose	Display environment and configuration diagnostics.

Command access can be managed with granular permission nodes

---

✅ Requirements

Component	Requirement
Server software	Paper 1.21.7+
Java	Java 21
Optional plugins	WorldGuard, PlaceholderAPI

---