🎵 CustomMusic Player

Play your own music inside Minecraft — a full-featured local music player with a MusicBee-style interface. Your tracks, your folders, your queue. Vanilla music is not replaced, the mod runs completely client-side and does not touch OpenAL.

Works with: Minecraft 1.21.1 (NeoForge 21.1.x, Java 21), 1.20.1 (Forge 47.x, Java 17) and 1.19.2 (Forge 43.4.0+, Java 17) — pick the file that matches your version and loader. All three carry exactly the same fixes and features (1.0.1).

Features

• MusicBee-style GUI: folder / artist / album tree on the left, sortable track table in the centre, queue and now-playing panel on the right, transport controls at the bottom.
• Formats: MP3, WAV, FLAC (including hi-res 24-bit and 96 kHz with graceful down-conversion), OGG Vorbis. DSF/DFF is experimental.
• Your folder structure is respected: custommusic/Artist/Album/01 - Track.mp3. Tags are read with jaudiotagger (ID3v1/ID3v2, Vorbis comments, FLAC); if a file has no tags, the name is parsed (Artist - Album - Title.mp3, Artist - Title.mp3).
• Search by title, artist, album or file name, with an instant filter.
• Queue modes: sequential, shuffle, repeat all, repeat one.
• Seek by clicking the progress bar, separate volume control (MASTER_GAIN).
• Background library scanning — a 25 GB / 2500-file library does not freeze the game; the window opens immediately and shows “Scanning library…”.
• Client-side only: no server installation required, no world changes, works in singleplayer and on any server. The jar can also sit in a dedicated server's mods/ folder — it loads and does nothing there.
• Playback goes through Java Sound (SourceDataLine), so it is independent of the game's sound engine and keeps playing while you mine, build or fight.

Controls

All keys are rebindable in Options → Controls → Custom Music.

Commands

/custommusic open      — open the player
/custommusic folder    — print the absolute path of your music folder
/custommusic rescan    — rescan the library
/custommusic selftest  — write an audio diagnostic report to latest.log
                         (which decoders are visible, which files decode, how many
                         seconds of PCM were produced)

Installation

1. Install Minecraft 1.21.1 + NeoForge 21.1.x (or 1.19.2 + Forge 43.4.0+). For 1.21.1 you need Java 21.
2. Download the file that matches your version:
   • custommusic-1.21.1-1.0.1.jar → Minecraft 1.21.1 / NeoForge (no -all suffix: libraries are Jar-in-Jar)
   • custommusic-1.20.1-1.0.1-all.jar → Minecraft 1.20.1 / Forge
   • custommusic-1.19.2-1.0.1-all.jar → Minecraft 1.19.2 / Forge
3. Put it into your mods/ folder. Nothing else to install — all audio decoders are bundled (Jar-in-Jar on NeoForge, shaded into the jar on Forge).
4. Launch the game once. A custommusic/ folder is created next to mods/.
5. Drop your music in, press M, and if the list is empty press Refresh.

Music folder layout:

custommusic/
  Artist/
    Album/
      01 - Track.mp3
      02 - Track.flac
  Another Artist - Single.ogg

Configuration

config/custommusic-client.toml:

[general]
    musicFolder = 'custommusic'        # relative to the game folder; '' = ./custommusic/
    defaultVolume = 0.7                # 0.0 .. 1.0
    pauseVanillaMusic = true
    autoScanOnStartup = true
    defaultPlayMode = 'SEQUENTIAL'     # SEQUENTIAL | SHUFFLE | REPEAT_ALL | REPEAT_ONE
    enableDSF = false
    defaultViewMode = 'FOLDERS'        # FOLDERS | ARTISTS | ALBUMS | ALL

musicFolder also accepts an absolute path, which is handy if you already keep music outside the game folder — use single quotes so backslashes survive TOML parsing:

musicFolder = 'D:/Music'
musicFolder = 'D:\Music'

Restart the game after changing the path.

Note: pauseVanillaMusic and defaultPlayMode are currently reserved settings — the queue always starts in sequential mode and vanilla music is not muted. Everything else in the config is fully functional.

FAQ

Nothing plays / “Unsupported audio format”. Make sure you use the file that matches your Minecraft version and loader, and that the music folder path in the config is correct (/custommusic folder).

OGG tracks are silent or missing. OGG is decoded by the mod's own Vorbis decoder (the old Java Sound SPI for Vorbis returns an empty stream on modern JVMs). If an .ogg file is actually Opus, convert it to Vorbis, FLAC or MP3.

The window opens empty. The library is still being scanned in the background — wait a moment or press Refresh.

Can everyone on a server hear my music? No. The player is client-side: each player hears their own library. Broadcasting music to a server would need a different mod.

Does it slow the game down? No. Decoding and playback run on a separate daemon thread; library scanning is asynchronous.

Compatibility

Built and verified against Minecraft 1.21.1 with NeoForge 21.1.251 (the mod loads and runs on a clean installation; in-game GUI and audio output are up to the player's machine). It is designed not to conflict with other mods: the jar ships no classes that duplicate Minecraft's own libraries (jorbis, slf4j, commons-io, guava, gson, netty, lwjgl, log4j) and its bundled libraries do not share packages with each other, so it does not break NeoForge's JPMS module resolution — the typical cause of “the whole modpack won't start”.

If something does not play, run /custommusic selftest and attach logs/latest.log (search for [CustomMusic]) — the report lists which decoders are visible at runtime and how many seconds of PCM each file produced.

Third-party libraries

Audio decoding is done by third-party libraries, redistributed under their own licenses (all of them permit redistribution with notice):

On NeoForge these jars are shipped as Jar-in-Jar entries inside META-INF/jarjar/, i.e. as separate replaceable jars, which satisfies the LGPL redistribution terms. Full license texts: LGPL-2.1, Apache-2.0, BSD-3-Clause, Xiph.Org BSD.

The mod's own code is MIT licensed: https://github.com/antonovichkorp1985-maker/custommusic-mod/blob/1.21.1-neoforge/LICENSE

Source code & issues

• Repository: https://github.com/antonovichkorp1985-maker/custommusic-mod
• 1.21.1 / NeoForge branch: https://github.com/antonovichkorp1985-maker/custommusic-mod/tree/1.21.1-neoforge
• Bug reports: https://github.com/antonovichkorp1985-maker/custommusic-mod/issues (please attach logs/latest.log — search for [CustomMusic])