Set the background music NEW

Set The Background Music

Author: luocheng-maker

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.

Features

• Recursively scans all audio files under config/setthebackgroundmusic/music/
• Supported formats: .ogg .wav .mp3 .m4a .aac .aiff .aif .au .flac .opus .wma .ape .wv .mka
• Dual-engine playback: Melody (OpenAL) + JavaFX MediaPlayer, with automatic fallback
• JAVE2 (FFmpeg) transcodes extended formats; users do not need to install FFmpeg
• 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

Installation

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 to scan files, 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.

Supported Formats

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

JAR Variants

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

Commands

Examples

/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

Music Directory Layout

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/.

Configuration

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": ""
}

Building

Single platform

gradlew clean build -Pffmpeg_platforms=win64

Platform identifiers (case-sensitive, lowercase):

Multiple platforms, comma-separated, no spaces:

gradlew clean build -Pffmpeg_platforms=win64,win-arm64

Build all variants at once

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

Requirements

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

Credits

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

Feedback

Found a problem? Please open an Issue.

Enjoy your custom background music.