Diamond DJ

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

1. Server admin places .ogg files in the songs folder or resource packs
2. Run /dj start to begin playback
3. Songs are automatically sent to connecting players
4. 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

1. Install the mod on the server and all clients
2. 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)
3. Read through config/diamond-dj-server.json and adjust settings to your liking
4. Follow the Local Mode or Streaming Mode setup below

Server Setup (Local Mode)

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

Server Setup (Streaming Mode)

1. Install mod on server and all clients
2. Set "playbackMode": "streaming" in config/diamond-dj-server.json
3. Add URLs to config/diamonddj/streaming_playlist.txt (one per line)
4. Restart the server or run /dj reload
5. 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