ShetcanWilly's Battle Music

ShetcanWilly's Battle Music 1.4

This turned into a much bigger update than I originally planned.

The addon used to be pretty simple: combat starts, it figures out whether you're fighting a normal mob, elite, or boss, and plays music from that pool.

It can now react to a lot more situations and use much more specific music when appropriate.

WHAT'S NEW

- Added proper dungeon and raid encounter detection.
- Boss fights can now tell the difference between a kill and a wipe.
- Boss music no longer depends only on whatever you happened to target when combat started.
- Added optional wipe audio.
- Added optional Death / Game Over music.
- Added a separate one-shot death sting that fires immediately when you die.
- Added separate music pools for:
  - Arena
  - Battlegrounds
  - World PvP
  - Mythic+
  - Pet Battles
  - Heavy combat
- Added boss-specific music using encounter IDs.
- Added instance-specific music overrides.
- Added difficulty-specific music overrides.
- Added zone/map-specific music overrides.
- Added optional Pet Battle win/loss sounds.
- Added MP3 and OGG support for generated playlists.
- Added named tracks, so music no longer has to be named 1.mp3, 2.mp3, 3.mp3, etc.
- Added Random, Shuffle Bag, Sequential, and Fixed-track playback modes.
- Expanded the settings menu for the new systems.
- Added library/context/debug commands to make setup and testing easier.
- Empty optional music pools can now be set to 0 and will fall back instead of causing silence.
- Added an HTML Track Builder for generating Tracks.lua without requiring BAT or PowerShell scripts.

The original General / Elite / Boss system is still there and acts as the normal fallback.

NAMED TRACKS

You can still use the old numbered format:

1.mp3
2.mp3
3.mp3

But you can now use normal filenames instead:

One Winged Angel.ogg
Rip and Tear.mp3
The Only Thing They Fear Is You.ogg
Whatever Else You Want.mp3

The addon uses the actual filename, not the MP3/OGG metadata.

MP3 and OGG files can be mixed in the generated playlists.

SCWBM TRACK BUILDER

Named tracks are handled through Tracks.lua.

The addon now includes:

SCWBM_Track_Builder.html
Tracks.lua

The Track Builder runs locally in your web browser. Nothing is uploaded anywhere.

The addon files stay in:

World of Warcraft\_retail_\Interface\AddOns\ShetcanWillys_BattleMusic\

Your actual music stays in:

World of Warcraft\_retail_\Interface\Music\Battles\SCWBM\

Any time you add, delete, move, or rename music:

1. Add/remove/rename your MP3 or OGG files.
2. Open SCWBM_Track_Builder.html.
3. Select your SCWBM music folder when prompted.
4. The builder scans the supported music folders.
5. Generate/download the new Tracks.lua.
6. Replace the Tracks.lua inside:

   Interface\AddOns\ShetcanWillys_BattleMusic\

7. Go back into WoW and /reload.

You do NOT have to manually type all of your song names into Tracks.lua.

The builder reads the filenames and creates the list for you.

IMPORTANT - TRACKS.LUA

Tracks.lua is generated from YOUR music library.

A fresh addon download contains its own default/blank Tracks.lua because everybody's music library is different.

If you completely replace the addon folder during an update, your generated Tracks.lua may also be replaced.

If the addon suddenly starts showing:

Track 1
Track 16
Track 42

instead of:

One Winged Angel
Rip and Tear
Whatever Else You Named It

your music files are fine.

Just open SCWBM_Track_Builder.html, scan your music folder again, generate a new Tracks.lua, put it back in the addon folder, and /reload.

FOLDER STRUCTURE

Your external music folder can now look like this:

Interface\
└─ Music\
   └─ Battles\
      └─ SCWBM\
         │
         ├─ General music goes directly here
         │
         ├─ Elite\
         │
         ├─ Boss\
         │  └─ Encounters\
         │     └─ <encounterID>\
         │
         ├─ Heavy\
         ├─ MythicPlus\
         ├─ Death\
         ├─ PetBattle\
         │
         ├─ PvP\
         │  ├─ Arena\
         │  ├─ Battleground\
         │  └─ World\
         │
         ├─ Instances\
         │  └─ <instanceID>\
         │
         ├─ Difficulties\
         │  └─ <difficultyID>\
         │
         ├─ Zones\
         │  └─ <mapID>\
         │
         ├─ sting.mp3
         ├─ scratch.mp3
         ├─ end.mp3
         ├─ win.mp3
         ├─ wipe.mp3
         ├─ deathsting.mp3
         ├─ petwin.mp3
         └─ petloss.mp3

You do NOT need to create every folder.

Only create folders for features you actually want to use.

OPTIONAL POOLS AND FALLBACKS

Optional music pools can now have 0 tracks.

Having a feature available does not mean you have to create music for it.

For example, if you fight a boss but have no Boss music configured, the addon will not simply go silent.

The fallback behavior is:

Boss = 0
-> try Elite
-> if Elite is also empty, use General

Elite = 0
-> use General

Heavy = 0
-> use General

Arena = 0
-> use General

Battleground = 0
-> use General

World PvP = 0
-> use General

Mythic+ = 0
-> use General

Pet Battle = 0
-> use General

Death = 0
-> no Death music

Death is intentionally different. If you don't configure Death music, the addon won't start playing normal battle music while you're dead.

This means the additional music pools are actually optional.

You can use one, all, or none of them.

DEATH MUSIC / DEATH STING

These are two separate things.

deathsting.mp3 goes directly in:

SCWBM\deathsting.mp3

That is a short one-shot sound that fires immediately when you die.

The actual music played while dead goes in:

SCWBM\Death\

Example:

SCWBM\deathsting.mp3
SCWBM\Death\Final Fantasy Game Over.ogg
SCWBM\Death\Another Death Theme.mp3

The sequence is basically:

You die
-> deathsting.mp3 plays once
-> Death playlist starts
-> you resurrect
-> Death music stops

If the Death playlist is empty, the death sting can still play without starting a Death music playlist afterward.

SPECIAL CUE FILES

These are treated as one-shot cues and are not added to the normal General playlist:

sting.mp3
scratch.mp3
end.mp3
win.mp3
wipe.mp3
deathsting.mp3
petwin.mp3
petloss.mp3

The Track Builder filters these out so they don't accidentally get counted as regular General combat music.

BOSS-SPECIFIC MUSIC

Specific dungeon/raid encounters can have their own music.

Example:

SCWBM\Boss\Encounters\3012\One Winged Angel.ogg
SCWBM\Boss\Encounters\3012\Jenova Theme.mp3

If encounter 3012 starts, the addon will try that encounter's music first.

If nothing is configured there, it falls back instead of leaving you with no music.

Use:

/scwbm context

to see encounter ID, instance ID, difficulty ID, map information, and other useful information while setting up overrides.

OVERRIDE PRIORITY

The addon generally prefers the most specific music available:

Specific Encounter
-> Specific Instance
-> Specific Difficulty
-> Specific Zone
-> Normal Pool

If the more specific library is empty or unavailable, the addon continues through its fallback logic instead of intentionally selecting an empty playlist.

This means you can keep your normal setup simple and only create special overrides where you actually want them.

PLAYBACK MODES

Random

Similar to the original behavior, with recent-repeat protection.

Shuffle Bag

Plays every track in the current pool once before the bag resets.

This is useful for larger libraries because it prevents the RNG from playing the same few songs over and over.

Sequential

Plays through the library in order.

Fixed

Always uses one selected track.

Useful for testing or if you want one specific song for a particular pool.

SETTINGS CHANGES

The settings menu has been expanded for the new music pools and options.

Editable number boxes were removed where possible because they were not consistently retaining their values across reloads/restarts.

Numeric settings now use sliders with visible values.

Examples include:

- Volume
- Low-health threshold
- Fade duration
- Combat-end grace
- Heavy-combat threshold
- History size
- Manual cooldown

Legacy/manual track-count sliders can now be set to 0.

0 means that pool is not configured and the addon should use its normal fallback behavior.

When using generated named playlists, track counts are read automatically from Tracks.lua instead of requiring you to manually enter how many songs you have.

For example:

General: 56 detected
Elite: 0 detected
Boss: 0 detected
Death: 4 detected

If Boss is 0, that does NOT mean boss fights will be silent. The addon will fall back to another appropriate pool.

COMMANDS

/scwbm context

Shows current encounter, instance, difficulty, zone/map, and activity information.

/scwbm library

Shows the music and cue counts currently loaded by WoW.

This is also useful for checking whether your newly generated Tracks.lua loaded correctly.

/scwbm status

Shows the current addon/music state.

There are also test commands for the individual music pools.

EXISTING FEATURES KEPT

The update still keeps the original systems, including:

- General combat music
- Elite combat music
- Boss combat music
- One-track-per-combat latch
- Manual skip behavior
- NUMPAD+ skip binding
- Combat-start sting
- Victory fanfare
- Combat-end cue
- Low-health volume ducking
- Stealth volume ducking
- Fade in/out
- Separate General / Elite / Boss volume controls
- Spec folders
- Recent-track history
- Combat-end anti-flicker delay
- External music library support
- Debug path output

OTHER CLEANUP

- Improved encounter state handling.
- Improved death/resurrection handling.
- Improved PvP context handling.
- Improved Mythic+ handling.
- Improved Pet Battle start/end handling.
- Improved music fallback logic.
- Empty optional pools no longer cause silence.
- Track-count settings can now use 0 where appropriate.
- Special cue files are kept separate from normal playlists.
- Named playlists use the actual filenames generated in Tracks.lua.
- Track generation understands the expanded folder structure.
- Added automatic detection/counting of generated named-track libraries.
- Reworked numeric settings away from unreliable editable number boxes.
- Added a browser-based Track Builder so named playlists don't require executable updater scripts.
- Various cleanup and compatibility fixes.

BASIC SETUP

If you only want the original behavior, you can still keep everything simple:

SCWBM\
├─ General songs here
├─ Elite\
└─ Boss\

You don't even need to put anything in Elite or Boss if you don't want to.

An empty optional pool will fall back appropriately.

If you're using named tracks:

1. Open SCWBM_Track_Builder.html.
2. Select the SCWBM music folder.
3. Generate Tracks.lua.
4. Put Tracks.lua in the addon folder.
5. /reload

That's it.

ADVANCED SETUP

If you want the newer features, add whichever folders you actually want:

Death\
Heavy\
MythicPlus\
PetBattle\
PvP\Arena\
PvP\Battleground\
PvP\World\
Boss\Encounters\<encounterID>\
Instances\<instanceID>\
Difficulties\<difficultyID>\
Zones\<mapID>\

You do not have to use all of them.

After changing your music library:

1. Open SCWBM_Track_Builder.html.
2. Scan the SCWBM music folder.
3. Generate the new Tracks.lua.
4. Replace Tracks.lua in the addon folder.
5. /reload.

There's a lot more available now, but every additional system is optional.

If all you want is a folder full of battle music that starts when combat begins, you can still use the addon that way.

If you want different music for bosses, PvP, Mythic+, individual encounters, specific instances, death, Pet Battles, or certain zones, you can go as far down that rabbit hole as you want.