Set The Background Music

English | 中文

Play your own background music in the Minecraft main menu and in-game, with support for multiple audio formats.

Vanilla music only plays in specific situations? Now you can play your favorite music right from the main menu.

• Recursively scans all audio files under config/setthebackgroundmusic/music/
• 34+ supported formats (see the format table below)
• Dual-engine playback: Melody (OpenAL) + JavaFX MediaPlayer, with automatic fallback
• JAVE2 (FFmpeg) transcodes extended formats; users do not need to install FFmpeg
• Bilingual UI: English and Simplified Chinese
• Auto-recovery: resumes playback after resource reload (F3+T) or opening the settings menu
• Single track loop / sequential loop / shuffle
• Three shuffle modes: true random / no-repeat / weighted (favorites get 3x weight)
• Subfolder categories: switch playlists by category
• Favorites and play history
• HUD: shows current track and volume when switching songs
• Fade in / fade out: smooth transitions between tracks
• Automatically disables vanilla background music
• Vanilla-style toast notifications
• Persistent config (config.json)
• Full /music command system with tab completion

1. Put the mod JAR into your .minecraft/mods folder
2. Launch the game (the config folder is created on first run)
3. Put your music files into config/setthebackgroundmusic/music/
4. Run /music reload in-game, or restart the game

First launch: the JavaFX engine may fail first and then fall back to Melody. Seeing JavaFX playback failed, falling back to Melody in the log is expected.

The no-FFmpeg build (noffmpeg-universal) only supports .ogg .wav .mp3 .aiff .aif .aifc .au.

All variants share the same mod ID. Install only one, or Fabric will report a duplicate mod.

/music play "Aria Math"            -> Play Aria Math
/music volume 75                   -> Set volume to 75%
/music shufflemode WEIGHTED        -> Favorites get 3x weight
/music category BGM                -> Switch to the BGM category (music/BGM/)
/music fav                         -> Favorite the current track

config/setthebackgroundmusic/music/
├── song1.ogg
├── song2.mp3
├── BGM/                          <- category
│   ├── calm.ogg
│   └── battle.mp3
└── Vocal/                        <- category
    └── pop.flac

A category is simply a subfolder name. /music category BGM only plays tracks inside BGM/.

The file config/setthebackgroundmusic/config.json is created on first run:

{
  "modEnabled": true,
  "shuffle": false,
  "volume": 0.5,
  "fadeEnabled": true,
  "fadeDurationMs": 800,
  "hudEnabled": true,
  "hudDisplaySeconds": 5,
  "shuffleMode": "TRUE_RANDOM",
  "history": [],
  "favorites": [],
  "activeCategory": ""
}

gradlew clean build -Pffmpeg_platforms=win64

Platform identifiers (case-sensitive, lowercase):

Multiple platforms, comma-separated, no spaces:

gradlew clean build -Pffmpeg_platforms=win64,osx64,osxm1

Double-click build-all.bat. Output goes to release/.

• JDK 25 (required)
• Gradle 9.7.1+
• Fabric Loom 1.17.17+

• Melody - OpenAL audio playback library
• JavaFX - MP3 / AAC decoding
• JAVE2 - FFmpeg Java wrapper
• Fabric - Mod loader

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

It uses JAVE2, which is also licensed under GPL-3.0.

Found a problem? Please open an Issue.

Enjoy your custom background music.