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

FunctionSignatureDescription
audio_init() → i32Initialize audio system. Returns 1 on success.
audio_shutdown()Stop all sounds and free resources
audio_init()
defer audio_shutdown()

Loading & Freeing

FunctionSignatureDescription
audio_load(str) → i32Load 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

FunctionSignatureDescription
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) → boolCheck 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

FunctionSignatureDescription
audio_set_volume(i32, f32)Set per-sound volume (0.0 - 1.0)
audio_get_volume(i32) → f32Get per-sound volume
audio_set_master_volume(f32)Set master volume (0.0 - 1.0)
audio_get_master_volume() → f32Get 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

LimitValue
Max loaded sounds64
Max simultaneous playback channels32
Max WAV file size64 MB
Supported formats8/16-bit PCM WAV, mono/stereo

Platform Notes

  • Windows: Uses waveOut API (winmm.lib, auto-linked via @link("winmm")). Volume scaling is done in software by mixing PCM data before submission. Looping uses the WOM_DONE callback to re-submit the buffer.
  • Linux/macOS: Stub implementation — audio_load returns -1, playback functions are no-ops. Future versions may add ALSA/PulseAudio/CoreAudio.
  • TCC: Fully supported on Windows.
  • Thread safety: The waveOut callback runs on a system thread. Avoid calling audio_free on a sound while it is playing — call audio_stop first.

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