Screenshot 1 of 2. Night scene over water with the HUD Config panel open and the Music HUD widget near the bottom.
What Music HUD works with.
| Platform | Java Edition |
|---|---|
| Loaders | Fabric, NeoForge |
| Minecraft versions | 1.21.1, 1.21.11, 26.1.2, 26.2, 26.3 |
| Environment | Client, Server |
Music HUD is a Fabric and NeoForge mod that turns the game into a music player powered by NetEase Cloud Music. It adds a GUI, a configurable HUD, synced lyrics and song requests, and changes no game mechanics. It runs on client and server, and plugin editions also exist for Paper, Spigot, Purpur, Folia and Velocity.
Loaders and versions
- Fabric: Minecraft 1.21.1 to 26.3. The newest build requires Modern UI, Fabric API and Forge Config API Port, optionally Mod Menu; some builds for 1.21.1 to 26.2 require Fabric API and Forge Config API Port; some builds for 1.21.1 to 26.2 require Forge Config API Port; some builds for 1.21.6 to 1.21.11 require Architectury API and Forge Config API Port; some builds for 1.21.6 to 1.21.10 need no dependencies; some builds for 1.21.8 require Modern UI, Architectury API and Forge Config API Port.
- NeoForge: Minecraft 1.21.1 to 26.3. The newest build requires Modern UI; some builds for 1.21.1 to 26.2 need no dependencies; some builds for 1.21.6 to 1.21.11 require Architectury API; some builds for 1.21.6 to 1.21.8 require Modern UI and Architectury API.
What it does
- Search songs, playlists, albums and artists, and favourite or subscribe to them.
- Log in by QR code or SMS code to reach your own playlists, and scrobble plays to your NetEase profile.
- Show scrolling lyrics, a fluid background and the requesting player on the HUD.
- Connected mode shares one play queue and progress across the server, with votes to skip. Isolated mode keeps everything on your own client.
- Stream audio without client-side caching, through an OpenAL pipeline that supports every NetEase quality option.
Audio is downloaded and processed on the client, so the server needs little bandwidth. A customizable HUD layout is a future target, not a current feature.
Setting up the API backend
The mod talks to a NetEase Cloud Music API server that you deploy. Single-player, LAN hosts and isolated mode need one. In connected mode the host runs it and joining players do not.
- 1.Install the mod and its required libraries with the Fabric or NeoForge loader.
- 2.Press Download API in the settings page for the guided route, or fetch the binary for your platform from the NeteaseCloudMusicApiEnhanced releases.
- 3.Unzip it into {corepath}/music-hud/ and rename it to api (api.exe on Windows).
- 4.On a dedicated server, run the API separately. If it does not use port 3000, set serverApiBaseUrl in config/music_hud-server.toml.
Compatibility
Music HUD mutes Reactive Music while it plays, and connected mode works with ViaVersion. It turns off the reverb from Sound Physics Perfected on its own audio.
Questions about Music HUD.
4 questions
Does Music HUD work outside China?
It might not work well. Music HUD streams from NetEase Cloud Music, and NetEase's service scope is limited, which Etern warns about directly. No other music platform is supported yet, though QQ Music and Kugou Music are planned.
Do I need to run an API server for Music HUD?
Yes, someone does. Single-player, LAN hosts, isolated mode and dedicated servers need a NetEase Cloud Music API server. In connected mode only the server or LAN host runs it, and joining players need none. The mod can download and manage one for you.
Does Music HUD work on multiplayer servers?
Yes. Connected mode shares a play queue and progress across everyone on the server, which needs Music HUD installed there. Players can also use isolated mode, which does all the work on their own client. Connected mode works with ViaVersion.
Which loaders does Music HUD support?
The mod supports Fabric and NeoForge. Plugin variants cover Bukkit-family servers such as Paper, Spigot, Purpur and Folia, plus Velocity. Forge and Quilt are not listed, and the CurseForge page no longer receives updates.
