Maestro

Posted Feb 5, 2026 Updated Feb 12, 2026

Written By Obscuria

12 min read

Maestro

Maestro is a data-driven music orchestration framework for Minecraft, giving modpack and map creators full control over music behavior. The information provided here is intended to help understand the key concepts of the mod and customize it to your needs.

Core Concepts

Maestro is built around the idea that music should be continuous, reactive, and context-aware. Instead of treating music as isolated tracks separated by silence, Maestro treats it as an evolving soundtrack that responds to gameplay in real time.

All music behavior is fully data-driven and configured either through resource packs or via the config folder using the Fragmentum Layer system.

Resource Loading

Maestro loads music definitions from both resource packs and Fragmentum Layer. Both sources use exactly the same format and are processed identically.

assets/
└── <namespace>/          -> the namespace of your pack
    ├── sounds.json       -> sound event registration
    ├── sounds/           -> audio files (.ogg)
    └── music/            -> maestro music definitions

Music Layers

Maestro organizes music into two logical layers, each with a clear purpose:

UNDERSCORE: The persistent background layer. Used for ambient and exploratory music tied to dimensions, biomes, time of day, or other slowly changing conditions.
ENCOUNTER: A dynamic foreground layer. Used for temporary situations such as structures, boss fights, special events, or short-lived encounters.

When an Encounter track becomes active, the Underscore layer smoothly fades down in volume instead of stopping. Importantly, the background music keeps its progress while muted – so when the encounter ends, the underscore fades back in naturally, continuing from where it left off instead of restarting.

Priority System

Multiple music definitions can match the same game state at the same time. Priorities are evaluated within each music layer independently. When multiple definitions compete in the same layer, Maestro selects the one with the highest priority.

Vanilla Integration & Fallback

Maestro integrates directly with Minecraft’s vanilla music system and preserves full compatibility with it. Vanilla music is always treated as part of the Underscore layer. If Maestro cannot find a matching music definition for the Underscore layer, it automatically falls back to vanilla music selection and lets Minecraft choose the appropriate track.

This means:

Vanilla biome and dimension music continues to work as expected
Mods that rely on the vanilla music system remain fully compatible
Maestro only takes control where custom definitions are explicitly provided

Encounter music never pulls from vanilla sources and is handled exclusively through Maestro definitions. As soon as a Maestro Underscore definition becomes applicable again, it smoothly takes over from vanilla playback without breaking musical continuity.

Sounds

Audio Format

Minecraft plays sounds using the OGG audio format. Maestro does not introduce a custom audio system – it works entirely on top of vanilla Minecraft sound handling.

Any audio file (.mp3, .wav, .flac, etc.) must be converted to .ogg. Once converted, Maestro treats the sound exactly like a vanilla music track.

Converting Audio to OGG

You can convert audio files using tools like:

Audacity (free, cross-platform)
ffmpeg
any audio editor capable of exporting .ogg

Basic Audacity workflow:

Open your audio file
File -> Export Audio -> Format: Ogg Vorbis Files
Use default settings (they are sufficient)
Save the file under assets/<namespace>/sounds/

Registering Sounds

Before Maestro can reference a track, it must be registered as a vanilla sound event using the standard sounds.json file.

Maestro references sound events, not raw audio files. sounds.json assigns a sound event ID to one or more .ogg files, which Maestro then uses in music definitions.

Example: sounds.json

  
{
  "music.biome.frozen_ocean": {
    "sounds": [
      {
        "name": "my_namespace:my_audio_file",
        "stream": true
      }
    ]
  },
  "music.boss.captain_cornelia": {
    "sounds": [
      {
        "name": "my_namespace:other_audio_file",
        "stream": true
      }
    ]
  }
}

This registers the following files:

assets/my_namespace/sounds/my_audio_file.ogg
assets/my_namespace/sounds/other_audio_file.ogg

and exposes them as sound events:

my_namespace:music.biome.frozen_ocean
my_namespace:music.boss.captain_cornelia

Multiple Files per Sound Event

A single sound event can reference multiple audio files.

If multiple sounds are registered under the same ID, Minecraft will randomly choose one each time the track starts. This is useful for adding subtle variation without additional logic.

Why stream: true?

Music tracks should always be registered with "stream": true.

Streaming tells Minecraft to:

Load the audio gradually instead of fully into memory
Avoid memory spikes for long tracks
Behave consistently with vanilla music playback

Short sound effects usually do not need streaming – music does.

Naming Conventions

Use clear, self-describing sound event names:

✅ music.biome.frozen_ocean
✅ music.boss.captain_cornelia
❌ track1
❌ some_music

Good naming makes music definitions easier to read, debug, and maintain.

Music Definitions

Music definitions describe what music should play and under which in-game conditions. Each definition is evaluated dynamically, and the one with the highest priority that matches the current game state is selected.

Basic Definition

  
{
  "priority": 0,
  "layer": "underscore",
  "sound_event": "minecraft:music_disc.pigstep",
  "cooldown_seconds": 0,
  "occupy_layer_during_cooldown": true,
  "reset_cooldown_on_reactivation": false,
  "condition": {
    "type": "maestro:always"
  }
}

Field	Type	Description
`priority`	Inreger	Determines priority within the same layer. Higher values take precedence over lower ones.
`layer`	Enum Value	Target music layer. Supported values: `underscore`, `encounter`.
`sound_event`	Identifier	Reference to a sound event (`namespace:path`).
`cooldown_seconds`	Integer (Optional)	Time after the track finishes playing naturally before it can play again (in seconds). Defaults to `0`
`occupy_layer_during_cooldown`	Boolean (Optional)	Keeps the track valid during cooldown, occupying the layer with silence. Defaults to `true`
`reset_cooldown_on_reactivation`	Boolean (Optional)	Resets the cooldown when the track becomes valid again after its condition was false. Defaults to `false`
`condition`	Condition	Defines when this music definition is considered valid.

Note
reset_cooldown_on_reactivation only works when occupy_layer_during_cooldown is enabled. If disabled, the track is not selected during cooldown, so it cannot be re-selected and the cooldown will never reset.

Example: Biome & Weather Based Definition

  
{
  "priority": 100,
  "layer": "underscore",
  "sound_event": "my_namespace:music.blizzard",
  "condition": {
    "type": "maestro:all_of",
    "terms": [
      {
        "type": "maestro:biome",
        "values": [ 
          "minecraft:snowy_beach",
          "minecraft:frozen_ocean" 
        ]
      },
      {
        "type": "maestro:weather",
        "is_snowing": true
      }
    ]
  }
}

This definition plays the custom blizzard music track when the player is located in either the Snowy Beach or Frozen Ocean biome and it is currently snowing.

Music Conditions

Conditions define which game state a music definition applies to. They are evaluated dynamically and can be combined using logical operators to describe complex scenarios.

Constants

Always

Always evaluates to true.

This condition is useful for:

global or fallback music,
testing and debugging,
base background layers.

  
"condition": {
  "type": "maestro:always"
}

Never

Always evaluates to false.

This condition is mainly useful for:

temporarily disabling a definition,
placeholders in resource packs,
debugging priority or condition logic.

  
"condition": {
  "type": "maestro:never"
}

World & Environment

Dimension

Checks whether the player is currently in one of the specified dimensions.

  
"condition": {
  "type": "maestro:dimension",
  "values": [
    "minecraft:overworld"
  ]
}

Field	Type	Description
`values`	Array[Identifier]	A list of dimension IDs that are allowed.

Biome

Checks whether the player is currently in one of the specified biomes.

  
"condition": {
  "type": "maestro:biome",
  "values": [
    "minecraft:plains",
    "minecraft:ocean"
  ]
}

Field	Type	Description
`values`	Array[Identifier]	A list of biome IDs that are allowed.

Biome Tag

Checks whether the player is currently in one of the specified biomes.

  
"condition": {
  "type": "maestro:biome_tag",
  "values": [
    "c:is_desert",
    "c:is_mesa"
  ]
}

Field	Type	Description
`values`	Array[TagKey]	A list of biome tags that are allowed.

Weather

Evaluates the current weather state at the player’s position.

  
"condition": {
  "type": "maestro:weather",
  "is_raining": true,
  "is_snowing": true,
  "is_sandstorm": true,
  "is_trundering": true
}

Field	Type	Description
`is_raining`	Boolean (Optional)	Requires the weather to match the specified rain state.
`is_snowing`	Boolean (Optional)	Requires the weather to match the specified snow state.
`is_sandstorm`	Boolean (Optional)	Requires the weather to match the specified sandstorm state.
`is_thundering`	Boolean (Optional)	Requires the weather to match the specified thunder state.

Note
is_thundering is typically used together with one of the precipitation flags to detect a more intensified version of a weather state (e.g., a thunderstorm instead of regular rain). If used alone, it will return true whenever a thunderstorm is active in the world, even if there is no precipitation at the player’s position (for example, in deserts).

Day Cycle

Evaluates the current phase of the in-game day based on world time.

  
"condition": {
  "type": "maestro:day_cycle",
  "is_day": true,
  "is_night": true,
  "is_sunrise": true,
  "is_sunset": true
}

Field	Type	Description
`is_day`	Boolean (Optional)	Matches daytime (ticks `0-12000`).
`is_night`	Boolean (Optional)	Matches nighttime (ticks `13000-23000`).
`is_sunrise`	Boolean (Optional)	Matches sunrise transition (ticks `23000-24000`).
`is_sunset`	Boolean (Optional)	Matches sunset transition (ticks `12000-13000`).

Time

Evaluates the current in-game time of day using numeric tick thresholds (0–24000).

  
"condition": {
  "type": "maestro:time",
  "above": 12000,
  "below": 13000
}

Field	Type	Description
`above`	Integer (Optional)	Requires the world time to be greater than this value.
`below`	Integer (Optional)	Requires the world time to be less than this value.

Height

Evaluates the player’s current Y level against numeric thresholds.

  
"condition": {
  "type": "maestro:height",
  "above": 0,
  "below": 60
}

Field	Type	Description
`above`	Integer (Optional)	Requires the player’s Y level to be above this value.
`below`	Integer (Optional)	Requires the player’s Y level to be below this value.

Player & Entities

Entity

Checks for the presence of one or more specific entities within a cubic area centered on the player.

  
"condition": {
  "type": "maestro:entity",
  "required_amount": 1,
  "search_radius": 64,
  "values": [
    "minecraft:wither",
    "minecraft:ender_dragon"
  ]
}

Field	Type	Description
`required_amount`	Integer (Optional)	Minimum number of matching entities required. Defaults to `1`.
`search_radius`	Integer (Optional)	Radius of the cubic detection area centered on the player. Defaults to `64`.
`values`	Array[Identifier]	A list of entity IDs that are allowed.

Entity Tag

Checks for the presence of one or more specific entities within a cubic area centered on the player.

  
"condition": {
  "type": "maestro:entity_tag",
  "required_amount": 1,
  "search_radius": 64,
  "values": [
    "c:bosses"
  ]
}

Field	Type	Description
`required_amount`	Integer (Optional)	Minimum number of matching entities required. Defaults to `1`.
`search_radius`	Integer (Optional)	Radius of the cubic detection area centered on the player. Defaults to `64`.
`values`	Array[TagKey]	A list of entity tags that are allowed.

Vehicle

Checks the player’s current vehicle (the entity they are riding).

Leave values empty to match any vehicle.

  
"condition": {
  "type": "maestro:vehicle",
  "values": [
    "minecraft:horse",
    "minecraft:donkey"
  ]
}

Field	Type	Description
`values`	Array[Identifier]	A list of entity IDs that are allowed.

Screen

Checks whether a specific GUI screen is currently open.

  
"condition": {
  "type": "maestro:screen",
  "kind": "title",
  "class_path": "net.minecraft.client.gui.screens.TitleScreen"
}

Field	Type	Description
`kind`	Enum Value (Optional)	If present, checks the current screen against a predefined category: `title`, `credits`, `inventory`, or `pause`.
`class_path`	String (Optional)	If present, checks whether the current screen is an instance of the specified class. This is an advanced option – use only if you know exactly what you are doing.