Diamond DJ is a Fabric mod that broadcasts OGG music files to all connected players. Everyone hears the same song at the same time, creating a shared radio experience for your server. Supports both local OGG files and streaming from YouTube, SoundCloud, Bandcamp, Vimeo, and direct HTTP URLs.

Updating from a previous version? Delete your old config files (config/diamond-dj-server.json and config/diamond-dj-hud.json) and let the mod regenerate them with the latest defaults. New fields are added each update and stale configs can cause unexpected behavior.

First time? After installing, take a moment to read through config/diamond-dj-server.json -- every option is there and the defaults are sensible, but there's a lot you can customize (battle music, streaming, vote skip, auto-start, and more).

Features

Synchronized Playback - All players hear the exact same position in the song
Streaming Mode - Stream audio from YouTube, SoundCloud, Bandcamp, Vimeo, and HTTP URLs
Local Mode - Play OGG files from the server with auto-download and playing
Independent volume controls - Diamond DJ uses the Jukebox / Records volume slider, so players can turn down server DJ music while still keeping vanilla Minecraft music at their preferred volume
Auto-Download - Clients automatically download and plays songs from the server
Vote Skip - Players can vote to skip songs
Customizable HUD - Minimal, verbose, or custom widget layouts
Resource Pack Support - Load music from server resource packs (zips or folders)
Battle Music - Vanilla combat triggers battle tracks with crossfade. Server config can disable battle music.
Dual-Source Battle Audio - In streaming mode, battle music plays on a separate audio source while the global stream runs silently; when battle ends, the stream fades back in instantly
Optional External Services - Can work entirely offline with local OGG files
Cross-Dimension Bleed - Optional otherworldly low-pass for distant fights
Auto-Start Playback - Optional auto-start after server load

Playback Modes

local - Plays OGG files from config/diamonddj/songs/
streaming - Streams audio from URLs via LavaPlayer (YouTube, SoundCloud, Bandcamp, Vimeo, HTTP)

Music Sources (Local Mode)

Diamond DJ supports three modes for loading music locally:

local - Reads OGG files from config/diamonddj/songs/ (default)
resourcepack - Reads OGG files from server resource packs
both - Reads from both; local files take priority on name conflicts

Third-party music resource packs work out of the box - the scanner finds all OGG files regardless of namespace or folder structure. Just drop a zip into `resourcepacks/` and set `musicSource` to `resourcepack` or `both`.

Streaming Sources

YouTube - https://youtube.com/watch?v=VIDEO_ID or https://youtube.com/playlist?list=PLAYLIST_ID
SoundCloud - https://soundcloud.com/artist/track
Bandcamp - https://artist.bandcamp.com/track/song
Vimeo - https://vimeo.com/VIDEO_ID

Configure URLs in config/diamonddj/streaming_playlist.txt (one URL per line). Playlist URLs are automatically expanded into individual tracks.

How It Works locally

Server admin places .ogg files in the songs folder or resource packs
Run /dj start to begin playback
Songs are automatically sent to connecting players
Players can vote to skip with /dj skip

Commands

All Players:

/dj skip - Vote to skip current song
/dj nowplaying - Show current song info

Operators:

/dj start - Start playback
/dj stop - Stop playback
/dj forceskip - Skip without voting
/dj reload - Reload song library and config
/dj list - List all songs
/dj status - Server status
/dj clearcache - Clear all client caches
/dj clearcacheplayer <player> - Clear one client's cache

Streaming (Operators):

/dj play <url> - Play a URL immediately (single track plays once, playlists loop)
/dj queue <url> - Queue a URL to play next
/dj addplaylist <url> - Add all tracks from a playlist URL to the end of the queue
/dj clearqueue - Clear the streaming queue

First-Time Setup

Install the mod on the server and all clients
Start the server once, then stop it. This generates all config files and folders automatically (config/diamond-dj-server.json, config/diamonddj/songs/, config/diamonddj/battle_songs/, config/diamonddj/streaming_playlist.txt)
Read through config/diamond-dj-server.json and adjust settings to your liking
Follow the Local Mode or Streaming Mode setup below

Server Setup (Local Mode)

Install mod on server and all clients
Add .ogg files to: config/diamonddj/songs/
Or set musicSource to resourcepack or both and add resource packs to resourcepacks/
Run /dj start in-game

Server Setup (Streaming Mode)

Install mod on server and all clients
Set "playbackMode": "streaming" in config/diamond-dj-server.json
Add URLs to config/diamonddj/streaming_playlist.txt (one per line)
Restart the server or run /dj reload
Music streams automatically if autoStartEnabled is true, or run /dj start

Server Configuration

Edit config/diamond-dj-server.json:

{
  "voteEnabled": true,
  "voteThresholdPercent": 50,
  "voteTimeoutSeconds": 30,
  "clearCacheOnDisconnect": true,
  "autoStartEnabled": true,
  "battleMusicEnabled": true,
  "enableBattleMusicInStreaming": false,
  "battleSongFolder": "battle_songs",
  "battleRadiusBlocks": 32,
  "combatTimeoutSeconds": 12,
  "combatCooldownSeconds": 2,
  "crossDimensionBleedEnabled": true,
  "crossDimensionLowPassStrength": 0.7,
  "localMusicSource": "local",
  "playbackMode": "local",
  "streamingPlaylistFile": "streaming_playlist.txt",
  "youtubePoToken": "",
  "youtubeVisitorData": "",
  "youtubeOAuthRefreshToken": ""
}

Client HUD

Edit config/diamond-dj-hud.json:

{
  "enabled": true,
  "preset": "SUPER_MINIMAL",
  "anchor": "TOP_LEFT",
  "scale": 1.0
}

Presets: SUPER_MINIMAL (default -- progress bar only, no chat messages), MINIMAL, VERBOSE, NONE, CUSTOM

Requirements

Minecraft 1.21.1
Fabric Loader 0.18.4+
Fabric API
Fabric Language Kotlin

Audio Format

Format: OGG Vorbis only