so many bugs i cannot even breathe

src/core/ChipAudio.lua

@@ -55,6 +55,14 @@ local currentMusic
 local pendingBuf -- a current-gen buffer popped from the worker but not yet
                  -- queued because the Source was momentarily full
 
+-- Music holds playback while a fanfare owns the music channels (#398).
+-- Pausing the Source is not enough on its own: this module is what starts a
+-- chip song (immediately on the sync path, on the first worker buffer on the
+-- threaded one), so a song that begins during a jingle would come up
+-- underneath it.  Music.duckForFanfare sets the hold, Music releases it when
+-- the jingle ends.
+local musicHeld = false
+
 -- ---------------------------------------------------------------------------
 -- worker management
 -- ---------------------------------------------------------------------------
@@ -148,7 +156,7 @@ local function playMusicSync(data, header, allowLoops)
   currentMusic = { source = source, engine = engine, threaded = false,
                    started = true, finished = false }
   fillSync(MUSIC_FILL_INITIAL)
-  source:play()
+  if not musicHeld then source:play() end
   return source
 end
 
@@ -222,7 +230,7 @@ local function updateThreaded()
       end
     end
   end
-  if not m.started then
+  if not m.started and not musicHeld then
     if (MUSIC_BUFFER_COUNT - m.source:getFreeBufferCount()) > 0 then
       pcall(function() m.source:play() end)
       m.started = true
@@ -245,7 +253,7 @@ end
 -- pause/resume behavior.
 function ChipAudio.ensureMusicPlaying()
   local m = currentMusic
-  if not m or m.finished then return end
+  if not m or m.finished or musicHeld then return end
   if m.threaded then
     if not m.started then return end
     local ok, playing = pcall(function() return m.source:isPlaying() end)
@@ -263,6 +271,18 @@ function ChipAudio.ensureMusicPlaying()
   end
 end
 
+-- Silence the song for the length of a fanfare and start whatever was held
+-- back once it ends.  Held state outlives a song change: Music.play may swap
+-- songs while the jingle is still sounding.
+function ChipAudio.holdMusic(held)
+  held = not not held
+  if held == musicHeld then return end
+  musicHeld = held
+  if held then return end
+  ChipAudio.update()
+  ChipAudio.ensureMusicPlaying()
+end
+
 -- Threaded playMusic returns an empty QueueableSource and only calls
 -- Source:play once the first worker buffer lands (~1 frame later).  Until
 -- then Source:isPlaying is false -- callers that treat that as "song over"
@@ -303,6 +323,17 @@ function ChipAudio.invalidate()
   if workerReady and cmdCh then cmdCh:push({ cmd = "invalidate" }) end
 end
 
+-- End the worker thread.  LOVE waits for every live love.thread before the
+-- process exits and the worker's command loop only returns on "quit", so
+-- skipping this leaves the process running after the window is gone (#339).
+function ChipAudio.shutdown()
+  ChipAudio.stopMusic()
+  if workerReady and cmdCh then cmdCh:push({ cmd = "quit" }) end
+  if worker then pcall(function() worker:wait() end) end
+  worker, cmdCh, outCh = nil, nil, nil
+  workerReady = false
+end
+
 -- Runtime mix for one hardware channel (1..4).  Takes effect on the next
 -- synthesized buffer (live music) and on any SFX/cry rendered after the call.
 function ChipAudio.setChannelVolume(hw, scale)

src/core/Music.lua

@@ -85,6 +85,7 @@ local function fanfareActive()
   local ok, playing = pcall(src.isPlaying, src)
   if ok and playing then return true end
   state.fanfare = nil
+  require("src.core.ChipAudio").holdMusic(false)
   return false
 end
 
@@ -94,6 +95,9 @@ end
 function Music.duckForFanfare(src)
   if not src then return end
   state.fanfare = src
+  -- ChipAudio is what starts a chip song, so the pause below cannot hold one
+  -- that has not started yet (nor one Music.play swaps in mid-jingle) (#398)
+  require("src.core.ChipAudio").holdMusic(true)
   if state.source then
     local ok, playing = pcall(state.source.isPlaying, state.source)
     if ok and playing then

src/core/Sound.lua

@@ -111,6 +111,9 @@ local function played(kind, name, species)
   Runtime.emit("sound.played", { kind = kind, name = name, species = species })
 end
 
+-- returns the started source (nil headless, or when the def failed to load)
+-- so callers that block on a fanfare like the original's
+-- PlaySoundWaitForCurrent -> WaitForSoundToFinish can poll it
 function Sound.play(data, name)
   local sfx = data.audio and data.audio.sfx
   local def = sfx and sfx[name]
@@ -120,6 +123,7 @@ function Sound.play(data, name)
     require("src.core.Music").duckForFanfare(src)
   end
   played("sfx", name)
+  return src
 end
 
 -- Play a move's sound with its MoveSoundTable pitch/tempo modifiers