Audio API

This is an API for modders that enables easily replacing or adding in-game audio. It supports looped audio, PCM WAV, FLAC, OGG VORBIS, OGG OPUS, and can load these via file path and/or ZIP DMA (influding NRM; ZIP/NRM must be store only without compression!). Note: This is an fixed and improved version of Magemods Audio API (original: https://github.com/magemods/mm-audio-api).

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

[0.8.6] - 2026-07-16

Fixed

• [custom soundfonts] AudioLoad_RelocateSample's 0.8.5 KSEG0 guard skipped sampleAddr/medium relocation for imported custom fonts entirely, breaking all custom-bank audio (heavy distortion); the guard now requires a KSEG0 sampleAddr too, and finalizes pre-patched RAM-pointer samples (medium=CART, isRelocated=true) so mod-memory sample data takes the DMA path the RSP can read
• [custom soundfonts] Codebook reads/copies were sized by AdpcmBook.header.order, which lies in the wild (e.g. MMRS zbanks shipping order=4 headers over order-2 data — harmless on hardware because the RSP ucode is hard-wired to the order-2 layout); sizing now follows the ucode's fixed order-2 layout (BOOK_CODEBOOK_NUM_ENTRIES), stopping over-reads past bank allocations in AudioApi_CopySample/AudioApi_HashSample/aLoadADPCM
• [custom soundfonts] AudioApi_AddSoundFont/AudioApi_ReplaceSoundFont packed sampleBank/count metadata into the caller's entry after copying it into the font table, so AudioLoad_InitSoundFont always derived sampleBankId1/2 = 0 and zero counts for custom fonts; the declared sample banks are now honored

[0.8.5] - 2026-07-03

Fixed

• [custom soundfonts] Out-of-bounds read when deep-copying custom envelopes terminated by ADSR_GOTO / ADSR_RESTART
• [polyphony] Audio-thread stack corruption when numNotes > 88 (noteIndices array sized to support full 255-note range)
• [no effect] AudioApi_SetSequenceFlags uninitialized data
• [enemy bgm] AudioApi_SetSequenceFlags queue drain read cmd->asUbyte (high byte on MIPS BE) after the staged-uintptr push wrote the flag to the low byte, so flags set during QUEUEING decoded as 0 — including SEQ_FLAG_ENEMY for vanilla BGM seqIds replaced by streaming mods, causing the enemy battle sub-BGM to never start while main BGM was active
• [mem-leak] CacheStrategy::Default never resolved to PreloadOnUse on Audiofile/Generic/SampleBank
• [decoder] TOCTOU use-after-free between audio thread decode() and GC worker close() after stream idle
• [audiofile] GC worker could close() an Audiofile while the audio thread was mid-getChunk() between open() and decoder->decode(), surfacing as transient "Decoder error: not open" decode failures / audible glitches; GC now skips close() while a chunk fetch is in flight
• [vfs] ZipFile::close wrote curPos outside mutex on the uncompressed path, racing with locked read/seek/tell; now locks unconditionally
• [vfs] ZipArchive accepted short reads silently because stream.fail() && stream.eof() are both set on truncation, bypassing the !eof() guard
• [mem-leak] AudioApi_Replace{SoundFont,Drum,SoundEffect,Instrument} and the init->load queue forwarder ignored RecompQueue_PushIfNotQueued's return value, leaking the deep-copied payload
• [mem-leak] ZipArchive leaked mz_zip_archive on init failure and never called mz_zip_reader_end (no destructor)
• [debug menu] crash safe-guards
• [vadpcm encode] Out-of-bounds read in loop-predictor pass when loopStart exceeds padded sample length
• [soundfont] AudioLoad_RelocateSample re-relocated already-relocated samples when isRelocated was stale (KSEG0 sampleAddr with isRelocated=0); restored vanilla's outer KSEG0 guard to skip re-entry
• AudioApi_PlayFanfare / async PLAY_SEQUENCE dereferenced AudioThread_GetFontsForSequence without bounds- or NULL-checking seqId
• [metadata] Metadata::parseId3v2 misaligned 2-byte read (UB; SIGBUS on strict-alignment ARM).
• Filesystem::isPathAllowed / openFile rejected legitimate filenames containing .., accepted absolute pathStr that bypassed baseDir, and ignored symlinks

[0.8.4] - 2026-03-21

Added

• 32 kHz mode in mod config
• Custom audio debug event registration (will be displayed in debug HTML)

Improved

• Debug HTML design and features

[0.8.3] - 2026-03-15

Fixed

• Heap: RSP cache invalidation
• Mayors theme mono playback

Added

• HTML debug panel. Disabled by default; must be enabled before game start (http://127.0.0.1:18480/audio-debug.html)

[0.8.2] - 2026-03-09

Fixed

• Day 2 Termina soundtrack not playing
• Guru Guru stops playing if ringing the bell or destroying the crate
• Ikana Music Box scene entry volume jump

[0.8.1] - 2026-02-26

Added

• AudioApiFileInfo2, AudioApi_CreateStreamedBgmEx, AudioApi_CreateStreamedFanfareEx, allowing to define a volume offset per track

Fixed

• Main bgm not correctly unmuted after enemy cleared
• Note priority, which caused N64 stealing soundtrack notes whenever it felt like it

Changed

• better concern separation to make it easier to control audio behavior without locking down API to a specific use case
• Streamed audio dropping left channel due to note stealing prio and max notes restrictions
• SFX not working during Final Hours after seperation of concerns patch

[0.7.3] - 2026-02-23

Fixed

• Cavern playback in Astral Observatory
• Guru Guru handling

[0.7.2] - 2026-02-22

NOTE

• From now on all changes are documented here and versioning will follow SemVer versioning

Fixed

• Enemy battle music not playing on second encounter

Changed

• .gitignore
• make now deletes at starts and generates after build /dist and creates the Thunderstore zip to /publish

[0.7.1] - 2026-02-20

Fixed

• Removed warp to credits debug code

[0.7.0] - 2026-02-20

Note

• This is a fork of Magemods Audio API

Fixed

• Frog Song
• Credits
• Ballad of Windfish
• Bremen Mask
• Fanfares looping behavior
• ZIP DMA
• loop index bugs
• queue overflow
• vanilla radio effect
• removed debug code breaking engine behavior

Added

• Morning Jingle feature
• Porcelain registration type flags
• Mod menu config: Radio emulation in shops and minigames toggle (vanilla is on, but sounds really bad, so default is disabled)