Audio¶

This page documents the audio system: SFX IDs, usage hotspots, data labels, and the runtime entry struct shared by SFX and music.

Playback rules¶

Recovered sfx_play and sfx_play_panned reject a sound while that native ID's cooldown is positive: 0.05 seconds normally, 0.44 seconds for either flamer ID. audio_update subtracts frame_dt_copy after playback requests, retaining a negative zero-crossing remainder. Sound selection has already consumed RNG before this admission check. There is no global four-event cutoff.

Panned playback computes ((camera_x + position_x) / screen_width - 0.5) * 1700, truncates to an integer, and clamps to ±10000 DirectSound hundredths of a dB. Positive values attenuate the left channel; negative values attenuate the right. Demo playback multiplies the requested volume by 0.7. The volume setter maps the scalar through (volume + 2) * (1 / 3) before converting it to DirectSound attenuation. These operations use native float32 constants and x87 PC=24; __ftol at 0x00461054 sets truncation mode before converting, including the Reflex Boost playback frequency calculation.

The Python backend converts channel attenuation to raylib 5.5's pan law in src/grim/audio_math.py. It retains the port's explicit zero-volume mute and per-voice gain state. Decoded sample ownership is shared by asset, while cooldowns remain separate for distinct native IDs. The port keeps its bounded voice pool rather than reproducing DirectSound's 16 buffers per native entry.

Music keeps selection and mute/fade intent even at zero master volume. The Python backend pauses streams at zero and resumes them without choosing a new tune. Stopped unmuted streams are started explicitly. Game-over and quest-failed screens repeatedly request shortie_monk while active; quest completion starts crimsonquest with a fade-in. A previously muted track must finish fading before an exclusive-play request can unmute it.

Python resource loading validates every decoded handle before publication and rolls back partial acquisition. An owned sample releases aliases before its source; a music entry retains encoded bytes until decoder teardown. Audio shutdown closes the device only when that state opened it.

See the deterministic session for deferred sound requests and cooldown timing. The backend conversion follows raylib 5.5 MixAudioFrames and the DirectSound pan and volume contracts.

Entry struct (audio_entry_t)¶

SFX and music tracks share the same 0x84-byte entry layout. The runtime uses this struct for both sfx_entry_table and music_entry_table.

Offsets are relative to the entry base and match the initialization logic in wav_parse_into_entry, sfx_entry_load_ogg, and music_entry_load_ogg.

Notes:

• Static/one-shot SFX entries leave vorbis_stream null and use the 16 voice buffers at 0x24 for overlapping playback.

• Music tracks set vorbis_stream and use a single streaming buffer at 0x24.

• The entry size is 0x84 bytes; table strides for sfx_entry_table and music_entry_table use this size.

• sfx_voice_table (0x004c3e80) is a 0x20-entry table of DirectSound buffer pointers; it is only zeroed during sfx_system_init, so the role remains inferred.

Memory-backed Vorbis stream¶

The native vorbis_stream_t is now recovered through its complete leaf surface. Its leading layout is an ov_callbacks record at +0x00, an OggVorbis_File at +0x10, the current bitstream index at +0x2e0, total PCM bytes at +0x2e4, source-data offset at +0x2e8, the owned source allocation at +0x2ec, and a copied 32-byte vorbis_info at +0x2f0.

The owned allocation has an eight-byte prefix followed by inline OGG data:

The callback policy contains several native quirks that ports should retain:

• reads reset an exhausted cursor to zero, clamp the copy to remaining bytes, but advance the cursor by the full requested size * count;
• seek returns 1 for every origin, treats non-SEEK_SET/SEEK_END origins as relative, and implements end-relative seek as size - offset;
• the callback close is a no-op returning 1; vorbis_stream_t::close owns the allocation and frees it before ov_clear;
• PCM reads request signed little-endian 16-bit output and clamp negative ov_read results to zero.

Opening copies vorbis_info, calculates PCM bytes as ov_pcm_total * channels * 16 / 8, and records the callback cursor after the Vorbis headers have been consumed.

SFX ID map¶

Derived from audio_init_sfx (0x0043caa0). sfx_load_sample (0x0043c740) returns the SFX id for each .ogg file and stores it in a global variable.

Labels are mirrored into analysis/ghidra/maps/data_map.json and applied with ApplyDataMap.java during headless analysis. Duplicate IDs that point at the same .ogg file use _alt suffixes to keep names unique.

Aliases¶

Alias entries are direct copies of another id in the init function.

Playlist/runtime globals¶

Recovered data labels for exclusive music-play path:

• music_playlist_entry_count (0x004cc8d0): number of queued entries in music_playlist (written by music_queue_track).
• music_playlist_randomized_latch (0x004cc8d4): latch used by sfx_play_exclusive(music_track_extra_0) to avoid re-randomizing every call.
• audio_assets_loaded_count (0x004cc8d8): increments on sfx_load_sample/music_load_track; displayed on startup loading UI ("Grim SFX: %d/%d" line).

Runtime callsite clusters (2026-02-06 capture)¶

From analysis/frida/gameplay_state_capture_summary.json (694s gameplay-heavy run):

• quest_results_screen_update -> sfx_play_exclusive(5) in 3989/3989 calls.
• game_over_screen_update -> sfx_play_exclusive(1) in 714/716 calls.
• quest_failed_screen_update -> sfx_play_exclusive(1) in 482/483 calls.
• ui_button_update -> sfx_play(63) in 38/38 calls.
• ui_element_update -> mostly sfx_play(64) (95/108) with secondary 63 (13/108).

Gameplay-heavy panned clusters (same capture):

• player_update: dominant IDs 34 and 37 (plus 30), matching weapon-fire cadence.
• projectile_update: dominant IDs 54/51/53/55/52/50 (projectile hit/explosion family).
• player_take_damage: IDs 0/2/1 (player hurt variants).
• player_start_reload: mostly ID 35 (15/20).
• bonus_apply: dominant sfx_play ID 62; panned side effects include 56/59/60.
• weapon_assign_player: panned cluster led by 31 with secondary 35/49.

Unreferenced entries (in sfx.paq)¶

These files exist in sfx.paq, but are not loaded by audio_init_sfx in 1.9.93:

• flamer_fire_start.ogg
• trooper_die_04.ogg
• trooper_inPain_04.ogg