Audio: internals

Finding the sound files

Retail reads sound data by PROT.DAT entry number. A dev-station path (h:\...) survives in the same functions but is never taken on a retail disc: the split is the build-mode global _DAT_8007B8C2, and the dev arm opens files through a host trap that has no disc to read.

The victory-voice pick, in the results sequencer FUN_8004E568: a pose tier from the pose actor's HP (≥ 3/4, ≥ 1/2, ≥ 1/4, below; a status in mask 0x107B forces tier 4), a pose action id from the per-character table at 0x800788A0, then a clip byte at 0x80078867 + action + char_id*8. Per-character clip bands: Vahn 0xB8..0xBC, Gala 0xBD..0xC3, Noa 0xC4..0xCB.

A third “mode-aware extension dispatcher” that turns up in call graphs is not a sound consumer at all - it is the character-mesh equipment group-transform swap (character mesh).

The track-swap handshake

The BGM poller FUN_800243F0 runs a stage counter through a seven-entry jump table while a track change is in flight: wait for CD idle and arm a 30-frame settle; tear down and close the BGM slot unless bit 0 below is set, then kick the async load; count the settle down; install the score; re-attach the slot unless bit 1 is set; latch. The sound-flag word _DAT_8007B750 coordinates it with the script:

After setting bit 3 the poller stalls while bit 0 is set and bit 4 is not, so a swap started by sub-op 9 keeps the old track until the script commits with sub-op 0xA, which detaches and closes the old occupant, sets bit 4 and clears bit 1. A port that honours the sub-op 2 pause but drops the 0xA commit leaves the music paused after the cutscene.

The libsnd calls under the control words settle their meaning: the pause raises a status flag and keeps the cursor; the play core rewinds the cursor to the start for every mode before it plays - which is why sub-op 4 is a replay from the first event, not a resume.

Sony's sequencer and SPU driver

libsnd (0x80061B18..0x800681D8) walks the SEQ bytes, keeps per-channel state in 16 slots of 0xB0-byte records, and turns note events into key-ons; Legaia installs two function-pointer hooks to wire the script VM's sequence context in. libspu (0x80068..0x8006D) pokes the chip's registers, runs the four-mode DMA transfer engine and the block allocator. Being the same libraries every PsyQ game shipped is what lets the functions be named.

• Key-on volume chain. On the sequencer path (FUN_80067550, in retail’s order and integer steps): the channel volume (CC7) folded into the velocity as vel × chvol / 127; velocity × bank volume × program volume × tone volume widened into the 14-bit register domain; the per-side sequence volume / 0x7F, which the game sets to 107 for every BGM sequence ((215 << 15) >> 16 through FUN_80064890); one pan attenuation per source (tone, program, channel); and a closing square taper v × v / 0x3FFF. A mid-note CC7 or CC10 re-runs the whole chain for every sounding voice on the channel. Against three retail save states, every sounding BGM voice’s pitch, envelope, left / right volume and reverb send matches what the engine programs.
• A sequence-volume change re-volumes the held notes. SsSeqSetVol on a playing slot, and every step of its slide, runs FUN_80067E9C: it stores the new volume and then recomputes every voice the sequence owns through the same chain, so a note held across a summon duck comes down with it. The port does the same at the next flush.
• The duck's volume is the audio level halved. Every site that turns a level into a sequence volume halves the word ((level << 15) >> 16 or sra 1), so a level of 210 plays at 105 - not the 104 a 107 × level / 215 scaling floors to. The library's summon states bear it out record by record. The level is applied at the top of each frame, before the battle logic steps it, so the music follows the duck one frame behind.
• Monaural. The options screen’s mono mode sounds each voice at the larger of its two volumes on both sides (0x800677F4..0x80067818), not at their average. That fold is all SsSetMono changes: XA voice, movie audio and the reverb return stay stereo. The port's separate Mono output setting (downmix_mono) is the full downmix for a single speaker.
• Pitch law. A note is pitched against its tone's center through a two-octave table into a 14-bit SPU PITCH (clamped 0x3FFF).
• Bank open validates the pBAV magic, builds the program-to-tone-page rank map into the reserved ProgAtr words, allocates SPU memory and stashes per-VAG addresses.
• Tempo becomes an integer tick step where the wall clock meets the sequencer; the decoder does not consume a whole event per call. A tempo set (the open FUN_80062410 and the tempo meta FUN_80061954 share one tail) stores the integer 60000000 / us_per_qn as the BPM and installs a budget of tenths of a tick per call, resolution × bpm × 10 / (divisor × 60) rounded to nearest, with the divisor 0x801CD2BC reading 60 in every catalogued save state. A track therefore runs at budget × 6 ticks a second rather than at its written tempo - 0.44 % off on average over the music_01 scores, 120 BPM exact, 24.83 BPM playing 3.4 % slow.
• Not audio: the 0x801CE628 cluster next door is libpad. And none of this is libgpu - battle and field code fire cues during render passes, which is why the cluster looks renderer-adjacent in call graphs.

libsnd functions

libspu globals, primitives and the transfer engine

An earlier “SsSepOpen / VAP SEP loader” reading of the bank open is falsified - the magic is the VAB's. See do-not-re-walk.

The port's audio model

crates/engine-audio is a from-scratch model; engine-session's AudioDirector turns field-VM sound events into sequencers and fires SFX cues against the banks their category names, generic over the output so the native window (cpal) and the browser (WebAudio) share it.

• Reverb is Studio C, always on, on every voice. Every captured retail state - field, town, battle, summon, title, minigames - has the master enable set and the reverb registers byte-identical to the Studio C preset, and each voice's send set by the tone it was keyed from (mode & 4). The output depth, which no preset carries, is a measured fixed pair. No SEQ carries a CC91 reverb-depth event.
• Timebase. The sequencer ticks once per SPU sample with an exact integer accumulator - locked to the audio clock, no drift, bit-deterministic for replays. It spaces events at retail's quantised rate (above) by default; Sequencer::set_exact_tempo(true) plays the score as written. Retail fires an event at the first SsSeqCalc after it falls due and writes its key-on at that call's flush, so every onset lands on a vsync; the port runs the same pump, spending one vsync's budget per flush period, re-reading it after every event so a tempo meta retunes the vsync it lands in, and carrying the overshoot. With the pump, two measured tracks match every key-on of their retail census; firing each event on its own sample instead moves notes near a vsync boundary into the neighbouring flush after any tempo change. A track whose header tempo is its only tempo plays at the header's rounded BPM, where a tempo meta truncates. The SEQ header tempo is a 240 BPM placeholder overridden by the first body tempo event, which carries no MIDI length byte; mis-parsing it pins playback ~3x fast (seq).
• XA comes in through the CD input, and two minigames reverb it. Voice lines, announcer lines and movie audio reach the mix through the SPU’s CD input rather than a voice, at the volume the game sets there (one step under full scale while a line plays, muted between lines). The CD input’s own reverb send is off everywhere except the Baka Fighter duel and the Muscle Dome hub: their overlays turn it on at entry and off as a dome fight starts or the minigame exits, so the announcer rings through the room and the fight does not. The port follows the same switch.
• Not modelled: pitch modulation, noise and FM (Legaia uses none), and asynchronous DMA timing. The reverb network runs behind the hardware's 39-tap half-band FIR on both sides, so send content above 11 kHz is filtered out before the 22 kHz tank instead of folding back into it.

Measuring the port against retail

The audio-trace oracle compares which SPU voices are active, frame by frame, against a real emulator running the retail disc. Two retail capture shapes feed it: a single-cycle snapshot lifted from a mednafen save state's SPU section, and a multi-frame trace captured in PCSX-Redux. A retail frame converges when some engine frame's active-voice set covers it with every start address matching; a start-address or master-volume mismatch is a hard failure, and so is an engine trace that sounded nothing where retail had voices. CLI: legaia-engine audio-trace.

• A save state cannot say which voices belong to the score. A voice leaves its off phase on key-on and returns only when a release runs all the way down, so a save taken mid-playthrough reports nearly every voice non-off - the residue of every cue since boot. Deciding which voices the music is sounding needs the per-vsync trace.
• Compare the same track over the same stretch. An engine trace plays the track the scene's entry script selects; a retail save plays whatever the playthrough left loaded. Paired on one track and window, the two sides hold the same number of concurrent voices - nineteen at the peak of the measured track, which is exactly what its score decodes to.
• Every sounding note is one the port programs. Across the library's mednafen states - field, town, battle, summon, minigame, menu, ending - each sounding sequence voice's pitch, envelope words, left and right volume and reverb send is one the engine programs for the same track at the same sequence volume. The track, the volume and the mono setting are read off the state itself, not off its scene.
• Count key-ons, not envelope edges. A breakpoint census of every retail key-on matches the engine note for note on the measured field, battle, title and minigame states; the envelope a per-vsync capture records runs on the emulator's audio thread, not the emulated clock.

How we know

Full write-up: docs/subsystems/audio.md.