π΅ Audio System
SDL3-backed sound effects with a fixed voice pool, per-source volume/pan/pitch and simple 2D distance attenuation. Music streaming is not implemented.
Overview#
AudioSystem opens one SDL3 playback device and owns a pool of AudioSource objects.
Each source wraps an SDL_AudioStream bound to the device:
- SFX β the whole clip is pushed into the stream. A free source is reused; when the
pool is exhausted,
playSFXreturnsnullptrand the sound is dropped. - Voices β
init(sfxChannelCount, musicChannelCount)sizes the SFX pool. The music channel count is accepted but unused;Stats::musicPlayingandmusicVolumeare alwaysfalse/0. - Spatial β a 2D listener position gives linear volume falloff and a pan value from the horizontal offset. There is no 3D attenuation, cone or Doppler.
AudioSystem is a plain engine service, not an ECS::ISystem: the host calls
update(dt) once per frame.
API#
namespace Caffeine::Audio {
struct AudioClip {
const u8* data = nullptr;
u64 size = 0;
u32 sampleRate = 44100;
u16 channels = 2;
u16 bitsPerSample = 16;
f32 duration = 0.0f;
};
struct AudioEmitter {
FixedString<128> clipPath;
f32 volume = 1.0f;
f32 maxDistance = 500.0f;
bool loop = false;
bool playOnSpawn = true;
bool spatial = true;
};
class AudioSource {
public:
void play();
void pause();
void stop();
void seek(f32 seconds);
void setVolume(f32 v); // clamped 0..1
void setPan(f32 pan); // clamped -1..1
void setPitch(f32 pitch); // stored 0.1..4; not applied by SDL
void setLoop(bool loop);
bool isPlaying() const;
bool isPaused() const;
bool isFree() const;
f32 currentTime() const;
f32 duration() const;
f32 volume() const;
f32 pan() const;
f32 pitch() const;
bool loop() const;
void tick(f32 dt);
};
class AudioSystem {
public:
bool init(u32 sfxChannelCount = 32, u32 musicChannelCount = 2);
void shutdown();
AudioClip* registerClip(const u8* data, u64 size,
u32 sampleRate = 44100, u16 channels = 2,
u16 bitsPerSample = 16, f32 duration = 0.0f);
AudioSource* playSFX(const AudioClip* clip,
f32 volume = 1.0f, f32 pan = 0.0f);
AudioSource* playSFXAt(const AudioClip* clip, Vec2 worldPos,
f32 maxDistance = 500.0f);
void setListenerPosition(Vec2 pos, Vec2 forward = {1.0f, 0.0f});
void setSourcePosition(AudioSource* source, Vec2 worldPos,
f32 maxDistance = 500.0f);
void setMasterVolume(f32 volume);
void setMasterPaused(bool paused);
void update(f64 dt);
bool isInitialized() const;
f32 masterVolume() const;
bool masterPaused() const;
Vec2 listenerPosition() const;
struct Stats {
u32 activeSFX;
u32 sfxPoolUsed;
u32 sfxPoolTotal;
bool musicPlaying;
f32 musicVolume;
};
Stats stats() const;
};
} // namespace Caffeine::Audio
The whole header is wrapped in #ifdef CF_HAS_SDL3; without SDL3 the types are not
available. registerClip does not copy the bytes: the caller owns the buffer for as
long as the clip is used.
setPitch stores a value but SDL3's audio stream gain path does not resample, so pitch
is currently informational only.
ECS audio component#
namespace Caffeine::Audio {
// Emitter data for a 2D sound in the world.
struct AudioEmitter {
FixedString<128> clipPath; // path to the SFX
f32 volume = 1.0f;
f32 maxDistance = 500.0f; // pixels
bool loop = false;
bool playOnSpawn = true;
bool spatial = true; // false = no attenuation
};
} // namespace Caffeine::Audio
AudioEmitter is a component in Caffeine::Audio, not Caffeine::Components. The
engine stores it with the entity; a runtime or tool is responsible for registering the
clip and calling playSFXAt.
Spatial audio#
distance = length(emitter.xy - listener.xy)
volume = clamp(1 - distance / maxDistance, 0, 1)
pan = clamp((emitter.x - listener.x) / maxDistance, -1, 1)
listener position βββΊ setListenerPosition()
emitter position βββΊ playSFXAt() or setSourcePosition()
playSFXAt applies volume and pan once, at start. setSourcePosition updates an
already-playing source; call it every frame for a moving emitter. forward in
setListenerPosition is currently ignored.
Exemplos de Uso#
Caffeine::Audio::AudioSystem audio;
audio.init(32, 2);
// bytes must stay alive while the clip is in use
static const u8 jumpPCM[64] = {};
auto* jumpSFX = audio.registerClip(jumpPCM, sizeof(jumpPCM), 44100, 2, 16, 0.5f);
// Non-positional SFX.
audio.playSFX(jumpSFX, 0.8f);
// Positional SFX relative to the listener.
audio.setListenerPosition(camera.position());
audio.playSFXAt(jumpSFX, {300.0f, 150.0f}, 500.0f);
// Per-frame upkeep: advances source timers and restarts looping clips.
audio.update(dt);
audio.setMasterVolume(0.7f);
audio.setMasterPaused(paused);
Design Decisions#
| Decision | Justification |
|---|---|
| Fixed source pool | No allocation while playing; predictable voice count |
| Whole SFX in the stream | Lowest latency for short sounds |
| No music streaming yet | musicChannelCount and the music stats are reserved |
update() on the main thread |
SDL's audio callback runs on its own thread; source state stays on the main thread |
| Linear 2D falloff | Cheap and predictable for side-scrollers and top-down games |
| Caller-owned PCM | registerClip avoids a copy and lets assets stream from their own storage |
Acceptance Criteria#
tests/test_audio.cpp covers:
- [x] Default
AudioClip,AudioEmitterandAudioSystemstate - [x]
initis idempotent;shutdownon an uninitialised system is safe - [x] Master volume clamps to 0..1
- [x] Listener position and pause flag are stored before init
- [x]
playSFX(nullptr)returnsnullptr - [x]
registerClipreturns a stable clip pointer - [x] Distance attenuation reaches zero at
maxDistanceand full volume at the centre - [x]
setSourcePosition(nullptr)is a no-op - [x]
updateandshutdownafter init do not crash - [x]
stats().sfxPoolUsedtracks active sources
There is no crossfade or music-streaming test because that feature is not implemented.
Dependencies#
- Upstream: SDL3 audio (
SDL_AudioStream), Asset Manager - Downstream: gameplay code that reacts to events and calls
playSFXAt
π Related Topics#
| Topic | Description |
|---|---|
| ECS Core | Components and queries |
| Assets & Pipeline | How audio bytes are loaded before registerClip |
References#
src/caffeine/audio/AudioSystem.hppβ device, sources and spatial helperssrc/caffeine/audio/AudioComponents.hppβAudioClipandAudioEmittertests/test_audio.cppβ behaviour suite- SDL3 audio documentation