Add bb.s3m soundtrack playback via libopenmpt

bb never compiled in sound (libmikmod is missing, per its own configure
output), and there's no realistic path to changing that: WASI has no
audio API at all, so even a working libmikmod couldn't play anything
from inside the wasm module. Plays bb's actual bb.s3m independently,
client-side, via libopenmpt's official prebuilt WebAssembly build
(BSD-3-Clause/BSL-1.0) -- fetched at Docker build time alongside
everything else, not vendored. Not synced to whichever scene bb.wasm is
currently rendering; there's no signal from the wasm side to sync to,
just a soundtrack loop toggled by a button (autoplay policy requires a
user gesture regardless).

This particular libopenmpt.js build doesn't expose HEAPU8/HEAPF32/ccall
on the Module object -- only _malloc/_free and the _openmpt_* C
functions -- so there's no supported way to read or write the bytes a
_malloc'd pointer refers to. Worked around it by wrapping
WebAssembly.instantiate(Streaming) in index.html before loading
libopenmpt.js, capturing the real wasm instance's exports regardless of
what the module chooses to expose, then finding the one export that's a
WebAssembly.Memory (even export names are minified in this build, no
literal "memory" key to look up).

audio.js is wrapped in an IIFE: libopenmpt.js is a classic script too,
and litters the shared global scope with its own same-named internals
(wasmMemory, node, start all collided) -- discovered the hard way when
a same-named local function got silently clobbered.

Claude-Session: https://claude.ai/code/session_01F6QKUwwiAxLNkYn4dv5TfW

Author: chrisns

web/Dockerfile

@@ -86,6 +86,22 @@ RUN cp /usr/share/misc/config.guess /usr/share/misc/config.sub . \
     && ./configure --host=wasm32-wasi \
     && make LDFLAGS="-static"
 
+# bb never compiled in sound (libmikmod is missing, per its own configure
+# output), and there's no realistic path to changing that: WASI has no
+# audio API at all, so even a working libmikmod couldn't play anything
+# from inside the wasm module. Playing bb's actual soundtrack means doing
+# it independently, client-side, with an existing tracker-module player --
+# libopenmpt (BSD-3-Clause/BSL-1.0) is the mature, actively maintained one,
+# with an official prebuilt WebAssembly build for exactly this.
+FROM --platform=$BUILDPLATFORM debian:trixie-slim AS openmpt
+RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+ARG LIBOPENMPT_VERSION=0.8.7
+RUN curl -fL "https://lib.openmpt.org/files/libopenmpt/dev/libopenmpt-${LIBOPENMPT_VERSION}+release.dev.js.tar.gz" | tar -xz -C /opt \
+    && mv "/opt/libopenmpt-${LIBOPENMPT_VERSION}+release/bin/wasm" /opt/libopenmpt
+
 FROM scratch AS export
 COPY --from=build /bb-1.3.0/bb /bb.wasm
-COPY web/index.html web/wasi-shim.js web/worker.js web/app.js web/bb-logo.jpg /
+COPY --from=build /bb-1.3.0/bb.s3m /bb.s3m
+COPY --from=openmpt /opt/libopenmpt/libopenmpt.js /opt/libopenmpt/libopenmpt.wasm /
+COPY web/index.html web/wasi-shim.js web/worker.js web/app.js web/audio.js web/bb-logo.jpg /

web/app.js

@@ -63,7 +63,7 @@ function startWorker(size) {
 }
 
 function fitFont() {
-  const reserved = ["logo", "sizes", "status"]
+  const reserved = ["logo", "sizes", "music", "status"]
     .map((id) => document.getElementById(id))
     .reduce((sum, el) => sum + (el && el.isConnected ? el.getBoundingClientRect().height + 12 : 0), 0);
   const footer = document.querySelector("footer").getBoundingClientRect().height;

web/audio.js

@@ -0,0 +1,111 @@
+// bb never compiled in sound (libmikmod is missing, and WASI has no audio
+// API regardless -- there's no path to the wasm module playing anything
+// itself). This plays bb's actual bb.s3m soundtrack independently,
+// client-side, via libopenmpt (loaded as a classic script by index.html,
+// which sets the global `libopenmpt`/`Module` this depends on). Not
+// synced to whichever scene bb.wasm is currently rendering -- there's no
+// signal from the wasm side to sync to -- just a soundtrack loop.
+//
+// Wrapped in an IIFE: libopenmpt.js is also a classic (non-module) script
+// and litters the shared global scope with its own internal `var`s (e.g.
+// wasmMemory, node, start all collide with obvious names -- discovered
+// the hard way when `function wasmMemory(){}` here got silently
+// clobbered by its same-named global).
+(function () {
+  const BUFFER_FRAMES = 4096;
+
+  let audioCtx = null;
+  let audioNode = null;
+  let modPtr = 0;
+  let outPtr = 0;
+  let playing = false;
+
+  // This build of libopenmpt.js doesn't expose memory-access helpers on
+  // the Module object -- index.html captures the real wasm instance
+  // exports by wrapping WebAssembly.instantiate(Streaming) instead. Even
+  // export names are minified in this build (no "memory" key to look
+  // up), so find the one export that's actually a WebAssembly.Memory
+  // instead. Fetch fresh views each time rather than caching: growing
+  // memory detaches old ArrayBuffers.
+  function findWasmMemory() {
+    for (const value of Object.values(window.__wasmExports)) {
+      if (value instanceof WebAssembly.Memory) return value;
+    }
+    throw new Error("no WebAssembly.Memory export found on libopenmpt.wasm");
+  }
+  const memU8 = () => new Uint8Array(findWasmMemory().buffer);
+  const memF32 = () => new Float32Array(findWasmMemory().buffer);
+
+  function whenReady(cb) {
+    const Module = window.libopenmpt;
+    if (Module.calledRun) cb(Module);
+    else {
+      const prev = Module.onRuntimeInitialized;
+      Module.onRuntimeInitialized = () => {
+        prev?.();
+        cb(Module);
+      };
+    }
+  }
+
+  async function startMusic(button) {
+    button.disabled = true;
+    button.textContent = "Loading…";
+    const Module = await new Promise((resolve) => whenReady(resolve));
+
+    const data = new Uint8Array(await (await fetch("bb.s3m")).arrayBuffer());
+    const dataPtr = Module._malloc(data.length);
+    memU8().set(data, dataPtr);
+    modPtr = Module._openmpt_module_create_from_memory(dataPtr, data.length, 0, 0, 0);
+    Module._free(dataPtr);
+    if (!modPtr) {
+      button.textContent = "Failed to load bb.s3m";
+      return;
+    }
+    Module._openmpt_module_set_repeat_count(modPtr, -1); // loop forever
+
+    audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+    outPtr = Module._malloc(BUFFER_FRAMES * 2 * 4); // interleaved stereo float32
+    audioNode = audioCtx.createScriptProcessor(BUFFER_FRAMES, 0, 2);
+    audioNode.onaudioprocess = (event) => {
+      const rendered = Module._openmpt_module_read_interleaved_float_stereo(
+        modPtr,
+        audioCtx.sampleRate,
+        BUFFER_FRAMES,
+        outPtr,
+      );
+      const interleaved = memF32().subarray(outPtr / 4, outPtr / 4 + rendered * 2);
+      const left = event.outputBuffer.getChannelData(0);
+      const right = event.outputBuffer.getChannelData(1);
+      for (let i = 0; i < rendered; i++) {
+        left[i] = interleaved[i * 2];
+        right[i] = interleaved[i * 2 + 1];
+      }
+      for (let i = rendered; i < BUFFER_FRAMES; i++) left[i] = right[i] = 0;
+    };
+    audioNode.connect(audioCtx.destination);
+
+    playing = true;
+    button.disabled = false;
+    button.textContent = "🔊 Pause music";
+  }
+
+  function stopMusic(button) {
+    audioCtx.suspend();
+    playing = false;
+    button.textContent = "🔇 Play music";
+  }
+
+  function resumeMusic(button) {
+    audioCtx.resume();
+    playing = true;
+    button.textContent = "🔊 Pause music";
+  }
+
+  const button = document.getElementById("music");
+  button.onclick = () => {
+    if (!audioCtx) startMusic(button);
+    else if (playing) stopMusic(button);
+    else resumeMusic(button);
+  };
+})();

web/index.html

@@ -55,6 +55,16 @@
   }
   #sizes button:hover { border-color: #666; color: #ccc; }
   #sizes button[aria-pressed="true"] { color: #0f0; border-color: #0f0; }
+  #music {
+    background: #111;
+    color: #999;
+    border: 1px solid #333;
+    font: inherit;
+    font-size: 0.8rem;
+    padding: 0.2rem 0.6rem;
+    cursor: pointer;
+  }
+  #music:hover { border-color: #666; color: #ccc; }
   footer {
     color: #444;
     font-size: 0.75rem;
@@ -73,6 +83,7 @@
 <body>
   <img id="logo" src="bb-logo.jpg" alt="bb logo">
   <div id="sizes"></div>
+  <button id="music">🔇 Play music</button>
   <pre id="screen"></pre>
   <div id="status">Loading bb.wasm&hellip;</div>
   <footer>
@@ -82,7 +93,8 @@
       Original: <a href="https://aa-project.sourceforge.net/aalib/">aa-lib</a>
       &middot;
       <a href="https://aa-project.sourceforge.net/bb/">bb</a>
-      (last modified Wed Mar 26 1997)
+      (last modified Wed Mar 26 1997).
+      Music playback: <a href="https://lib.openmpt.org/libopenmpt/">libopenmpt</a>
     </div>
     <div class="blurb">
       &ldquo;This demo requires computer at least as fast as 486/33 with coprocesor.
@@ -96,5 +108,26 @@
     </div>
   </footer>
   <script type="module" src="app.js"></script>
+  <script>
+    // This build of libopenmpt.js doesn't expose HEAPU8/HEAPF32/ccall/etc on
+    // the Module object (only _malloc/_free and the _openmpt_* functions),
+    // so there's no supported way to read or write the bytes _malloc'd
+    // pointers refer to. Capture the wasm instance's own exports -- the
+    // memory it holds is real regardless of what the module chooses to
+    // expose -- by wrapping the WebAssembly APIs it instantiates itself
+    // with, and build our own typed array views directly over its buffer.
+    window.libopenmpt = {};
+    for (const name of ["instantiateStreaming", "instantiate"]) {
+      const orig = WebAssembly[name];
+      WebAssembly[name] = async function (...args) {
+        const result = await orig.apply(WebAssembly, args);
+        const instance = result.instance || result;
+        window.__wasmExports = instance.exports;
+        return result;
+      };
+    }
+  </script>
+  <script src="libopenmpt.js"></script>
+  <script src="audio.js"></script>
 </body>
 </html>