Music Looper

Music Looper

Keeps Minecraft’s music playing forever — and lets you play your own songs.

Client-side only, no need to install on the server

---

What it does

1. Continuous vanilla music

Vanilla background music goes silent for a few minutes after each track.
With this mod, one song flows straight into the next — you barely notice a gap.
Track selection works just like vanilla: it picks music based on the biome
and dimension you’re in.

2. Play your own music

The mod creates this folder for you:

.minecraft/config/musiclooper/music/

Just drop your songs in (subfolders work too) and they’ll be added to the
random playlist, alternating with the vanilla music.

Supported formats:

Format	Notes
.ogg	Most reliable — uses Minecraft’s built-in decoder
.mp3	Decoder is bundled, plays out of the box
.wav / .aiff / .au	Uses Java’s built-in decoders

After adding songs, run this command in-game to rescan:

/musiclooper reload

3. Biome-specific music

Want one biome to always play a particular song? You can assign tracks to a
biome, or to a whole category of biomes. See the Configuration section below.

4. Combat music

Put the songs you want to hear while fighting into a separate folder:

.minecraft/config/musiclooper/combat/

Music in this folder is never played during normal rotation. It only starts
when a fight breaks out, and stops on its own once the fight is over — handing
playback back to the regular music.

A fight counts as active when any of these is true:

Condition	Meaning
Taking damage	You just got hit (hurtTime > 0)
Trading blows	You attacked a still-alive target within the last combatTimeoutTicks (default 100 ticks = 5 s)
Being targeted	A living hostile mob within detectRadius (default 16 blocks) has locked onto you (mob.getTarget() == player)

endDelay (default 100 ticks = 5 s) acts as the end buffer, so landing the
final hit doesn’t cut the music off mid-bar.

Relevant settings:

[combatMusic]
    enabled = true            # master switch
    detectRadius = 16         # how far to look for hostile mobs (blocks)
    endDelay = 100            # fade out this many ticks after combat ends
    combatTimeoutTicks = 100  # how long an attack still counts as "in combat"
    volume = 1.0              # volume multiplier
    loop = true               # keep shuffling combat tracks during a fight

Check the current state with:

/musiclooper combat

It reports whether you’re in combat, how many ticks of the end buffer are left,
how many combat tracks were found, and the settings in effect.

5. Shut the vanilla music up

If you only want to hear your own songs, open the config file:

.minecraft/config/musiclooper-client.toml

And set this to true:

[vanilla]
    # Completely disable vanilla music once there is enough custom music
    disableVanillaMusicWhenEnoughCustom = true

    # How many tracks count as "enough" (default: 5)
    customMusicThreshold = 5

Once your track count reaches the threshold, vanilla music stops entirely.

---

Commands

Command	What it does
/musiclooper play <file name>	Immediately stop the current song and play the one you name
/musiclooper biome	Show the biome you’re standing in, and which rule it matched
/musiclooper combat	Show combat music state: in combat or not, how many tracks found
/musiclooper reload	Rescan both music folders
/musiclooper status	Show how many tracks were found, plus current config

---

Configuration

Everything lives in one file:

.minecraft/config/musiclooper-client.toml

It has five sections:

[vanilla]      # vanilla music behaviour
[custom]       # your own music
[biomeMusic]   # per-biome rules
[combatMusic]  # combat music
[fade]         # fade in / fade out

---

[vanilla]

[vanilla]
    # Keep the vanilla music going forever instead of leaving gaps
    loopVanillaMusic = true

    # Fully disable vanilla music once enough custom tracks exist
    disableVanillaMusicWhenEnoughCustom = false

    # How many tracks count as "enough" (default: 5)
    customMusicThreshold = 5

---

[custom]

[custom]
    # Play the tracks found in config/musiclooper/music
    playCustomMusic = true

    # Volume multiplier for your own music (0.0 ~ 1.0)
    customMusicVolume = 1.0

---

[biomeMusic]

Play specific songs in specific biomes.

Five steps to set it up:

1. Put your music into config/musiclooper/music/
2. Open config/musiclooper-client.toml
3. Under [biomeMusic], set enabled = true
4. Write your rules in rules
5. Run /musiclooper reload in-game

Every rule looks like biome ID=file1,file2:

[biomeMusic]
    enabled = true

    rules = [
        # 1. A single biome: only these two play in plains
        "minecraft:plains=calm.mp3,morning.mp3",

        # 2. A biome tag: shared by every forest biome (note the leading #)
        "#minecraft:is_forest=forest_theme.mp3",

        # 3. Fallback: used when nothing above matched
        "*=fallback.mp3",
    ]

    # ONLY_CUSTOM  only your music plays here, vanilla stays quiet (default)
    # MIX          your music and vanilla alternate
    mode = "ONLY_CUSTOM"

Matching order: exact biome → tag → * fallback.

Biome IDs are written namespace:name, and the namespace defaults to minecraft:

"minecraft:plains=..."                # full form
"plains=..."                          # same thing
"biomesoplenty:lavender_field=..."    # biomes from other mods work too

Not sure what the biome ID is? Stand in that biome and run:

/musiclooper biome

It tells you the biome ID, whether a rule matched, and which tracks got picked.

Tags cover a whole category at once — just prefix with #:

"#minecraft:is_forest=forest.mp3"      # all forests
"#minecraft:is_taiga=taiga.mp3"        # all taigas
"#minecraft:is_jungle=jungle.mp3"      # all jungles
"#minecraft:is_ocean=ocean.mp3"        # all oceans
"#minecraft:is_mountain=mountain.mp3"  # all mountains
"#minecraft:is_nether=nether.mp3"      # the whole Nether

Also handy: is_beach, is_river, is_badlands, is_hill, is_savanna, is_overworld.

These are Minecraft’s own groupings, so biomes added by future game updates are
covered automatically.

File names are matched against config/musiclooper/music/ and are
case-insensitive:

"minecraft:plains=Calm.MP3"     # matches calm.mp3

If a file sits in a subfolder, write just the file name — no path needed.

Two things worth knowing:

1. What if a file can’t be found?

If every file named in a rule is missing or undecodable, that biome falls back
to the full random playlist. You never end up with a silent biome — the reason
is written to the log instead.

2. Which setting wins on a conflict?

Biome rules win. Even with “disable vanilla music when there’s enough custom
music” turned on, a matching ONLY_CUSTOM rule takes precedence.

---

[combatMusic]

Combat music lives in its own folder and never joins the normal rotation.

Setup:

1. Put your combat songs into config/musiclooper/combat/
2. Leave enabled = true (the default)
3. Run /musiclooper reload in-game

[combatMusic]
    # Master switch. With an empty folder this does nothing at all.
    enabled = true

    # How far to look for hostile mobs (blocks). A mob in this range that has
    # locked onto you counts as combat.
    detectRadius = 16

    # Keep playing this many ticks after combat ends (100 ticks = 5 s).
    # Prevents the music from cutting out right after your last hit.
    endDelay = 100

    # How long an attack still counts as "in combat" (100 ticks = 5 s).
    combatTimeoutTicks = 100

    # Volume multiplier. Actual volume = this × the in-game "Music" slider.
    volume = 1.0

    # Shuffle combat tracks one after another during a fight.
    # Set to false to play just one track per fight.
    loop = true

Combat tracks and regular tracks are kept in separate lists, so the normal
rotation can never pick a combat track and vice versa.

While combat is active, the mod keeps blocking vanilla music — otherwise the
vanilla track selection would layer on top of your combat music.

Not sure whether it’s working? Run:

/musiclooper combat

It reports whether you’re currently in combat, the remaining end-buffer ticks,
how many combat tracks were found, and the settings in effect.

/musiclooper status also shows the combat track count.

---

[fade]

Third-party music fades in when it starts and fades out before it stops.
This avoids the abrupt cut you’d otherwise get when switching tracks.

[fade]
    # Fade-in length when a track starts (ms). 0 = no fade-in.
    fadeInMs = 1500

    # Fade-out length before stopping or switching (ms). 0 = no fade-out.
    fadeOutMs = 1200

Both “regular music → combat music” and “combat music → regular music”
wait for the current track to finish fading out before the next one starts,
so the transition doesn’t sound jarring.

This only applies to third-party music (tracks in music/ and combat/).
Vanilla music is managed by the game itself, which already applies its own
short volume decay when stopping.

---

If you run into a bug, please leave feedback. Thanks!