BTW Music Player

BTW Music Player is a dynamic music engine created as an addon for the Better Than Wolves Community Edition 3.0.0 mod for Minecraft 1.6.4. It replaces the standard, repetitive in-game music, allowing for custom tracks to be played based on the gameplay context.

Players can create and install their own "Music Packs" containing music files and a songs.json file that defines when each track should be played. The mod features smooth transitions between songs and intelligently manages combat music, reacting to actions from both the player and monsters.

Features

• Full Music Customization: Replace the entire game's soundtrack with your own .ogg files.
• Smart Playlist Logic: Tracks are shuffled globally at launch (like a deck of cards). The mod ensures every song for a specific context plays at least once before looping. The playback state is remembered even if you leave and return to an area, preventing repetitive music and ensuring you hear your entire library.
• Smooth Transitions: Music gently fades in and out when the context changes, eliminating abrupt cuts.
• Intelligent Combat System: Combat music is triggered not only when the player is attacked but also when they initiate a fight. The system sustains the combat theme as long as a threat is nearby.
• Context-Aware Playback: Define music playback rules based on a wide range of conditions:
  • Dimension: Overworld, Nether, The End.
  • Time of Day: Day or night.
  • Biome: Any biome in the game (e.g., Forest, Desert, Taiga).
  • Weather: Clear skies or a storm.
  • Location: Play different music on the surface versus in caves.
  • Combat: Dedicated music for encounters with monsters, wolves, or squids.
  • Boss Battles: Unique tracks for fights against the Ender Dragon and the Wither.
  • Victory: A special theme plays after defeating a boss.
  • Menu Music: Define tracks to play in the Main Menu, World Selection screen, and options when outside of the game world.
  • Low Health Overlay: A heartbeat sound effect (or any other sound) plays simultaneously with the background music when the player's health drops to 5 hearts or below.
• Smart Biome Logic: Biome variants (e.g., Forest Hills, Desert Hills) are automatically treated as their main biome, simplifying configuration.
• Seamless Travel: Rivers and Beaches are considered "transparent". The music from the previous biome (e.g., Forest) continues to play while crossing a river, preventing constant music switching.
• Advanced Validator: The mod checks if your .ogg files exist and are valid, reporting errors directly in the Music Pack selection menu.
• Multi-Music Pack Support: Load tracks from a single, specific music pack or from all installed packs at once.
• In-Game Configuration: Manage settings, select music packs, and open the music folder directly from the game options menu via a new gear icon.
• Global Condition Toggles: Enable or disable specific conditions (e.g., disable all Biome music or Combat music) directly from the in-game configuration menu.
• Diagnostics Commands: Use /bmp debug to view the current music state (biome, combat, song priority) in real-time, and /bmp reload to reload configuration and music packs without restarting the game.
• Now Playing Notifications: A stylish pop-up appears on the right side of the screen when a new song starts, displaying the track title and the name of the Music Pack.
• Custom Song Titles: You can now define a custom display title for each song in the songs.json file.

Downloads

• BTW Music Player Mod: Click the green download buuton!
• Sample Music Pack (RadogostMusicPack.zip): Download Music Pack
• Source Code: Browse on GitHub

Requirements

• Better Than Wolves Community Edition 3.0.0 installed

Mod Installation

1. Download the latest .jar file for the mod from the Downloads section.
2. Open your Minecraft directory.
3. In your .minecraft directory, find the mods folder.
4. Move the downloaded btw-music-player-x.y.z.jar file into the mods folder.
5. Launch the game.

Music Pack Installation

After successfully installing the mod, you can add any number of music packs to customize the in-game music.

1. Download a music pack (e.g., RadogostMusicPack.zip) from the Downloads section.
2. Navigate to your main Minecraft game directory (.minecraft).
3. In the .minecraft directory, find a folder named musicpacks. If it does not exist, you must create it.
4. Unzip the downloaded .zip archive. Inside, you will find a folder with the music pack's name (e.g., RadogostMusicPack).
5. Important: Move the entire folder (e.g., RadogostMusicPack) into the musicpacks directory. Do not copy individual .ogg files or the songs.json file directly.

After restarting the game, the music packs will be loaded automatically according to the settings in the configuration file.

Example Folder Structure

This is what your file structure should look like after installing the mod and two example music packs (RadogostMusicPack and AnotherCoolMusicPack):

.minecraft/
├── mods/
│   ├── btwce-3.0.x.jar
│   └── btw-music-player-x.y.z.jar
│
├── musicpacks/
│   ├── RadogostMusicPack/
│   │   ├── songs.json
│   │   ├── day/
│   │   │   └── kam_01_spirit.ogg
│   │   └── combat/
│   │       └── witcher_52_monster_battle.ogg
│   │
│   └── AnotherCoolMusicPack/
│       ├── songs.json
│       └── ... (music files)
│
└── ... (other minecraft files and folders)``````

---

Configuration

You can configure the mod directly inside the game!

1. Go to Options.
2. Look for the Music slider.
3. Click the small Gear Icon next to the slider.

This menu allows you to:

• Browse and validate installed Music Packs (Green = Valid, Red = Missing files or Invalid format).
• Manage Active Conditions: Open the Song Conditions screen to globally enable or disable specific rules (e.g., turn off all Biome checks).
• Toggle between ALL (load all packs) and SINGLE (load one specific pack) modes.
• Adjust the Context Delay, Crossfade (fade duration), and Cave Depth sliders.
• Toggle Debug Logging.
• Quickly open the musicpacks folder on your computer using the Open Folder button.

Alternatively, you can edit the configuration file manually at .minecraft/config/btw-music-player.cfg.

Available Options

• musicpack_loading_mode
  • Description: Determines how the mod should load music packs.
  • Values:
    • ALL (default) - The mod loads music from all music packs found in the musicpacks folder.
    • SINGLE - The mod loads music from only one specific music pack.
  • Example: To use only one music pack, change this value to SINGLE.
• single_musicpack_name
  • Description: The name of the music pack to be activated when musicpack_loading_mode is set to SINGLE.
  • Values: The exact name of the music pack folder (e.g., RadogostMusicPack). This is case-sensitive.
  • Example: single_musicpack_name=RadogostMusicPack
• enable_debug_logging
  • Description: Enables or disables detailed mod messages in the game console. This is useful for diagnosing issues or when creating your own music pack.
  • Values:
    • false (default) - Logging is disabled.
    • true - Logging is enabled.
• context_change_delay_seconds
  • Description: Sets a delay (in seconds) that must pass before the music changes after the game context (e.g., biome, entering a cave) is altered. This prevents annoying, rapid music switching when moving between areas. High-priority music (combat, boss battles) will always play immediately, ignoring this delay.
  • Values:
    • 7 (default) - Music will change after the new context has been stable for 7 seconds.
    • 0 - Music changes are immediate.
• fade_duration_ms
  • Description: Sets the duration (in milliseconds) of the crossfade effect when music changes.
  • Values:
    • 1000 (default) - 1 second fade.
    • 0 - Instant cut with no fading.
• cave_y_level
  • Description: Specifies the Y coordinate (height) below which the game considers the player to be in a "cave". This affects the is_in_cave condition.
  • Values:
    • 60 (default) - Standard sea level/underground start.
• show_notifications
  • Description: Determines whether the "Now Playing" pop-up should appear when the music changes.
  • Values: true (default), false.

Creating Your Own Music Pack

Anyone can create their own music pack! The process involves preparing your music files in .ogg format and defining playback rules in a special file called songs.json.

0. Important Tip: Volume Normalization

Before you begin, we strongly recommend normalizing the volume for all your tracks. This will prevent situations where one track is too quiet and the next is too loud, forcing you to constantly adjust the in-game music slider.

You can do this using a free program like Audacity. For my music pack, I used the "Normalize" effect to a perceived loudness of -22 LUFS. This step ensures a professional and consistent listening experience.

1. Folder Structure

First, create a main folder for your music pack, e.g., MyFirstMusicPack. Inside it, you must place the songs.json file. You can place your music files alongside it or, for better organization, group them into subfolders (e.g., music, combat, boss).

musicpacks/
  └── MyFirstMusicPack/
      ├── songs.json
      ├── ambient/
      │   ├── day_forest.ogg
      │   └── night_plains.ogg
      └── combat/
          └── regular_fight.ogg

2. The songs.json File

This is the heart of your music pack. It's a text file containing a list of "rules" that tell the mod when to play a specific track. Each rule consists of four parts:

• file: The path to the music file.
• title (Optional): The display name of the song shown in notifications.
• priority: A number that determines how important the track is.
• conditions: A set of conditions that must be met for the track to be played.

Here is an example songs.json file with two rules:

[
  {
    "file": "ambient/day_forest.ogg",
    "title": "Spirit of the Woods",
    "priority": 10,
    "conditions": {
      "dimension": "overworld",
      "time_of_day": "day",
      "biome": "forest"
    }
  },
  {
    "file": "combat/regular_fight.ogg",
    "priority": 100,
    "conditions": {
      "is_in_combat": true
    }
  }
]

3. Priority

Priority decides which playlist takes precedence if more than one rule's conditions are met at the same time. The rule with the highest priority number wins.

Example: You are in a forest during the day (matching the rule with priority: 10), but a zombie suddenly attacks you (also matching the combat rule with priority: 100). Since 100 is greater than 10, the music will immediately switch to the combat track. Tip: Use low priorities (e.g., 1-20) for general background music (biomes, time of day) and high priorities (e.g., 100+) for special events like combat, boss battles, or victory themes.

4. Available Conditions

The following table lists all the conditions you can use in the conditions section to define your rules.

Condition Key	Accepted Values	Description
dimension	overworld, the_nether, the_end	Specifies the dimension the player must be in.
biome	ocean, plains, desert, extreme_hills, forest, taiga, swampland, hell, sky, frozenocean, ice_plains, ice_mountains, mushroomisland, jungle	Specifies the biome. Note: Hills (e.g., forest_hills), edges, and shores are automatically mapped to their parent biome (use forest, desert, etc.). Rivers and Beaches are ignored to maintain the previous track and cannot be targeted directly.
time_of_day	day, night	Specifies the current time of day in the game.
weather	clear, storm	Checks if the weather is calm or if there is a storm.
is_in_cave	true, false	Checks if the player is below the configured Y level (Default: 60).
is_in_combat	true, false	Checks if the player is currently in combat.
boss_type	wither, ender_dragon	Checks if a specific boss is nearby
victory_after_boss	true	A special condition that is true for a short time after defeating a boss.
is_menu	true	Checks if the player is in the Main Menu or any screen outside of the active world (e.g., World Selection).
is_low_health	true, false	Checks if the player has 5 hearts (10 HP) or less. This tracks plays as an overlay on top of current music.

5. Tips and Tools

• File Format: Ensure all your music files are in the .ogg format.
• Use Diagnostics: You can use the in-game command /bmp debug to see exactly why a specific song is playing (or why it isn't). It displays the current biome, combat status, and active song priority.
• Use Logs: For deeper analysis, enable enable_debug_logging=true in the config. The game console will show detailed traces of what the mod is trying to do.
• JSON Validator: If the game isn't loading your music pack, make sure your songs.json file is free of syntax errors. You can check it by pasting its content into an online JSON validator.
• Managing Large Music Packs (CSV to JSON): If you plan to add dozens or hundreds of tracks, editing the songs.json file by hand becomes tedious. In this case, you can prepare a simple spreadsheet with columns in the following order: file,priority,dimension,biome,time_of_day,is_in_combat,weather,is_in_cave,boss_type,victory_after_boss,is_menu,is_low_health

Save the spreadsheet as a .csv file, and then use my helper tool, which will automatically convert it into a ready-to-use songs.json file.

• Download the tool: BTW Music Player CSV to JSON
• Detailed instructions on how to use the tool are available in its repository.