Install and open the player

What you need

• Minecraft: use one of the versions listed below, only if a compatible JAR has actually been released for it.
• Loader: Fabric or NeoForge. Use the matching JAR, never both loaders' JARs together.
• Java: Minecraft 1.21.x projects use Java 21; 26.x projects use Java 25.
• Dependencies: install the matching loader dependencies. Do not mix dependency builds for different Minecraft versions.
• Music Pack: required if you want to add your own songs; the mod itself does not provide your personal audio collection.

1. Download the correct Music Interface JAR from CurseForge or Modrinth. Check the file's actual game version and loader.
2. Install the dependencies shown on that file's release page and loader metadata.
3. Place the JAR and dependency JARs in your Minecraft instance's mods/ directory.
4. Launch the game. Open the Music Interface player using its assigned keybind or in-game UI entry point. Check Minecraft's Controls menu if you need to find or change the keybind.
5. Enable a Music Pack from Minecraft's Resource Packs screen. The library is filled from active packs.

Settings screen: Music Interface integrates with Cloth Config, when installed and compatible. Without Cloth Config, the mod still loads, but the in-game settings screen is not available through that integration. Advanced users can edit config/musicinterface/config.json while the game is closed.

Compatibility and dependencies

Configured source targets

That is 18 configured loader/version outputs. Targets are not evidence of verified release availability, binary compatibility, or runtime passing tests.

Root Minecraft 1.21.1 metadata

These constraints apply to the root 1.21.1 source, not automatically to every other version project. For a different version, inspect that project's gradle.properties, loader metadata and release dependency list. Java 25 belongs to the 26.x generation.

Menu, ambient and contextual playback

Music Interface controls a custom playback scheduler. There are two complementary concepts:

• Music metadata: genres, moods, tags and energy describe songs and assist Radio/Smart Mixes.
• Music contexts: explicit rules in music_data.json or music_contexts.json tell the scheduler when a track is eligible. Supported conditions are dimension, biome, biome tag, day/night, weather and Cobblemon combat active/inactive.

For actual JSON and fully working examples, see the Music Pack guide, or the French Music Pack guide.

Title screen

The customMenuMusicEnabled option enables Music Interface music on the title screen (enabled by default).

• If Title-screen track ID is empty, eligible library songs can be selected automatically for the menu. Empty does not mean disabled.
• If the ID contains an existing track ID, that track is reserved for custom title-screen autoplay and is excluded from world autoplay.
• To stop custom title-screen music, switch Custom menu music off.
• Allow vanilla menu music is separate and controls Minecraft's original menu soundtrack.
• Title-screen autoplay uses the menu selection path; in-world context filters are not applied on the title screen.

Ambient versus Continuous

• Ambient (default): the scheduler can leave a configurable gap between songs in a world.
• Continuous: no intentional between-track delay.
• World join silence: waits after entering a world before scheduled music starts; default is 10 seconds.

Context selection

• A context rule matches when all its specified condition groups match. For a group accepting multiple values, any listed value may match.
• More than one rule can be attached to a track. A matching rule makes the track eligible.
• The scheduler selects from the highest matching numerical priority. Greater specificity alone does not raise priority.
• If nothing matches, Library fallback (default) considers the normal available library, while Dedicated fallback restricts fallback to tracks marked context_fallback: true.
• Finish (default) waits for the current track to finish after a context change. Crossfade can transition a track that the context scheduler started, when a different track is preferred.
• A manually chosen track, queue item, playlist or Radio source does not become a forced battle cue just because a rule exists.
• Track cooldown and disabled/failed tracks also affect automatic selection.

Cobblemon battles

Cobblemon integration is optional. The Cobblemon Battle Music setting defaults to External so Music Interface yields control while a recognized battle is active.

To let Music Interface select battle music:

1. Install a compatible Cobblemon version for your Minecraft/loader, if one is available.
2. In Music Interface settings, set Cobblemon Battle Music to Context (value context).
3. Enable Context Music.
4. Add tracks with a "combat": true context rule and an appropriate priority.
5. To resume exploration music after battle, provide "combat": false rules or other eligible fallback tracks.
6. If you want contextual music to switch during an already-playing contextual song, choose Crossfade instead of Finish.

A tag named battle alone does not create a battle event. Music Interface also supports an optional CobbleSafari music-coordination bridge; neither Cobblemon nor CobbleSafari is required for ordinary playback.

Settings explained

The in-game Cloth Config screen groups settings into Playback, Timing, Context, Library and Toast. Defaults below come from the 1.21.1 source configuration, not necessarily from an older user config file.

Two different weights: a track's weight affects selection relative to other tracks. customWeight changes the balance between Music Interface and Minecraft's vanilla music.

Files and privacy

The following files live under the current Minecraft instance's config/musicinterface/ folder:

Recent listening History is a separate in-memory list, not a long-term disk log. Back up your config directory before reinstalling, migrating instances or resetting statistics. The profile remains local; its code does not upload usage telemetry.

Commands and multiplayer

Distinguish client-local commands from administrator commands. A local player command does not imply that every multiplayer server allows the same literal syntax.

Client-side commands

Client aliases can conflict with server command names in some setups. The local diagnostics alias is usually the clearest way to inspect a Music Pack.

Dedicated / integrated server command tree

These commands are registered on the server side with permission level 2. They require the relevant server installation; some actions also require compatible Music Interface clients.

For example, /musicinterface play route_01 @a sends the track request to all eligible players, if the server knows route_01 and those clients have the corresponding music resource. The command does not transmit the OGG file. In single-player and multiplayer, permission and command registration may differ.

A beginner-friendly guide to adding your own songs, cover art and music for specific situations in Minecraft.

Music Interface reads music from a standard Minecraft resource pack. You do not need to program a mod. The track metadata format works on Fabric and NeoForge, but vanilla resource-pack compatibility metadata must match the Minecraft version you use.

For the player, settings, queues, playlists and Radio, see the complete user guide.

Quick answers

• Where are songs assigned to events? In a track's contexts field or optional music_contexts.json.
• Are tags enough for battle music? No. tags, genres and moods describe songs for Radio and recommendations; they do not trigger events.
• How do I pick one menu theme? Enter its song id in the Title-screen track ID setting. Blank allows automatic menu selection.
• How does Cobblemon music work? Set Cobblemon Battle Music to Context and use a combat: true context rule.
• Can I combine packs? Yes, including folders and ZIP files. Keep song IDs unique.

1. Create the pack folder

Open the folder of your Minecraft instance, then create My Music Pack inside its resourcepacks/ directory:

.minecraft/
└── resourcepacks/
    └── My Music Pack/
        ├── pack.mcmeta
        ├── pack.png                         (optional)
        └── assets/
            └── musicinterface/
                ├── music_data.json
                ├── music_contexts.json      (optional)
                ├── sounds.json
                ├── sounds/
                │   └── custom/
                │       ├── route_01.ogg
                │       └── battle_theme.ogg
                └── textures/
                    └── covers/
                        ├── route_01.png
                        └── battle_theme.png

Exact spelling matters. Music Interface reads the namespace assets/musicinterface/. Use lowercase names without spaces or accents for resource paths.

Easier option: generate a template

Open the Music Interface player and use its template generation control (hover for the tooltip). The mod creates resourcepacks/MusicInterface Template/ with folders, basic JSON and an example cover. It does not overwrite existing template files.

Replace the example track with your own OGG, then update its paths and IDs. The generated pack.mcmeta is a baseline example that may require changes for your Minecraft version.

2. Set up pack.mcmeta

Minecraft reads pack.mcmeta before enabling a resource pack. The project generator uses this for the Minecraft 1.21.1 baseline:

{
  "pack": {
    "pack_format": 34,
    "description": "My Music Pack for Music Interface"
  }
}

Do not copy pack_format: 34 blindly to 1.21.4, 1.21.11 or 26.x. Resource-pack metadata changes between Minecraft versions. Some versions also require different/additional format fields. Use the requirements for your exact Minecraft version. The music metadata documented below is independent of Fabric versus NeoForge.

If Minecraft reports that the pack is incompatible, fix pack.mcmeta first.

3. Add OGG files

Put your song here:

assets/musicinterface/sounds/custom/route_01.ogg

Use actual OGG audio, not an MP3 renamed to OGG. Short, consistent file names are easiest to manage.

4. Register sounds in sounds.json

Minecraft needs a sound event entry for each OGG. Save this file as assets/musicinterface/sounds.json:

{
  "custom/route_01": {
    "sounds": [
      {
        "name": "musicinterface:custom/route_01",
        "stream": true
      }
    ]
  },
  "custom/battle_theme": {
    "sounds": [
      {
        "name": "musicinterface:custom/battle_theme",
        "stream": true
      }
    ]
  }
}

The event musicinterface:custom/route_01 points to assets/musicinterface/sounds/custom/route_01.ogg. Omit the file extension and the sounds/ folder from the JSON name. Keep "stream": true for long music.

5. Register tracks in music_data.json

Save a JSON array inside assets/musicinterface/music_data.json. Here are two tracks:

[
  {
    "id": "route_01",
    "title": "Route 01",
    "author": "Your Name",
    "album": "Exploration",
    "sound": "musicinterface:custom/route_01",
    "cover": "musicinterface:textures/covers/route_01.png",
    "enabled": true,
    "weight": 1,
    "genres": ["ambient"],
    "moods": ["calm"],
    "tags": ["overworld", "exploration"],
    "energy": 0.3,
    "contexts": [
      {
        "combat": false,
        "priority": 10
      }
    ]
  },
  {
    "id": "battle_theme",
    "title": "Battle Theme",
    "author": "Your Name",
    "album": "Battles",
    "sound": "musicinterface:custom/battle_theme",
    "cover": "musicinterface:textures/covers/battle_theme.png",
    "enabled": true,
    "weight": 2,
    "genres": ["orchestral"],
    "moods": ["intense"],
    "tags": ["battle", "combat"],
    "energy": 0.9,
    "contexts": [
      {
        "combat": true,
        "priority": 100
      }
    ]
  }
]

route_01 can match when no battle is active; battle_theme can match while a compatible Cobblemon battle is active. You still need to enable Cobblemon's Context mode in settings, as explained below.

Track fields

Optional fields can be omitted. Simple older track definitions remain valid in the 2.0 parser.

Use consistent labels, such as calm or orchestral, across your library to make Radio similarity useful. No fixed genre, mood or tag vocabulary is required.

Tags vs contexts

A tag answers "what kind of music is this?" A context answers "when can the scheduler choose it?"

{
  "tags": ["battle", "boss"],
  "contexts": [
    {
      "combat": true,
      "priority": 100
    }
  ]
}

This block shows fields within a track, not a standalone music_data.json file. Only contexts creates the battle condition; tags helps with similarity.

Context rule fields

For list properties, you may use a single string or an array. Multiple values in one property mean OR; different properties in one rule must all match (AND). Several rule objects represent alternative situations.

For example, this rule matches rain or thunder, at night, on plains in the Overworld, outside combat:

{
  "dimensions": ["minecraft:overworld"],
  "biomes": ["minecraft:plains"],
  "time": ["night"],
  "weather": ["rain", "thunder"],
  "combat": false,
  "priority": 30
}

Priority is explicit: a more specific rule is not automatically stronger than a general rule. A missing contexts rule does not restrict a song to any particular biome. Unrestricted/legacy songs can remain eligible during library fallback.

6. Ambient / exploration music

Put this property into an exploration track:

"contexts": [
  {
    "combat": false,
    "priority": 10
  }
]

To select forest music, add "biomes": ["minecraft:forest"] inside that rule. For time or weather, add time or weather.

Ambient is also a global playback mode: it can leave a delay between tracks. It is not a special tag or context value. Continuous removes the intentional delay.

7. Cobblemon battle music

For a song meant to play during a detected battle:

"contexts": [
  {
    "combat": true,
    "priority": 100
  }
]

Also configure the mod:

1. Install compatible Cobblemon for the loader/game version, where available.
2. Turn Context Music on in Music Interface.
3. Set Cobblemon Battle Music to Context. Its default External mode suspends Music Interface music while a Cobblemon battle is detected.
4. Select Context Transition: Crossfade if you want an already-playing context-managed song to change during context switches. Default Finish allows it to finish.
5. Provide non-combat tracks, or a fallback library, for when battles end.

The integration observes supported Cobblemon battle events, not arbitrary Minecraft damage or other combat mods. A manual track, pending queue, Radio or playlist may take priority over context autoplay.

8. Title-screen music

A menu track is assigned through player settings, not by adding a menu tag:

1. Add your menu song to music_data.json and sounds.json, with ID main_menu_theme.
2. In Music Interface settings, enable Custom Menu Music.
3. Set Title-screen track ID to main_menu_theme.

A blank title-screen track ID lets the mod choose automatically from the library on the title screen. To stop custom title-screen music, turn Custom Menu Music off. The Allow Vanilla Menu Music switch only controls Minecraft's own music. In-world context filtering is not applied to title-screen selection.

9. Optional music_contexts.json

If you prefer to keep context rules separate from song metadata, create assets/musicinterface/music_contexts.json. A JSON object keyed by track ID is supported:

{
  "route_01": [
    {
      "combat": false,
      "priority": 10
    },
    {
      "biomes": ["minecraft:forest"],
      "time": ["day"],
      "combat": false,
      "priority": 30
    }
  ],
  "battle_theme": [
    {
      "combat": true,
      "priority": 100
    }
  ]
}

An array of rules is also supported:

[
  {
    "track": "route_01",
    "combat": false,
    "priority": 10
  },
  {
    "track": "battle_theme",
    "combat": true,
    "priority": 100
  }
]

External rules are added to a track's inline rules. When multiple packs supply external rules for the same track ID, the higher-priority pack's external definition wins. A reference to an unknown track ID produces a warning.

For simple packs, choose either inline contexts or music_contexts.json, to avoid duplicating rules unintentionally.

10. Fallback when nothing matches

In Context Fallback settings, select:

• Library (default): choose from available tracks if no explicit context matches.
• Dedicated: choose only songs marked "context_fallback": true if no rule matches.

Example single track for the music_data.json array:

{
  "id": "route_01",
  "title": "Route 01",
  "sound": "musicinterface:custom/route_01",
  "context_fallback": true,
  "contexts": [
    {
      "combat": false,
      "priority": 10
    }
  ]
}

11. Covers, pack priority and reload

Place covers under assets/musicinterface/textures/covers/ and reference them by resource ID:

"cover": "musicinterface:textures/covers/route_01.png"

Toast colors: the Now Playing toast automatically samples its border accent from the track's cover artwork. If no usable cover is available, it uses a built-in fallback accent. There is no setting or Music Pack JSON field for choosing an arbitrary outline color.

Enable the folder or ZIP pack in Minecraft's Resource Packs menu. After editing, press F3+T. Music Interface rebuilds the track list from active packs; it does not accumulate old definitions.

When two packs define the same id, the higher-priority pack wins. Prefer stable, unique IDs: playlists and favorites store these IDs.

Use the local /musicinterface_diagnostics client command to see active packs, duplicate IDs, missing audio events, missing covers and parse warnings. NeoForge also registers /musicinterface diagnostics locally; a server command with the same name may require administrator permissions.

12. Common problems

Advice: start with one OGG and one JSON entry, make it play, then add contexts and metadata. Keep permissions for the recordings and artwork you distribute.

Frequently asked questions

Does Music Interface come with music? Where do I download tracks?

No songs or ready-made music library are included. You must create or obtain a separate Music Pack (a Minecraft resource pack with OGG audio and track metadata). These packs may be made by you or shared by modpack/server creators. There is no built-in music catalog or automatic download service. See Music Packs for the full setup.

Why can't I find any songs, including Minecraft's vanilla soundtrack?

The Music Interface library displays custom tracks declared by active Music Packs. Vanilla Minecraft music is handled by Minecraft's own music system and does not appear automatically as Music Interface tracks. If you only installed the mod, an empty library is expected. Check that a valid pack is enabled, then reload with F3+T.

Is Music Interface a Cobblemon mod? Can I use it without Cobblemon or with an older Cobblemon version?

Music Interface is independent of Cobblemon. Ordinary music playback works without Cobblemon, as long as you install the correct Minecraft/loader build and a Music Pack. Cobblemon is an optional integration for battle detection; its battle features depend on the versions and integration hooks available. Having an older Cobblemon release does not make Cobblemon a required dependency for the player.

Does Music Interface work with Constant Music or other music mods?

Music Interface does not automatically read another mod's track list or resource files. Other mods may also manage Minecraft's MUSIC sound channel, so universal compatibility is not guaranteed. Music Interface has playback controls for vanilla/external music and a strictExclusiveMusic option to avoid starting music over another active soundtrack. If tracks overlap or interrupt one another, review both mods' music settings or let only one mod manage automatic music. You still need a Music Pack for Music Interface tracks.

What are moods, and do they control when songs play?

moods describe the atmosphere of a track, for example calm, relaxing or intense. Along with genres, tags and energy, they help Track Radio and Smart Mixes find related songs. Moods and tags are not event triggers. A song tagged battle is not automatically played during a battle.

How can I assign music to the menu, exploration or Cobblemon battles? Do I need Minecraft predicates?

No vanilla Minecraft predicates are required. Use the contexts rules in a track's music_data.json, or put them in music_contexts.json. Rules can match dimension, biome, biome tags, day/night, weather and Cobblemon combat. Example: "combat": true with a priority selects a battle track when the Cobblemon battle mode is set to context. The menu is handled separately by the Title-screen track ID setting. See examples for both files.

Can I change the Now Playing toast outline color?

The accent color is generated automatically from each track's cover art, with a default fallback if no usable cover exists. You can change the cover in your Music Pack, but Music Interface 2.0 has no manual outline-color setting.

Can a resource-pack lang file translate music titles?

The mod interface itself supports language files, but custom track names in music_data.json are currently plain display strings. The title value is displayed as written, not resolved as a translation key from assets/.../lang/*.json. Automatic per-language music title translation is not supported in 2.0. Authors should supply a readable title, or offer separate translated metadata packs where appropriate.

The generated template appears in the list, but its example track is silent. Why?

The template is a starting structure: it provides an example track definition, a sound event and cover, but not the example_track.ogg audio file. Add a real OGG file at the referenced path or replace the example with your song, then reload resources.

Troubleshooting

When asking for help, provide the exact Minecraft version, loader, Music Interface JAR/version, relevant dependencies, steps to reproduce and latest.log excerpts (with private details removed).