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:

Install Minecraft Music Player on the server
Install Minecraft Music Player on clients that should hear music
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

Hold any vanilla music disc in the main hand
Run /music burn song <song_id>
Or click [Burn] in supported list pages
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

Command	Description
`/music`	Show help
`/music now`	Show the current track with a clickable download entry
`/music queue [page]`	Show the current queue
`/music queue next <song_id>`	Move a queued song to the next position
`/music join`	Join current playback
`/music leave`	Leave current playback
`/music mute once`	Stop receiving only the current song
`/music vote next`	Vote to skip to the next track
`/music play song <song_id>`	Request a single song
`/music play playlist <playlist_id>`	Switch into playlist playback mode
`/music burn song <song_id>`	Burn the held disc into a music disc
`/music random`	Generate 10 random hot songs
`/music random refresh`	Generate another random hot song list
`/music search song <keyword>`	Search songs
`/music search song page <page> <keyword>`	View a specific page of song search results
`/music search artist <keyword>`	Search artists
`/music search artist page <page> <keyword>`	View a specific page of artist search results
`/music search author <keyword>`	Alias of `artist`
`/music search playlist <keyword>`	Search playlists
`/music search playlist page <page> <keyword>`	View a specific page of playlist search results
`/music search user <keyword>`	Search users
`/music search user page <page> <keyword>`	View a specific page of user search results
`/music view artist <artist_id>`	View artist top songs
`/music view artist page <page> <artist_id>`	View a specific page of artist details
`/music view author <artist_id>`	Alias of `artist`
`/music view playlist <playlist_id>`	View playlist details
`/music view playlist page <page> <playlist_id>`	View a specific page of playlist details
`/music view user <user_id>`	View user playlists
`/music view user page <page> <user_id>`	View a specific page of user playlists

Admin Commands

Command	Description
`/music admin reload`	Reload config
`/music admin status`	Show current config status
`/music admin clearqueue`	Clear queued tracks
`/music next`	Skip immediately to the next track
`/music stop`	Stop playback
`/music admin set baseUrl <url>`	Set the music API base URL, or use `default` to restore the default
`/music admin set allowCustomServer <true\|false>`	Allow custom API URL or not
`/music admin set allowSongRequest <true\|false>`	Allow song requests or not
`/music admin set allowPlaylistRequest <true\|false>`	Allow playlist import or not
`/music admin set autoAdvance <true\|false>`	Enable auto-advance or not
`/music admin set announceQueueChanges <true\|false>`	Broadcast queue changes or not
`/music admin set showLoadingHints <true\|false>`	Show search and resolve hints or not
`/music admin set useSystemProxy <true\|false>`	Enable system proxy discovery or not
`/music admin set preferIpv4 <true\|false>`	Prefer IPv4 or not
`/music admin set proxy <host:port>`	Set HTTP proxy
`/music admin set proxy none`	Clear proxy
`/music admin set connectTimeoutSeconds <3-60>`	Set connect timeout
`/music admin set readTimeoutSeconds <3-120>`	Set read timeout
`/music admin set searchLimit <3-20>`	Set list page size
`/music admin set maxQueueSize <1-200>`	Set queue size limit
`/music admin set playlistQueueLimit <1-100>`	Set maximum imported songs per playlist
`/music admin set queueCacheSize <0-20>`	Set server-side queue prefetch size
`/music admin set enableLootMusicDiscs <true\|false>`	Enable random music discs in loot containers
`/music admin set lootMusicDiscChance <0.0-1.0>`	Set the generation chance for random loot music discs
`/music admin set lootMusicDiscCount <0-5>`	Set how many random music discs a loot container may generate
`/music admin set voteSkipPercent <0.1-1.0>`	Set vote skip ratio

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
}

中文

Minecraft Music Player 是一个面向 Minecraft 1.21.11 的 Fabric 音乐模组，提供基于网易云音乐的共享播放队列、搜索、点歌和播放同步能力。

服务端负责命令、队列、搜索、同步和配置管理；客户端负责实际的音频拉取和播放。因此这是一个双端协作的模组，而不是纯服务端音频模组。

功能概览

搜索歌曲、作者、歌单和用户
查看作者热门歌曲、歌单详情和用户歌单
所有主要列表支持分页与可点击导航
所有高频条目支持点击查看详情、点歌、刻录或下载
共享点歌、待播队列、自动下一首、投票切歌
重复点歌自动去重，待播歌曲支持提升为下一首
服务端队列预缓存，减少切歌解析等待
将歌曲刻录进原版唱片，并放入唱片机播放 URL 音乐
/music random 每次生成 10 首随机热门音乐，可直接点歌和刻录
所有带战利品表的容器都可按配置随机生成热门音乐唱片

工作方式

服务端安装本模组后，负责命令处理、搜索请求、播放队列、战利品箱随机唱片和唱片机同步
客户端安装本模组后，负责实际播放音频和渲染唱片机封面
只有服务端安装时，命令和队列逻辑可以工作，但客户端听不到声音
需要听歌的玩家必须安装客户端模组

推荐部署方式：

服务器安装 Minecraft Music Player
所有需要听歌的客户端也安装 Minecraft Music Player
服务器或客户端网络可以访问可用的音乐 API

依赖要求

Minecraft 1.21.11
Fabric Loader 0.18.4 或更高版本
Fabric API 0.141.3+1.21.11 或兼容版本
Java 21
一个可访问的网易云音乐相关 API 服务，默认地址为 https://mycelis.dpdns.org/

安装

服务端

将模组主文件和 Fabric API 放入服务器的 mods 目录。

客户端

将模组主文件和 Fabric API 放入客户端的 mods 目录。

默认 API 地址

默认配置使用：

https://mycelis.dpdns.org/

管理员可以通过命令修改地址，也可以恢复到默认值。

音乐唱片

刻录流程

主手持有任意原版唱片
使用 /music burn song <歌曲ID>
或在支持的列表页面中点击 [刻录]
获得带有歌曲 URL 和元数据的自定义音乐唱片

唱片保存的数据

歌曲 ID
歌曲名
作者名
作者 ID
封面 URL
时长
可用音源 URL 列表

唱片机播放

将刻录后的唱片放入唱片机后自动播放其中的 URL 音乐
播放会跟随唱片机位置同步，而不是全局背景音乐
四个侧面会渲染旋转中的唱片封面效果
唱片被弹出、替换、唱片机被破坏、区块卸载或玩家离开可听范围后会停止播放
“正在生成”的占位唱片不能放入唱片机，使用时不会有任何反应

支持的刻录入口

当主手持有可刻录唱片时，这些界面会自动出现 [刻录]：

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

随机热门音乐

使用：

/music random

行为说明：

每次生成 10 首随机热门音乐
来源是热门歌单分类下的热门歌单，再从歌单中随机抽歌
每次生成的列表都不同
列表中的每一首歌都支持：
- 点歌
- 刻录
- 查看作者详情
- 下载当前直链

战利品箱随机音乐唱片

本模组支持在所有带战利品表的容器第一次被打开时，按配置随机注入热门音乐唱片。