romdevtools 0.13.0

package/src/host/dsp-state.js

@@ -0,0 +1,188 @@
+// SNES S-DSP state introspection.
+//
+// Per the rom-games agent's audio-debugging asks: distinguish "voice
+// never produced output" (BRR/envelope issue) from "voice produced
+// output but mixer muted it" (master volume issue). The data lives in
+// the savestate's "SND" block, AFTER the SMP::save_state region. We
+// parse it the same way as cpu-state.js parses the SMP block.
+//
+// SND block layout (cumulative):
+//   [0x10000]                      apuram (SMP::save_state)
+//   [4 × 14 = 56 bytes]            SMP regs (clock + opcode + PC + SP + A + X + Y + 8 P flags)
+//   [...status + timer fields...]
+//   [DSP::save_state begins here]
+//     [128 bytes]                  m.regs (DSP register file)
+//     [per voice × 8]
+//       [12 × int16 = 24 bytes]    v.buf (BRR sample ring)
+//       [uint16]                   v.interp_pos
+//       [uint16]                   v.brr_addr
+//       [uint16]                   v.env       ← THE KEY FIELD
+//       [int16]                    v.hidden_env
+//       [uint8]                    v.buf_pos
+//       [uint8]                    v.brr_offset
+//       [uint8]                    v.kon_delay
+//       [uint8]                    v.env_mode
+//       [uint8]                    v.t_envx_out
+//       [extra: 1 byte N + N bytes pad]
+//     [...echo history, misc...]
+//
+// All multi-byte fields are little-endian (host byte order on wasm32).
+// SPC_DSP::copy_state uses memcpy (no endian flip).
+
+import { findSnes9xBlock } from "./snes9x-state.js";
+
+// Where the DSP block starts within "SND", measured from the start of
+// the SMP region. Sum of every INT32(...) call in SMP::save_state:
+//   apuram(0x10000) + clock(4) + opcode_number(4) + opcode_cycle(4)
+//   + pc(4) + sp(4) + a(4) + x(4) + y(4)
+//   + p.n/v/p/b/h/i/z/c (8 × 4 = 32)
+//   + iplrom_enable(4) + dsp_addr(4)
+//   + ram00f8(4) + ram00f9(4)
+//   + timer0.{enable,target,stage1,stage2,stage3} (5 × 4 = 20)
+//   + timer1 (5 × 4 = 20)
+//   + timer2 (5 × 4 = 20)
+//   + rd(4) + wr(4) + dp(4) + sp(4) + ya(4) + bit(4) = 24
+const SMP_BLOCK_BYTES =
+  0x10000 + // apuram
+  3 * 4 +   // clock + opcode_number + opcode_cycle
+  5 * 4 +   // pc + sp + a + x + y
+  8 * 4 +   // p flags (n v p b h i z c)
+  4 * 4 +   // iplrom_enable + dsp_addr + ram00f8 + ram00f9
+  3 * 5 * 4 + // 3 timers × 5 fields
+  6 * 4;    // rd + wr + dp + sp + ya + bit
+
+/**
+ * Decode SNES S-DSP voice state + key register slices.
+ *
+ * @param {Uint8Array} state full savestate buffer
+ * @returns {{
+ *   regs: Uint8Array,                       // 128-byte DSP register file
+ *   masterVolume: { l: number, r: number }, // signed -128..127
+ *   echoVolume: { l: number, r: number },
+ *   flg: number,                            // FLG register: bit 6 = mute, bit 7 = reset
+ *   kon: number,                            // last KON write (bitmask of voices keyed on)
+ *   koff: number,                           // last KOFF write
+ *   endx: number,                           // ENDX (voices whose samples have ended)
+ *   voices: Array<{
+ *     slot: number,
+ *     vol: { l: number, r: number },        // signed -128..127
+ *     pitch: number,                        // 14-bit unsigned
+ *     srcn: number,                         // sample directory index
+ *     adsr: { adsr1: number, adsr2: number },
+ *     gain: number,
+ *     envx: number,                         // RAW DSP register (snapshot at last sample)
+ *     outx: number,                         // RAW DSP register (snapshot)
+ *     env: number,                          // INTERNAL envelope value (gates output)
+ *     hiddenEnv: number,                    // ADSR rate counter / GAIN internal
+ *     envMode: number,                      // 0=release, 1=attack, 2=decay, 3=sustain
+ *     bufLastSamples: number[],             // last 12 BRR-decoded samples (int16)
+ *     bufPos: number,
+ *   }>
+ * } | null}
+ */
+export function decodeSnes9xDSP(state) {
+  const off = findSnes9xBlock(state, "SND");
+  if (off < 0) return null;
+  let p = off + SMP_BLOCK_BYTES;
+
+  // DSP register file (128 bytes)
+  const regs = state.slice(p, p + 128);
+  p += 128;
+
+  // 8 voices
+  const voices = [];
+  for (let i = 0; i < 8; i++) {
+    const bufStart = p;
+    const bufLastSamples = [];
+    for (let j = 0; j < 12; j++) {
+      const lo = state[bufStart + j * 2];
+      const hi = state[bufStart + j * 2 + 1];
+      // Sign-extend 16-bit
+      const u = lo | (hi << 8);
+      bufLastSamples.push(u >= 0x8000 ? u - 0x10000 : u);
+    }
+    p += 24;
+    const interpPos = state[p] | (state[p + 1] << 8); p += 2;
+    const brrAddr = state[p] | (state[p + 1] << 8); p += 2;
+    const env = state[p] | (state[p + 1] << 8); p += 2;
+    const hiddenEnvU = state[p] | (state[p + 1] << 8); p += 2;
+    const hiddenEnv = hiddenEnvU >= 0x8000 ? hiddenEnvU - 0x10000 : hiddenEnvU;
+    const bufPos = state[p++];
+    /* brrOffset */ p++;
+    /* konDelay */ p++;
+    const envMode = state[p++];
+    /* t_envx_out */ p++;
+    // copier.extra(): uint8 N then N bytes pad
+    const extraN = state[p++];
+    p += extraN;
+
+    // Voice DSP regs: base = voice<<4, fields:
+    //   $X0 VOLL, $X1 VOLR, $X2 PITCHL, $X3 PITCHH, $X4 SRCN,
+    //   $X5 ADSR1, $X6 ADSR2, $X7 GAIN, $X8 ENVX, $X9 OUTX
+    const base = i << 4;
+    const vol = {
+      l: regs[base] > 0x7F ? regs[base] - 256 : regs[base],
+      r: regs[base + 1] > 0x7F ? regs[base + 1] - 256 : regs[base + 1],
+    };
+    const pitch = regs[base + 2] | ((regs[base + 3] & 0x3F) << 8);
+    voices.push({
+      slot: i,
+      vol,
+      pitch,
+      srcn: regs[base + 4],
+      adsr: { adsr1: regs[base + 5], adsr2: regs[base + 6] },
+      gain: regs[base + 7],
+      envx: regs[base + 8],
+      outx: regs[base + 9],
+      env,
+      hiddenEnv,
+      envMode,
+      bufLastSamples,
+      bufPos,
+    });
+    // Discard interpPos, brrAddr — agent rarely needs them; available
+    // via savestate if they do.
+  }
+
+  // CAREFUL: the DSP register file (m.regs) holds the LAST VALUE WRITTEN
+  // to each address, not necessarily a useful runtime state. Reading
+  // regs[KON] tells you "what KON byte the driver wrote most recently",
+  // not "which voices are currently keying on" — the DSP consumes KON
+  // every sample and clears its internal new_kon shadow. Same for KOFF.
+  // ENDX is special: the DSP auto-clears regs[ENDX] on every write
+  // regardless of the data byte.
+  //
+  // Surface these as `regs4C` / `regs5C` / `regs7C` (raw byte names)
+  // rather than `kon` / `koff` / `endx` (state names) so callers don't
+  // mistake the byte for a live interpretation. Field names are still
+  // memorable (the address IS the canonical DSP register name) but
+  // semantically honest about what you're reading.
+  //
+  // Source: snes9x/src/apu/bapu/dsp/SPC_DSP.h r_* constants; .cpp KON/
+  // ENDX special-case write handling at lines 285-291.
+  return {
+    regs,
+    masterVolume: {
+      l: regs[0x0C] > 0x7F ? regs[0x0C] - 256 : regs[0x0C],
+      r: regs[0x1C] > 0x7F ? regs[0x1C] - 256 : regs[0x1C],
+    },
+    echoVolume: {
+      l: regs[0x2C] > 0x7F ? regs[0x2C] - 256 : regs[0x2C],
+      r: regs[0x3C] > 0x7F ? regs[0x3C] - 256 : regs[0x3C],
+    },
+    flg: regs[0x6C], // bit 6 = mute, bit 7 = reset — direct register, no shadow
+    regs4C: regs[0x4C], // last KON write (not "currently keying on" — DSP consumes per sample)
+    regs5C: regs[0x5C], // last KOFF write
+    regs7C: regs[0x7C], // ENDX register — auto-cleared by DSP on every write
+    voices,
+  };
+}
+
+/**
+ * @param {import("./LibretroHost.js").LibretroHost} host
+ * @param {string} platform
+ */
+export function getDspState(host, platform) {
+  if (platform !== "snes") return null;
+  return decodeSnes9xDSP(host.serializeState());
+}

package/src/host/framebuffer.js

@@ -0,0 +1,115 @@
+// Framebuffer utilities. XRGB8888 / RGB565 / 0RGB1555 → PNG (base64).
+//
+// libretro pixel layouts (little-endian, byte order on a little-endian host):
+//   XRGB8888 → [B, G, R, X] per pixel, 4 bytes
+//   RGB565   → low byte then high byte; bits {15..11=R, 10..5=G, 4..0=B}
+//   0RGB1555 → low byte then high byte; bits {14..10=R, 9..5=G, 4..0=B}
+//
+// pngjs expects [R, G, B, A] per pixel.
+
+import { PNG } from "pngjs";
+import {
+  RETRO_PIXEL_FORMAT_0RGB1555,
+  RETRO_PIXEL_FORMAT_RGB565,
+  RETRO_PIXEL_FORMAT_XRGB8888,
+} from "./retroConstants.js";
+
+/**
+ * Convert a libretro framebuffer to a flat RGBA8888 Uint8Array (one
+ * row at a time, no padding). Same pixel-format decode as
+ * framebufferToPng but skips the PNG encode step — useful when the
+ * caller wants raw pixels (e.g. piping into chafa-wasm for ASCII
+ * rendering).
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array} src raw framebuffer bytes
+ * @param {number} pitch bytes per row
+ * @param {number} format one of RETRO_PIXEL_FORMAT_*
+ * @returns {Uint8Array} `width * height * 4` bytes, RGBA order
+ */
+export function framebufferToRgba(width, height, src, pitch, format) {
+  const dst = new Uint8Array(width * height * 4);
+  decodePixelsInto(dst, width, height, src, pitch, format);
+  return dst;
+}
+
+function decodePixelsInto(dst, width, height, src, pitch, format) {
+  if (format === RETRO_PIXEL_FORMAT_XRGB8888) {
+    for (let y = 0; y < height; y++) {
+      const srcRow = y * pitch;
+      const dstRow = y * width * 4;
+      for (let x = 0; x < width; x++) {
+        const s = srcRow + x * 4;
+        const d = dstRow + x * 4;
+        dst[d + 0] = src[s + 2]; // R
+        dst[d + 1] = src[s + 1]; // G
+        dst[d + 2] = src[s + 0]; // B
+        dst[d + 3] = 0xff;
+      }
+    }
+  } else if (format === RETRO_PIXEL_FORMAT_RGB565) {
+    for (let y = 0; y < height; y++) {
+      const srcRow = y * pitch;
+      const dstRow = y * width * 4;
+      for (let x = 0; x < width; x++) {
+        const s = srcRow + x * 2;
+        const pix = src[s] | (src[s + 1] << 8);
+        const r = (pix >> 11) & 0x1f;
+        const g = (pix >> 5) & 0x3f;
+        const b = pix & 0x1f;
+        const d = dstRow + x * 4;
+        dst[d + 0] = (r << 3) | (r >> 2);
+        dst[d + 1] = (g << 2) | (g >> 4);
+        dst[d + 2] = (b << 3) | (b >> 2);
+        dst[d + 3] = 0xff;
+      }
+    }
+  } else if (format === RETRO_PIXEL_FORMAT_0RGB1555) {
+    for (let y = 0; y < height; y++) {
+      const srcRow = y * pitch;
+      const dstRow = y * width * 4;
+      for (let x = 0; x < width; x++) {
+        const s = srcRow + x * 2;
+        const pix = src[s] | (src[s + 1] << 8);
+        const r = (pix >> 10) & 0x1f;
+        const g = (pix >> 5) & 0x1f;
+        const b = pix & 0x1f;
+        const d = dstRow + x * 4;
+        dst[d + 0] = (r << 3) | (r >> 2);
+        dst[d + 1] = (g << 3) | (g >> 2);
+        dst[d + 2] = (b << 3) | (b >> 2);
+        dst[d + 3] = 0xff;
+      }
+    }
+  } else {
+    throw new Error(`Unsupported pixel format ${format}`);
+  }
+}
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array} src raw framebuffer bytes
+ * @param {number} pitch bytes per row
+ * @param {number} format one of RETRO_PIXEL_FORMAT_*
+ * @returns {Buffer} PNG bytes
+ */
+export function framebufferToPng(width, height, src, pitch, format) {
+  const png = new PNG({ width, height });
+  decodePixelsInto(png.data, width, height, src, pitch, format);
+  return PNG.sync.write(png);
+}
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array} src
+ * @param {number} pitch
+ * @param {number} format
+ * @returns {import("./types.js").ScreenshotResult}
+ */
+export function framebufferToScreenshot(width, height, src, pitch, format) {
+  const buf = framebufferToPng(width, height, src, pitch, format);
+  return { width, height, pngBase64: buf.toString("base64") };
+}

package/src/host/gb-apu-state.js

@@ -0,0 +1,321 @@
+// Game Boy (DMG/CGB) and Game Boy Advance APU state introspection.
+//
+// Same idea as nes-apu-state.js: give GB/GBC/GBA music jobs a "what is each
+// channel playing this frame?" decode straight off the hardware register file,
+// independent of whatever private sound driver the game uses.
+//
+// GB data source: the `gb_io` region — the 128-byte I/O page at $FF00-$FF7F.
+// The APU register block lives at $FF10-$FF3F, i.e. io[0x10]..io[0x3F]:
+//
+//   NR10=$10 sweep      NR11=$11 duty/len   NR12=$12 vol/env
+//   NR13=$13 freq lo    NR14=$14 freq hi+trigger        (channel 1, pulse+sweep)
+//   NR21=$16 duty/len   NR22=$17 vol/env
+//   NR23=$18 freq lo    NR24=$19 freq hi+trigger        (channel 2, pulse)
+//   NR30=$1A DAC        NR31=$1B len        NR32=$1C vol-shift
+//   NR33=$1D freq lo    NR34=$1E freq hi+trigger        (channel 3, wave)
+//   NR41=$20 len        NR42=$21 vol/env
+//   NR43=$22 noise freq NR44=$23 trigger                (channel 4, noise)
+//   NR50=$24 master vol NR51=$25 panning    NR52=$26 power + channel status
+//
+// GBA data source: the `gba_io_regs` region — the 0x400-byte I/O page at
+// $4000000. The GBA carries the same four DMG PSG channels (mirrored at byte
+// offsets $60-$81) plus two Direct Sound DMA FIFO channels ($A0/$A4). The
+// PSG decode reuses the exact same formulas as GB; only the offsets differ.
+//
+// These are *register* bytes (what the CPU last wrote), not the APU's internal
+// envelope/sweep counters — which is exactly the pitch/duty/volume layer you
+// want for music transcription.
+
+// Pulse channels: freq = 131072 / (2048 - freq11) Hz.
+// Wave channel:   freq =  65536 / (2048 - freq11) Hz.
+// freq11 is the 11-bit timer (NRx3 | ((NRx4 & 7) << 8)).
+
+// Duty-cycle code (NRx1 bits 6-7) → human label.
+const DUTY_LABEL = ["12.5%", "25%", "50%", "75%"];
+
+// Wave volume-shift code (NR32 bits 5-6) → output level percentage.
+const WAVE_VOLUME_LABEL = ["mute", "100%", "50%", "25%"];
+
+/**
+ * Convert a frequency in Hz to the nearest note name (e.g. "A4", "C#5"),
+ * or null for zero / non-finite frequencies. A4 = 440 Hz, 12-TET.
+ * @param {number} hz
+ * @returns {string | null}
+ */
+export function freqToNote(hz) {
+  if (!hz || !Number.isFinite(hz) || hz <= 0) return null;
+  const NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+  const midi = Math.round(69 + 12 * Math.log2(hz / 440));
+  const name = NAMES[((midi % 12) + 12) % 12] + (Math.floor(midi / 12) - 1);
+  return name;
+}
+
+/** Round a frequency to 2 decimal places (null stays null). */
+function round2(hz) {
+  return hz == null ? null : Math.round(hz * 100) / 100;
+}
+
+/**
+ * Decode a square/pulse channel from its three register bytes.
+ * @param {number} nrx1 duty/length (bits 6-7 = duty)
+ * @param {number} nrx2 volume/envelope (bits 4-7 = initial volume)
+ * @param {number} nrx3 frequency low byte
+ * @param {number} nrx4 frequency high bits + trigger/length-enable
+ * @param {boolean} enabled channel status bit from NR52
+ * @returns {{ enabled: boolean, freqHz: number|null, note: string|null,
+ *   duty: number, dutyLabel: string, volume: number, lengthEnable: boolean }}
+ */
+function decodePulseCore(nrx1, nrx2, nrx3, nrx4, enabled) {
+  const freq11 = nrx3 | ((nrx4 & 0x07) << 8);
+  const freqHz = freq11 < 2048 ? 131072 / (2048 - freq11) : null;
+  const duty = (nrx1 >> 6) & 0x03;
+  return {
+    enabled,
+    freqHz: round2(freqHz),
+    note: freqToNote(freqHz),
+    duty,
+    dutyLabel: DUTY_LABEL[duty],
+    volume: (nrx2 >> 4) & 0x0F,
+    lengthEnable: !!(nrx4 & 0x40),
+  };
+}
+
+/**
+ * Decode the wave channel (channel 3) from its register bytes.
+ * @param {number} nr30 DAC power (bit7)
+ * @param {number} nr32 volume shift (bits 5-6)
+ * @param {number} nr33 frequency low byte
+ * @param {number} nr34 frequency high bits + trigger/length-enable
+ * @param {boolean} enabled channel status bit from NR52
+ * @returns {{ enabled: boolean, freqHz: number|null, note: string|null,
+ *   volumeShift: number, volumeLabel: string, lengthEnable: boolean, dacOn: boolean }}
+ */
+function decodeWaveCore(nr30, nr32, nr33, nr34, enabled) {
+  const freq11 = nr33 | ((nr34 & 0x07) << 8);
+  const freqHz = freq11 < 2048 ? 65536 / (2048 - freq11) : null;
+  const volumeShift = (nr32 >> 5) & 0x03;
+  return {
+    enabled,
+    freqHz: round2(freqHz),
+    note: freqToNote(freqHz),
+    volumeShift,
+    volumeLabel: WAVE_VOLUME_LABEL[volumeShift],
+    lengthEnable: !!(nr34 & 0x40),
+    dacOn: !!(nr30 & 0x80),
+  };
+}
+
+/**
+ * Decode the noise channel (channel 4) from its register bytes.
+ * @param {number} nrx2 volume/envelope (bits 4-7 = initial volume)
+ * @param {number} nrx3 noise frequency (divisor / shift clock / width)
+ * @param {number} nrx4 trigger + length-enable
+ * @param {boolean} enabled channel status bit from NR52
+ * @returns {{ enabled: boolean, volume: number, divisorCode: number,
+ *   shiftClock: number, widthMode: number, lengthEnable: boolean }}
+ */
+function decodeNoiseCore(nrx2, nrx3, nrx4, enabled) {
+  return {
+    enabled,
+    volume: (nrx2 >> 4) & 0x0F,
+    divisorCode: nrx3 & 0x07,        // bits 0-2: clock divisor code
+    shiftClock: (nrx3 >> 4) & 0x0F,  // bits 4-7: shift-clock frequency
+    widthMode: (nrx3 >> 3) & 0x01,   // bit 3: 0 = 15-bit, 1 = 7-bit LFSR
+    lengthEnable: !!(nrx4 & 0x40),
+  };
+}
+
+/**
+ * @typedef {ReturnType<typeof decodePulseCore>} GbPulseState
+ * @typedef {ReturnType<typeof decodeWaveCore>} GbWaveState
+ * @typedef {ReturnType<typeof decodeNoiseCore>} GbNoiseState
+ */
+
+/**
+ * Decode a four-channel DMG/CGB PSG register block given an accessor that maps
+ * an APU register offset (e.g. 0x10 for NR10) to its byte value. Shared by both
+ * the GB decoder (offsets into the I/O page) and the GBA decoder (offsets into
+ * the GBA I/O page, which mirrors the same NRxx layout).
+ *
+ * @param {(off: number) => number} r register-byte accessor
+ * @param {{ nr10: number, nr11: number, nr12: number, nr13: number, nr14: number,
+ *   nr21: number, nr22: number, nr23: number, nr24: number,
+ *   nr30: number, nr32: number, nr33: number, nr34: number,
+ *   nr42: number, nr43: number, nr44: number }} map register offsets
+ * @param {number} nr52 power + per-channel status byte
+ * @returns {{ pulse1: GbPulseState & { sweep: { period: number, shift: number, negate: boolean } },
+ *   pulse2: GbPulseState, wave: GbWaveState, noise: GbNoiseState }}
+ */
+function decodePsgBlock(r, map, nr52) {
+  const sweepReg = r(map.nr10);
+  const pulse1 = {
+    ...decodePulseCore(r(map.nr11), r(map.nr12), r(map.nr13), r(map.nr14), !!(nr52 & 0x01)),
+    sweep: {
+      period: (sweepReg >> 4) & 0x07, // bits 4-6: sweep time/period
+      shift: sweepReg & 0x07,         // bits 0-2: sweep shift amount
+      negate: !!(sweepReg & 0x08),    // bit 3: 1 = decrease (negate)
+    },
+  };
+  const pulse2 = decodePulseCore(
+    r(map.nr21), r(map.nr22), r(map.nr23), r(map.nr24), !!(nr52 & 0x02),
+  );
+  const wave = decodeWaveCore(
+    r(map.nr30), r(map.nr32), r(map.nr33), r(map.nr34), !!(nr52 & 0x04),
+  );
+  const noise = decodeNoiseCore(r(map.nr42), r(map.nr43), r(map.nr44), !!(nr52 & 0x08));
+  return { pulse1, pulse2, wave, noise };
+}
+
+// APU register offsets within the 128-byte `gb_io` page ($FF00-$FF7F).
+const GB_MAP = {
+  nr10: 0x10, nr11: 0x11, nr12: 0x12, nr13: 0x13, nr14: 0x14,
+  nr21: 0x16, nr22: 0x17, nr23: 0x18, nr24: 0x19,
+  nr30: 0x1a, nr32: 0x1c, nr33: 0x1d, nr34: 0x1e,
+  nr42: 0x21, nr43: 0x22, nr44: 0x23,
+  nr50: 0x24, nr51: 0x25, nr52: 0x26,
+};
+
+/** Format a byte as a "0x.." hex string (2 digits). */
+function hex(b) {
+  return "0x" + (b & 0xff).toString(16).padStart(2, "0");
+}
+
+/** Format a 16-bit value as a "0x...." hex string (4 digits). */
+function hex16(v) {
+  return "0x" + (v & 0xffff).toString(16).padStart(4, "0");
+}
+
+/**
+ * Decode the Game Boy (DMG/CGB) APU register file into per-channel musical state.
+ *
+ * @param {Uint8Array} io the 128-byte `gb_io` region ($FF00-$FF7F)
+ * @returns {{
+ *   enabled: boolean,
+ *   channels: {
+ *     pulse1: GbPulseState & { sweep: { period: number, shift: number, negate: boolean } },
+ *     pulse2: GbPulseState,
+ *     wave: GbWaveState,
+ *     noise: GbNoiseState,
+ *   },
+ *   nr52: string,
+ *   panning: string,
+ *   masterVolume: { left: number, right: number },
+ * }}
+ */
+export function decodeGbApu(io) {
+  const nr52 = io[GB_MAP.nr52];
+  const nr50 = io[GB_MAP.nr50];
+  const channels = decodePsgBlock((off) => io[off], GB_MAP, nr52);
+  return {
+    enabled: !!(nr52 & 0x80), // NR52 bit7 = APU power
+    channels,
+    nr52: hex(nr52),
+    panning: hex(io[GB_MAP.nr51]),
+    masterVolume: {
+      left: (nr50 >> 4) & 0x07,  // bits 4-6: left (SO2) volume
+      right: nr50 & 0x07,        // bits 0-2: right (SO1) volume
+    },
+  };
+}
+
+// GBA audio register byte offsets within the 0x400-byte `gba_io_regs` page.
+// The four PSG channels mirror the DMG NRxx registers, two bytes apart, and we
+// remap them onto the same GB_MAP-style offset names so decodePsgBlock works
+// unchanged. SOUND1CNT_L holds the sweep; SOUNDxCNT_H/_X hold len/vol/env/freq.
+const GBA = {
+  SOUND1CNT_L: 0x60, SOUND1CNT_H: 0x62, SOUND1CNT_X: 0x64,
+  SOUND2CNT_L: 0x68, SOUND2CNT_H: 0x6c,
+  SOUND3CNT_L: 0x70, SOUND3CNT_H: 0x72, SOUND3CNT_X: 0x74,
+  SOUND4CNT_L: 0x78, SOUND4CNT_H: 0x7c,
+  SOUNDCNT_L: 0x80, SOUNDCNT_H: 0x82, SOUNDCNT_X: 0x84, SOUNDBIAS: 0x88,
+};
+
+/**
+ * Decode one Direct Sound DMA FIFO channel's control bits out of SOUNDCNT_H.
+ * @param {number} cntH the 16-bit SOUNDCNT_H value
+ * @param {number} shift bit position of this channel's control nibble (8 for A, 12 for B)
+ * @returns {{ enable: { right: boolean, left: boolean }, timer: number,
+ *   reset: boolean, volume: string }}
+ */
+function decodeDirectSound(cntH, shift) {
+  const f = (cntH >> shift) & 0x0f;
+  return {
+    enable: {
+      right: !!(f & 0x01), // output to right
+      left: !!(f & 0x02),  // output to left
+    },
+    timer: (f >> 2) & 0x01, // which timer (0 or 1) drives the FIFO
+    reset: !!(f & 0x08),    // FIFO reset
+    // DMA-sound volume ratio: SOUNDCNT_H bit2 (A) / bit3 (B). 0 = 50%, 1 = 100%.
+    volume: ((cntH >> (shift === 8 ? 2 : 3)) & 0x01) ? "100%" : "50%",
+  };
+}
+
+/**
+ * Decode the Game Boy Advance APU register file: the four DMG PSG channels plus
+ * the two Direct Sound DMA FIFO channels.
+ *
+ * @param {Uint8Array} io the 0x400-byte `gba_io_regs` region (IO page at $4000000)
+ * @returns {{
+ *   enabled: boolean,
+ *   psg: ReturnType<typeof decodePsgBlock>,
+ *   directSound: {
+ *     a: ReturnType<typeof decodeDirectSound>,
+ *     b: ReturnType<typeof decodeDirectSound>,
+ *   },
+ *   psgVolume: { right: number, left: number },
+ *   soundBias: string,
+ *   soundcntX: string,
+ * }}
+ */
+export function decodeGbaApu(io) {
+  /** Read a 16-bit little-endian halfword at byte offset `off`. */
+  const u16 = (off) => io[off] | (io[off + 1] << 8);
+
+  const soundcntX = u16(GBA.SOUNDCNT_X);
+  const soundcntL = u16(GBA.SOUNDCNT_L);
+  const soundcntH = u16(GBA.SOUNDCNT_H);
+
+  // SOUNDCNT_X bits 0-3 are the live PSG channel-on status (same bit order as
+  // GB NR52 bits 0-3), so we can feed them straight into the shared decoder.
+  const nr52Equiv = soundcntX & 0x0f;
+
+  // Map the shared PSG decoder's NRxx offset names onto the GBA register bytes.
+  // Each GBA sound register is a 16-bit pair; the meaningful NRxx byte we want
+  // is at a specific byte offset within it (low byte = first, high byte = +1).
+  const gbaPsgMap = {
+    nr10: GBA.SOUND1CNT_L,         // sweep (low byte of SOUND1CNT_L)
+    nr11: GBA.SOUND1CNT_H,         // duty/len  (low byte of SOUND1CNT_H)
+    nr12: GBA.SOUND1CNT_H + 1,     // vol/env   (high byte of SOUND1CNT_H)
+    nr13: GBA.SOUND1CNT_X,         // freq lo   (low byte of SOUND1CNT_X)
+    nr14: GBA.SOUND1CNT_X + 1,     // freq hi   (high byte of SOUND1CNT_X)
+    nr21: GBA.SOUND2CNT_L,         // duty/len
+    nr22: GBA.SOUND2CNT_L + 1,     // vol/env
+    nr23: GBA.SOUND2CNT_H,         // freq lo
+    nr24: GBA.SOUND2CNT_H + 1,     // freq hi
+    nr30: GBA.SOUND3CNT_L,         // DAC/wave enable
+    nr32: GBA.SOUND3CNT_H + 1,     // vol-shift (high byte of SOUND3CNT_H)
+    nr33: GBA.SOUND3CNT_X,         // freq lo
+    nr34: GBA.SOUND3CNT_X + 1,     // freq hi
+    nr42: GBA.SOUND4CNT_L + 1,     // vol/env   (high byte of SOUND4CNT_L)
+    nr43: GBA.SOUND4CNT_H,         // noise freq
+    nr44: GBA.SOUND4CNT_H + 1,     // trigger/len-enable
+  };
+
+  const psg = decodePsgBlock((off) => io[off], gbaPsgMap, nr52Equiv);
+
+  return {
+    enabled: !!(soundcntX & 0x80), // SOUNDCNT_X bit7 = master sound enable
+    psg,
+    directSound: {
+      a: decodeDirectSound(soundcntH, 8),
+      b: decodeDirectSound(soundcntH, 12),
+    },
+    psgVolume: {
+      right: soundcntL & 0x07,        // bits 0-2: right (SO1) PSG volume
+      left: (soundcntL >> 4) & 0x07,  // bits 4-6: left  (SO2) PSG volume
+    },
+    soundBias: hex16(io[GBA.SOUNDBIAS] | (io[GBA.SOUNDBIAS + 1] << 8)),
+    soundcntX: hex16(soundcntX),
+  };
+}