feat(audio): per-board music with loudness-matched crossfade (#72)

Give the bonus and critters boards their own background loops and crossfade
between tracks on every level transition.

- bonus → corporate-glitch, critters → farm; home keeps Cipher2.
- Each Level carries a music basename + a loudness trim (music_gain). The trims
(0.349, 0.365) match each track to Cipher2's -19.74 LUFS (measured via EBU
R128) so nothing jumps in volume across a transition.
- Music is now a per-track voice pool (one <audio> + gain node each) feeding the
shared music bus; loadLevel crossfades by ramping the outgoing track to 0 and
the incoming up to its trim. Mixer slider, mute, and the glitch-board low-pass
still level every track together.

Verified with Playwright against the live Web Audio graph: home→bonus→critters
each select the right track, crossfade (both tracks overlap mid-fade), settle on
the exact trim, and park the outgoing voice; farm decodes and plays
(HAVE_ENOUGH_DATA); no console errors.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitattributes

@@ -1,2 +1,4 @@
 static/Cipher2.mp3 filter=lfs diff=lfs merge=lfs -text
+static/farm.mp3 filter=lfs diff=lfs merge=lfs -text
+static/corporate-glitch.mp3 filter=lfs diff=lfs merge=lfs -text
 docs/*.png filter=lfs diff=lfs merge=lfs -text

app.py

@@ -19,15 +19,31 @@ _SCRATCH = base64.b64encode((STATIC / "pencil-scratch.mp3").read_bytes()).decode
 # root so it still holds up inside the HF Spaces iframe.
 gr.set_static_paths(paths=[STATIC])
 
+# A static file streamed via the Gradio file route. game.js resolves the URL
+# against the Gradio root so it still holds up inside the HF Spaces iframe.
+def _file_route(name: str) -> str:
+    return "gradio_api/file=" + str(STATIC / name)
+
+
+# Each board may name its own background loop (Level.music, a static/ basename);
+# resolve those to file-route URLs here so the Level data stays path-agnostic.
+# Boards without one play the default loop (Cipher2). game.js crossfades between
+# tracks on transition; per-board music_gain keeps them at a matched loudness.
+def _level_client(lid: str) -> dict:
+    cv = LEVELS[lid].client_value()
+    cv["music"] = _file_route(cv["music"]) if cv["music"] else ""
+    return cv
+
+
 # Everything the board needs to render and switch levels client-side: the play
 # order, the boot board, each level's client-facing slice, the pen-scratch
-# sample (data URI), and the looping background-music URL (file route).
+# sample (data URI), and the default looping background-music URL (file route).
 GAME = {
-    "levels": [LEVELS[lid].client_value() for lid in LEVEL_ORDER],
+    "levels": [_level_client(lid) for lid in LEVEL_ORDER],
     "order": LEVEL_ORDER,
     "home": HOME_ID,
     "scratchAudio": "data:audio/mpeg;base64," + _SCRATCH,
-    "music": "gradio_api/file=" + str(STATIC / "Cipher2.mp3"),
+    "music": _file_route("Cipher2.mp3"),
 }
 
 HEAD = """

levels/_base.py

@@ -33,6 +33,12 @@ class Level:
     # negative; "?" becomes a shrink key and file tiles blow the context (see game.js)
     portal_to: str = ""  # if set, this board's portal tiles are a cross-level
     # link to that level id (instead of an in-board teleport)
+    music: str = ""  # basename of this board's background loop under static/
+    # (e.g. "farm.mp3"); "" plays the default loop. game.js crossfades between
+    # boards' tracks on transition.
+    music_gain: float = 1.0  # linear trim applied to this track so every board
+    # sits at the same loudness as the default loop (measured by EBU R128 / LUFS);
+    # nothing jumps in volume across a transition.
 
     def client_value(self) -> dict:
         """The subset shipped to the browser — no judge internals leave the server."""
@@ -46,4 +52,6 @@ class Level:
             "budget": self.budget,
             "glitch": self.glitch,
             "portal_to": self.portal_to,
+            "music": self.music,
+            "music_gain": self.music_gain,
         }

levels/animal.py

@@ -27,4 +27,6 @@ LEVEL = Level(
     budget=12,
     order=2,  # last: reached from the bonus board through the portal
     home=False,
+    music="farm.mp3",  # sweet-country-farm loop, fits the critters
+    music_gain=0.365,  # trim to match Cipher2's loudness (track is ~9 LUFS hotter)
 )

levels/bonus.py

@@ -37,4 +37,6 @@ LEVEL = Level(
     order=1,  # second board: feelings → bonus → critters (via the portal)
     glitch=True,
     portal_to="animal",  # the spiral whisks you to the critters board and back
+    music="corporate-glitch.mp3",  # the glitchy corporate sting for the finale
+    music_gain=0.349,  # trim to match Cipher2's loudness (track is ~9 LUFS hotter)
 )

static/corporate-glitch.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4fca1fa8d43805539f3236f1fbd742bcabacb9169425970c344b7ea42659442d
+size 4499748

static/farm.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:295bc128372ee9d4c612a457d8812f59b6772f627673833e997e74cb2c374d9b
+size 6065423

static/game.js

@@ -1566,45 +1566,103 @@
     },
   };
 
-  // ---- background music: a looping track on the music bus ----
-  // A single recorded loop (Cipher2) plays under the game via an <audio>
-  // element wired into musicGain, so the mixer's music slider levels and mutes
-  // it exactly like before — the bus, prefs, and gesture-unlock are unchanged.
-  let musicEl = null; // the <audio> element, created on first play
-  let musicSrc = null; // its MediaElementAudioSourceNode (only creatable once)
-  let musicPlay = Promise.resolve(); // the last play() promise, so a quick mute
-  // can wait it out instead of interrupting it (see stopMusic)
-
-  // data.music is a "gradio_api/file=…" path. An <audio> already resolves it
-  // against the document, but inside the HF iframe the file route lives under
+  // ---- background music: per-board loops, crossfaded on transition ----
+  // Each board names its own loop (data.levels[].music — bonus = corporate-glitch,
+  // critters = farm) and a loudness trim (.music_gain); boards without one play
+  // the default loop (data.music, Cipher2). Every track gets its own <audio> +
+  // gain node ("voice") feeding the shared musicGain bus, so the mixer slider,
+  // mute, and the glitch low-pass still level them all together. Switching boards
+  // ramps the outgoing voice to 0 and the incoming up to its trim — a crossfade.
+  const CROSSFADE = 1.4; // seconds; rides under the board drop-in
+  const voices = new Map(); // url -> { el, src, gain, play }
+  let curUrl = null; // the track currently faded up (its <audio> is the one playing)
+
+  // data.music / level.music are "gradio_api/file=…" paths. An <audio> resolves
+  // them against the document, but inside the HF iframe the file route lives under
   // the Gradio root — so prefer that root when the config exposes it, and fall
   // back to document-relative (correct on localhost and direct embeds).
-  function musicUrl() {
+  function musicUrl(path) {
     const root = (window.gradio_config && window.gradio_config.root) || "";
     const base = root.replace(/\/+$/, "");
-    return base ? base + "/" + data.music : data.music;
+    return base ? base + "/" + path : path;
+  }
+
+  // the track + loudness trim for the active board (its own, else the default)
+  function trackForLevel() {
+    return { url: musicUrl(level.music || data.music), trim: level.music ? (level.music_gain || 1) : 1 };
+  }
+
+  // a voice is lazily built per track; the MediaElementSource can only be made
+  // once per element, so we cache by url and reuse on revisits.
+  function voiceFor(url) {
+    let v = voices.get(url);
+    if (!v) {
+      const el = new Audio(url);
+      el.loop = true;
+      el.preload = "auto";
+      const src = ac.createMediaElementSource(el);
+      const gain = ac.createGain();
+      gain.gain.value = 0; // silent until faded in
+      src.connect(gain).connect(musicGain);
+      v = { el, src, gain, play: Promise.resolve() };
+      voices.set(url, v);
+    }
+    return v;
+  }
+  function playVoice(v) {
+    // play() is gesture-gated; unlockAudio drives the first call from a real tap
+    v.play = v.el.play() || Promise.resolve();
+    v.play.catch(() => {});
+  }
+
+  // Crossfade to `url`: fade its voice up to `trim`, fade the current one down to
+  // 0 and park it. Idempotent if `url` is already current. The bus gain (musicGain)
+  // is multiplied on top, so a muted bus keeps the swap silent.
+  function crossfadeTo(url, trim) {
+    if (!audio() || url === curUrl) return;
+    const prevUrl = curUrl;
+    curUrl = url;
+    const next = voiceFor(url);
+    const t = ac.currentTime;
+    if (musicVol > 0) playVoice(next); // gesture-gated; bus is 0 anyway when muted
+    next.gain.gain.cancelScheduledValues(t);
+    next.gain.gain.setValueAtTime(next.gain.gain.value, t);
+    next.gain.gain.linearRampToValueAtTime(trim, t + CROSSFADE);
+    const prev = prevUrl && voices.get(prevUrl);
+    if (prev) {
+      prev.gain.gain.cancelScheduledValues(t);
+      prev.gain.gain.setValueAtTime(prev.gain.gain.value, t);
+      prev.gain.gain.linearRampToValueAtTime(0, t + CROSSFADE);
+      // park the element once it's silent — unless it became current again. Wait
+      // out its play() first so the pause can't race a pending play (AbortError).
+      gsap.delayedCall(CROSSFADE + 0.1, () => {
+        if (curUrl !== prevUrl) prev.play.then(() => { if (curUrl !== prevUrl) prev.el.pause(); }).catch(() => {});
+      });
+    }
+  }
+
+  // Switch to the active board's track. No-ops until the context exists (boot
+  // runs before any gesture); unlockAudio starts the right track on first tap.
+  function updateMusicTrack() {
+    if (!ac) return;
+    const { url, trim } = trackForLevel();
+    crossfadeTo(url, trim);
   }
 
   function startMusic() {
     if (!audio()) return;
-    if (!musicEl) {
-      musicEl = new Audio(musicUrl());
-      musicEl.loop = true;
-      musicEl.preload = "auto";
-      musicSrc = ac.createMediaElementSource(musicEl);
-      musicSrc.connect(musicGain);
-    }
-    // play() is gesture-gated; unlockAudio drives the first call from a real tap
-    musicPlay = musicEl.play() || Promise.resolve();
-    musicPlay.catch(() => {});
+    const { url, trim } = trackForLevel();
+    if (curUrl === url) playVoice(voiceFor(url)); // unmuting the current track
+    else crossfadeTo(url, trim); // first play, or catch up after a muted swap
   }
   function stopMusic() {
-    if (!musicEl) return;
-    // Pausing while a play() is still pending throws AbortError and can wedge
-    // the element (a fast mute→unmute mid-load would then stay silent). So wait
-    // for the play to settle, then pause only if we still mean to be off —
-    // musicGain is already at 0, so nothing is audible in the meantime anyway.
-    musicPlay.then(() => { if (musicVol === 0 && musicEl) musicEl.pause(); }).catch(() => {});
+    const v = curUrl && voices.get(curUrl);
+    if (!v) return;
+    // Pausing while a play() is still pending throws AbortError and can wedge the
+    // element (a fast mute→unmute mid-load would then stay silent). So wait for the
+    // play to settle, then pause only if we still mean to be off — the bus is
+    // already at 0, so nothing is audible in the meantime anyway.
+    v.play.then(() => { if (musicVol === 0) v.el.pause(); }).catch(() => {});
   }
 
   // ---- audio toggles: hand-drawn ♫ + speaker doodles in the top-right ----
@@ -3153,6 +3211,7 @@
     // leaving the glitch board (e.g. onto critters) returns the doodle to size
     if (!level.glitch && shrunk) { shrunk = false; charGroup.scale.set(1, 1, 1); }
     setGlitchMode(!!level.glitch); // a glitch board inverts the whole screen
+    updateMusicTrack(); // crossfade to this board's loop (no-op before first gesture)
     state = "hopping"; // block input until the poof lands (then -> idle)
     buildTiles();
     buildTargets();