Forge Audio Pool

forge-audio-pool

Add fire-and-forget sound effect playback using ForgeAudioPool and smooth volume transitions using the fade envelope on ForgeAudioSource. Based on [Audio Lesson 02](../../../lessons/audio/02-sound-effects/).

When to use

• Playing the same sound multiple times with overlap (polyphony)
• One-shot sound effects that should auto-clean-up when finished
• Starting or stopping sounds without audible clicks (fade-in / fade-out)
• Ambient loops that toggle smoothly with a volume ramp

Source pool pattern

#include "audio/forge_audio.h"

/* In app_state */
ForgeAudioPool pool;
ForgeAudioBuffer sfx_buffer;

/* In SDL_AppInit */
forge_audio_pool_init(&pool);
forge_audio_load_wav("assets/audio/impact.wav", &sfx_buffer);

/* Fire-and-forget: each call allocates a new slot (up to 32) */
int slot = forge_audio_pool_play(&pool, &sfx_buffer, 1.0f, false);
if (slot = 0) {
    ForgeAudioSource *src = forge_audio_pool_get(&pool, slot);
    forge_audio_source_fade_in(src, 0.3f);
}

/* Update fades on all pool sources each frame */
for (int i = 0; i < FORGE_AUDIO_POOL_MAX_SOURCES; i++) {
    if (pool.sources[i].playing) {
        forge_audio_source_fade_update(&pool.sources[i], dt);
    }
}

Ambient loop with fade toggle

For a single looping source managed outside the pool (direct fade control):

/* In app_state */
ForgeAudioSource ambient;
bool ambient_active;

/* Toggle on key press */
if (ambient_active) {
    forge_audio_source_fade_out(&ambient, fade_duration);
    ambient_active = false;
} else {
    if (!ambient.playing) forge_audio_source_reset(&ambient);
    forge_audio_source_fade_in(&ambient, fade_duration);
    ambient_active = true;
}

Common mistakes

• Forgetting fade_update — The fade does not advance automatically.

Call forge_audio_source_fade_update(src, dt) once per frame for every source that might be fading.

• Calling fade_update per mix call — Call it per frame, not per mix

invocation. The rate is in units per second, scaled by dt.

• Not zeroing the mix buffer — forge_audio_pool_mix() is additive.

Always memset(out, 0, ...) before the first mix call each frame.

• Ignoring pool_play return value — Returns -1 when full. Decide whether

to drop the sound or steal an existing slot.

API reference

| Function | Purpose | |---|---| | forge_audio_pool_init | Zero all 32 slots | | forge_audio_pool_play | Play buffer in first idle slot → index or -1 | | forge_audio_pool_get | Get source pointer at index → ForgeAudioSource* or NULL | | forge_audio_pool_mix | Mix active sources, reclaim finished | | forge_audio_pool_stop_all | Stop everything | | forge_audio_pool_active_count | Count of playing sources | | forge_audio_source_fade | Start fade toward target over duration | | forge_audio_source_fade_in | 0→1 fade, starts playback | | forge_audio_source_fade_out | Current→0 fade, auto-stops | | forge_audio_source_fade_update | Advance fade by dt seconds |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Nebulavenus
• Source: Nebulavenus/forge-gpu
• License: Zlib

Install and usage instructions live in the source repository linked above.