Minecraft Music Player

Minecraft Music Player is a Fabric music mod for Minecraft 1.21.11. It provides NetEase Cloud Music search, song requests, shared queue playback, playlist playback, custom music discs, and URL-based jukebox playback.

The server handles commands, queue logic, search requests, sync, random loot disc injection, and jukebox control. The client handles actual audio download, playback, and jukebox cover rendering. This is a dual-side mod, not a pure server-side audio mod.

Features

• Search songs, artists, playlists, and users
• View artist top songs, playlist details, and user playlists
• Unified paging and clickable navigation for all major list pages
• Clickable actions for request, burn, detail view, and download
• Shared song requests, queue playback, auto-advance, and vote skip
• Duplicate request deduplication and move-queued-track-to-next support
• Server-side queue prefetching to reduce delay between tracks
• Burn songs into vanilla music discs and play URL-based music from jukeboxes
• /music random generates 10 random hot songs each time
• All loot-table-backed containers can spawn random hot music discs based on admin settings

How It Works

• The server handles command execution, search requests, playback queue, loot disc generation, and jukebox synchronization
• The client handles actual audio playback and jukebox cover rendering
• If only the server installs the mod, commands and queue logic work, but clients cannot hear music
• Players who want to hear music must install the mod on the client

Recommended setup:

1. Install Minecraft Music Player on the server
2. Install Minecraft Music Player on clients that should hear music
3. Make sure the server or clients can access a working music API endpoint

Requirements

• Minecraft 1.21.11
• Fabric Loader 0.18.4 or newer
• Fabric API 0.141.3+1.21.11 or a compatible version
• Java 21
• A reachable NetEase-related music API service, defaulting to https://mycelis.dpdns.org/

Installation

Server

Put the mod jar and Fabric API into the server mods folder.

Client

Put the mod jar and Fabric API into the client mods folder.

Default API Address

Default configuration uses:

https://mycelis.dpdns.org/

Admins can override it by command and restore the default later.

Music Discs

Burn flow

1. Hold any vanilla music disc in the main hand
2. Run /music burn song <song_id>
3. Or click [Burn] in supported list pages
4. Receive a custom music disc storing the track metadata and URLs

Disc metadata

A burned disc stores:

• song ID
• song title
• artist name
• artist ID
• cover URL
• duration
• available source URLs

Jukebox playback

• Inserting a burned disc into a jukebox automatically plays the stored URL music
• Playback is spatialized around the jukebox instead of acting like a global background track
• The four sides of the jukebox render a rotating disc-style cover effect
• Playback stops when the disc is ejected, replaced, the jukebox is broken, the chunk unloads, or the player leaves audible range
• Pending placeholder discs cannot be inserted into jukeboxes and will do nothing if used on one

Burn entry points

When the player holds a burnable disc in the main hand, a [Burn] action is shown automatically in these views:

• /music now
• /music queue
• /music random
• /music search song ...
• /music view playlist ...
• /music view artist ...
• /music view author ...

Random Hot Music

Use:

/music random

Behavior:

• Generates 10 random hot songs each time
• The source is hot playlists selected from hot playlist categories
• Each refresh produces a different list
• Every entry supports:
  • request song
  • burn to disc
  • view artist details
  • open the direct download URL

Loot Container Random Music Discs

The mod can inject random hot music discs into all loot-table-backed containers when they are opened for the first time.

Behavior:

• Applies to both block containers and entity containers backed by loot tables
• Each container is decided only once
• On first open, a temporary "generating" placeholder disc is inserted first and the real disc is resolved asynchronously in the background
• If the player takes the placeholder disc out early, it will still resolve later inside the player's inventory or the currently open container
• The original vanilla disc item type is preserved after resolution, so the color and appearance do not change
• Generated discs come from random hot songs selected from hot playlists
• Admins can configure whether this is enabled, the generation chance, and how many discs may be generated per container

Player Commands

Admin Commands

Configuration

Configuration file path:

config/minecraft-music-player.json

Default config example:

{
  "neteaseBaseUrl": "https://mycelis.dpdns.org/",
  "proxy": "",
  "useSystemProxy": true,
  "preferIpv4": true,
  "allowCustomServer": true,
  "allowSongRequest": true,
  "allowPlaylistRequest": true,
  "autoAdvance": true,
  "announceQueueChanges": true,
  "showLoadingHints": true,
  "connectTimeoutSeconds": 10,
  "readTimeoutSeconds": 20,
  "searchLimit": 8,
  "maxQueueSize": 40,
  "playlistQueueLimit": 20,
  "queueCacheSize": 3,
  "enableLootMusicDiscs": true,
  "lootMusicDiscChance": 0.3,
  "lootMusicDiscCount": 1,
  "voteSkipPercent": 0.6
}