Microaudio Module
GX includes a microaudio module for simple WAV sound playback. It is a
zero-dependency, header-only C library that uses the native platform audio API
(waveOut on Windows). Designed for games and tools that need sound effects
and background music without pulling in a large audio framework.
Prerequisites
No external dependencies. On Windows, links against winmm automatically.
Linux/macOS stubs are provided (playback not yet implemented on those platforms).
Usage
import microaudio.audio
Build with -I modules:
gx myapp.gx -I modules -o myapp.exe
Quick Example
import microaudio.audio
fn main() {
audio_init()
defer audio_shutdown()
var sfx = audio_load("explosion.wav")
var music = audio_load("background.wav")
audio_set_volume(sfx, 0.8)
audio_play(sfx)
audio_set_volume(music, 0.4)
audio_play_loop(music)
// ... game loop ...
audio_stop_all()
audio_free(sfx)
audio_free(music)
}
Initialization
| Function | Signature | Description |
|---|---|---|
audio_init | () → i32 | Initialize audio system. Returns 1 on success. |
audio_shutdown | () | Stop all sounds and free resources |
audio_init()
defer audio_shutdown()
Loading & Freeing
| Function | Signature | Description |
|---|---|---|
audio_load | (str) → i32 | Load WAV file, returns sound ID (0-63). Returns -1 on error. |
audio_free | (i32) | Free a loaded sound by ID |
var jump_sfx = audio_load("assets/jump.wav")
if (jump_sfx < 0) {
print("Failed to load sound!\n")
}
// When done:
audio_free(jump_sfx)
Supported formats: 8-bit and 16-bit PCM WAV, mono or stereo, any sample rate. Max file size: 64 MB. Up to 64 sounds can be loaded simultaneously.
Playback
| Function | Signature | Description |
|---|---|---|
audio_play | (i32) | Play sound once |
audio_play_loop | (i32) | Play sound on loop |
audio_stop | (i32) | Stop all instances of a sound |
audio_is_playing | (i32) → bool | Check if sound is playing |
audio_stop_all | () | Stop all sounds |
// Play hit sound on collision
if (hit_detected) {
audio_play(hit_sfx)
}
// Loop background music
audio_play_loop(bgm)
// Stop music when entering menu
audio_stop(bgm)
Up to 32 sounds can play simultaneously. If all channels are busy, the oldest non-looping channel is stolen for the new sound.
Volume
| Function | Signature | Description |
|---|---|---|
audio_set_volume | (i32, f32) | Set per-sound volume (0.0 - 1.0) |
audio_get_volume | (i32) → f32 | Get per-sound volume |
audio_set_master_volume | (f32) | Set master volume (0.0 - 1.0) |
audio_get_master_volume | () → f32 | Get master volume |
Final volume = sound_volume * master_volume. Both default to 1.0.
// Quiet background music, louder effects
audio_set_master_volume(0.8)
audio_set_volume(bgm, 0.3)
audio_set_volume(explosion, 1.0)
// Mute all audio
audio_set_master_volume(0.0)
Common Patterns
Sound Effects in a Game Loop
When a program uses both, import raylib before microaudio.audio. On Windows
the audio header pulls in PlaySound from the system headers, which clashes
with raylib’s own PlaySound if it comes first.
import raylib.core
import raylib.input
import microaudio.audio
fn main() {
InitWindow(800, 600, "Sound Demo")
audio_init()
defer audio_shutdown()
var shoot = audio_load("assets/shoot.wav")
var jump = audio_load("assets/jump.wav")
audio_set_volume(shoot, 0.7)
while (!WindowShouldClose()) {
if (IsKeyPressed(KEY_SPACE)) {
audio_play(jump)
}
if (IsMouseButtonPressed(MOUSE_BUTTON_LEFT)) {
audio_play(shoot)
}
BeginDrawing()
// ... render ...
EndDrawing()
}
CloseWindow()
}
Background Music with Fade
var bgm = audio_load("music.wav")
audio_set_volume(bgm, 0.0)
audio_play_loop(bgm)
// Fade in over time
var vol: f32 = 0.0
while (vol < 1.0) {
vol = vol + 0.01
audio_set_volume(bgm, vol)
time.gx_time_sleep_ms(16)
}
Checking Playback State
audio_play(fanfare)
// Wait until sound finishes
while (audio_is_playing(fanfare)) {
time.gx_time_sleep_ms(10)
}
print("Sound finished!\n")
Limits
| Limit | Value |
|---|---|
| Max loaded sounds | 64 |
| Max simultaneous playback channels | 32 |
| Max WAV file size | 64 MB |
| Supported formats | 8/16-bit PCM WAV, mono/stereo |
Platform Notes
- Windows: Uses
waveOutAPI (winmm.lib, auto-linked via@link("winmm")). Volume scaling is done in software by mixing PCM data before submission. Looping uses theWOM_DONEcallback to re-submit the buffer. - Linux/macOS: Stub implementation —
audio_loadreturns -1, playback functions are no-ops. Future versions may add ALSA/PulseAudio/CoreAudio. - TCC: Fully supported on Windows.
- Thread safety: The
waveOutcallback runs on a system thread. Avoid callingaudio_freeon a sound while it is playing — callaudio_stopfirst.
Module Layout
modules/
microaudio/
c/
microaudio.h Header-only C implementation (WAV parser, waveOut, mixing)
gx/
audio.gx Module: GX wrapper functions around ma_* C API