BOSS JUKEBOX
============

Plays a custom music track (chosen or randomized) whenever a boss encounter starts in a dungeon or raid, stops it when the encounter ends, and can play a one-shot victory sound when the boss actually dies (not on a wipe).

INSTALL
-------
1. Copy this whole "BossJukebox" folder into: World of Warcraft\_retail_\Interface\AddOns\
2. Make sure the folder is named exactly "BossJukebox" (or update ADDON_FOLDER at the top of Tracks.lua to match whatever you rename it to).
3. Launch WoW, make sure the addon is enabled on the character select / addon list screen.

ADDING YOUR OWN MUSIC AND VICTORY SOUNDS
------------------------------------------
This addon includes the author's favorite audio files, but you can also supply your own. WoW addons can't scan a folder's contents while the game is running (no filesystem access from in-game Lua), so the track list has to be built outside the game -- either by running the included script, or by hand.

Boss Music tracks and Victory Sound stingers live in two different places so the generator script can tell them apart automatically:
- Boss Music -> Sounds\
- Victory Sound -> Sounds\Victory\

Filenames only need to be unique within their own category -- a Boss Music track and a Victory Sound stinger can even share the same filename without conflict, since they end up in two separate lists
internally (BossJukebox.Tracks vs BossJukebox.VictoryTracks).

EASY WAY (recommended) - generate_tracks.py:
1. Convert your audio to .ogg (preferred) or .mp3.
2. Drop boss music into Sounds\, and victory stingers into Sounds\Victory\, e.g.:
BossJukebox\Sounds\Bowser_Fight.ogg
BossJukebox\Sounds\Victory\Level_Complete.ogg
The filename becomes the display name in-game (underscores/dashes become spaces), so name the file the way you want it to show up.
3. Open a terminal in the BossJukebox folder and run: python3 generate_tracks.py
(On Windows with the py launcher: py generate_tracks.py). This rewrites Tracks.lua for you, including each track's exact length, so long boss fights loop correctly. No ffmpeg, no pip installs, no extra tools needed -- it reads MP3/Ogg file headers directly with plain Python. It reports additions/removals for
each category separately.
4. /reload in-game (or relog).

DON'T HAVE PYTHON ON YOUR GAMING PC? Prebuilt Windows executable:
Download generate_tracks.exe here: https://mega.nz/file/NAdygbIR#RpQljtAEtBDC70W60kIszfGG1NNGxAGyimANivmcIg8
Drop it in this folder (next to Tracks.lua) and double-click it whenever you've added new files to Sounds\ or Sounds\Victory\. No Python needed.

ON A MAC INSTEAD? Prebuilt macOS binary:
Download generate_tracks here:
https://mega.nz/file/RNMWXChC#ji_idmM6xnfpeOZTuUin4WSNtRtqA-h5arQtDdRPDk8
Drop it in this folder and double-click it the same way. Since it isn't a signed/notarized app (and downloaded files get flagged by Gatekeeper even more reliably than locally-built ones), macOS will
very likely block the first run -- if so, right-click (Control-click) generate_tracks in Finder and choose Open once to approve it. You'll also need to make it executable the first time -- open Terminal, cd to this folder, and run: chmod +x generate_tracks

HAND-EDITING INSTEAD:
Open Tracks.lua -- boss music goes in the BossJukebox.Tracks table, victory sounds go in the BossJukebox.VictoryTracks table:
{ key = "mytrack", name = "My Track", file = "Sounds\\MyTrack.ogg", duration = 187 },
{ key = "mysting", name = "My Sting", file = "Sounds\\Victory\\MySting.ogg", duration = 6 },
- "key" must be unique within its own table (music and victory keys
don't need to differ from each other).
- "name" is what shows up in the options menu.
- "file" is the path inside the Sounds folder (note the Victory\\
subfolder for the second example).
- "duration" (seconds) controls looping for Boss Music -- see below.
Victory Sound never loops regardless of this field, since it's meant to play once.

Each track automatically appears in the options panel (under its matching Boss Music / Victory Sound tab), where you can include or exclude it from the random rotation, or pick it as your fixed "always play this" track.

LOOPING
--------
WoW's sound API has no native loop flag and no way to detect when an arbitrary audio file finishes playing. So if a Boss Music track is shorter than the boss fight, Boss Jukebox needs to know its exact
length (the "duration" field) to time a replay. generate_tracks.py fills this in automatically by reading the file's own header data. If a track has no duration set (rare -- usually means an unusual/corrupt encode), it'll just play once per pull instead of looping, and you'll get a one-time chat warning in-game reminding you.

Victory Sound stingers never loop, regardless of their duration -- they're designed to play exactly once per kill.

AUDIO CHANNEL
--------------
Tracks play on a WoW sound channel you can choose in the options panel ("Sound channel" dropdown, applies to both Boss Music and Victory Sound). This is a genuine tradeoff with no single right answer:

- "Dialog" -- default. Tested reliably in practice (its own dedicated channel, always audible regardless of
your music setting). In theory it could still clash with an actual NPC or boss voice line in some
encounters, but this hasn't been observed in testing so far.
- "Music" -- the other fully reliable channel (dedicated, never cut off by other sound effects), but it's fully silenced by WoW's own music on/off setting, so it's inaudible if you play with in-game music turned off.
- "Master"/"SFX"/"Ambience" -- always audible regardless of your music setting, but they share a limited pool of sound slots with every other sound effect in the game, so in a fight with a lot of simultaneous ability/spell sounds going off, the engine can occasionally cut your track off to make room for something else.

Default is "Dialog". If it ever does clash with a boss's own voice lines, or cuts out in some fight, try "Music" next (if you're willing to keep in-game music enabled), or "SFX"/"Ambience" as other always-audible alternatives. Blizzard's own encounter music is separately muted during the fight (via the "Mute Blizzard music during encounters" option) for players who keep game music on, regardless of which channel you pick, so the two don't overlap either way.

USING IT IN GAME
-----------------
- Options panel: type /bjb or /bossjukebox, or find "Boss Jukebox" under Options > AddOns in the game menu. Boss Music and Victory Sound each have their own tab, but both work the same way: the
track list is collapsed behind a "Show Tracks" button to keep the panel compact -- click it to check/uncheck tracks for the random rotation and preview them with the small speaker icon next to each one. There's also a "Stop Preview" button if you want to cut a preview off early. Preview just plays once -- it doesn't loop or duck game music the way real playback does.
- /bjb test - manually plays a boss music track right now, exactly as it would during a real encounter
(loops if the track has a duration, ducks game music, etc)
- /bjb testvictory - manually plays a victory sound right now
- /bjb stop - stops boss music AND any victory sound, and restores game music
- /bjb list - lists all configured tracks (both categories), their keys, and whether they're enabled
- /bjb preview <key> - previews a specific track by its key, from either category (see /bjb list)
- /bjb stoppreview - stops a preview started from the options window or slash command

VICTORY SOUND NOTES
---------------------
- Only fires on an actual kill (ENCOUNTER_END success), not on a wipe or reset.
- Has its own "Enable victory sound" checkbox in the Victory Sound tab, separate from the master "Enable Boss Jukebox" switch -- so you can run boss music without victory stings, or vice versa.
- Always plays once, never loops, regardless of the track's duration.
- If you haven't added any victory sounds yet, nothing plays and nothing is printed to chat -- it stays silent rather than nagging you on every kill.