|
Game Audio Module
A C++ audio system using miniaudio with Python bindings
|
Central manager for all audio functionality. More...
#include <audio_manager.h>
Public Member Functions | |
| bool | IsInitialized () const |
| Check if the audio system is initialized and running. | |
System Lifecycle | |
| bool | Initialize () |
| Initialize the audio system. | |
| void | Shutdown () |
| Shut down the audio system. | |
Track Management | |
| TrackHandle | CreateTrack () |
| Create a new audio track. | |
| void | DestroyTrack (TrackHandle track) |
| Destroy an audio track. | |
| void | PlayTrack (TrackHandle track) |
| Start playing an audio track. | |
| void | StopTrack (TrackHandle track) |
| Stop playing an audio track. | |
Layer Operations | |
| void | AddLayer (TrackHandle track, const string &layerName, const string &filepath, GroupHandle group=GroupHandle::Invalid()) |
| Add an audio layer to a track. | |
| void | RemoveLayer (TrackHandle track, const string &layerName) |
| Remove a layer from a track. | |
| void | SetLayerVolume (TrackHandle track, const string &layerName, float volume) |
| Set the volume of a specific layer. | |
| void | FadeLayer (TrackHandle track, const string &layerName, float targetVolume, std::chrono::milliseconds duration) |
| Fade a layer's volume to a target value over time. | |
Group Operations | |
| GroupHandle | CreateGroup () |
| Create a new audio group. | |
| void | DestroyGroup (GroupHandle group) |
| Destroy an audio group. | |
| void | SetGroupVolume (GroupHandle group, float volume) |
| Set the volume for an entire audio group. | |
| float | GetGroupVolume (GroupHandle group) const |
| Get the current volume for an audio group. | |
| void | FadeGroup (GroupHandle group, float targetVolume, std::chrono::milliseconds duration) |
| Fade a group's volume to a target value over time. | |
Sound Operations | |
| SoundHandle | LoadSound (const string &filepath) |
| Load a sound from a file. | |
| SoundHandle | LoadSound (const string &filepath, GroupHandle group) |
| Load a sound from a file and assign it to a group. | |
| void | DestroySound (SoundHandle sound) |
| Destroy a previously loaded sound. | |
| void | PlaySound (SoundHandle sound) |
| Play a sound. | |
| void | PlaySound (SoundHandle sound, const Vec3 &position) |
| Play a sound at a specific position. | |
| void | StopSound (SoundHandle sound) |
| Stop a currently playing sound. | |
| void | SetSoundVolume (SoundHandle sound, float volume) |
| Set the volume of a sound. | |
| void | SetSoundPitch (SoundHandle sound, float pitch) |
| Set the pitch of a sound for its next playback. | |
| void | SetSoundLooping (SoundHandle sound, bool should_loop) |
| Set whether a sound should loop. | |
| bool | IsSoundPlaying (SoundHandle sound) const |
| Check if a sound is currently playing. | |
| void | PlayRandomSoundFromFolder (const string &folderPath, GroupHandle group=GroupHandle::Invalid()) |
| Play a random sound from a folder. | |
Spatial Audio (3D Positioning) | |
| void | SetListenerPosition (const Vec3 &position, uint32_t listenerIndex=0) |
| Set the listener position in 3D space. | |
| Vec3 | GetListenerPosition (uint32_t listenerIndex=0) const |
| Get the listener position. | |
| void | SetListenerDirection (const Vec3 &direction, uint32_t listenerIndex=0) |
| Set the listener direction (forward vector) | |
| Vec3 | GetListenerDirection (uint32_t listenerIndex=0) const |
| Get the listener direction. | |
| void | SetListenerUp (const Vec3 &up, uint32_t listenerIndex=0) |
| Set the listener up vector. | |
| Vec3 | GetListenerUp (uint32_t listenerIndex=0) const |
| Get the listener up vector. | |
| void | SetSoundPosition (SoundHandle sound, const Vec3 &position) |
| Set the 3D position of a sound. | |
| Vec3 | GetSoundPosition (SoundHandle sound) const |
| Get the 3D position of a sound. | |
| void | SetSoundMinDistance (SoundHandle sound, float minDistance) |
| Set the minimum distance for distance attenuation. | |
| float | GetSoundMinDistance (SoundHandle sound) const |
| Get the minimum distance of a sound. | |
| void | SetSoundMaxDistance (SoundHandle sound, float maxDistance) |
| Set the maximum distance for distance attenuation. | |
| float | GetSoundMaxDistance (SoundHandle sound) const |
| Get the maximum distance of a sound. | |
| void | SetSoundRolloff (SoundHandle sound, float rolloff) |
| Set the rolloff factor for distance attenuation. | |
| float | GetSoundRolloff (SoundHandle sound) const |
| Get the rolloff factor of a sound. | |
| void | SetSoundSpatializationEnabled (SoundHandle sound, bool enabled) |
| Enable or disable spatialization for a sound. | |
| bool | IsSoundSpatializationEnabled (SoundHandle sound) const |
| Check if spatialization is enabled for a sound. | |
Static Public Member Functions | |
| static AudioManager & | GetInstance () |
| Get the singleton instance of the AudioManager. | |
Private Member Functions | |
| AudioManager () | |
| Constructor - private due to singleton pattern. | |
| AudioManager (const AudioManager &)=delete | |
| ~AudioManager () | |
| Destructor. | |
| void | EnsureInitialized () const |
| Ensures the audio system is initialized before use. | |
| AudioManager & | operator= (const AudioManager &)=delete |
Internal Handle Management | |
| TrackHandle | NextTrackHandle () |
| Generate a new track handle. | |
| GroupHandle | NextGroupHandle () |
| Generate a new group handle. | |
| SoundHandle | NextSoundHandle () |
| Generate a new sound handle. | |
Private Attributes | |
Resource Storage | |
| unique_ptr< AudioSystem > | audio_system_ |
| Core audio system. | |
| unordered_map< TrackHandle, unique_ptr< AudioTrack > > | tracks_ |
| Track storage. | |
| unordered_map< GroupHandle, unique_ptr< AudioGroup > > | groups_ |
| Group storage. | |
| unordered_map< SoundHandle, unique_ptr< Sound > > | sounds_ |
| Sound storage. | |
| unordered_map< string, std::vector< SoundHandle > > | folder_sounds_ |
| Cached sounds per folder. | |
Threading | |
| atomic< bool > | running_ {false} |
| Flag indicating if audio system is running. | |
| thread | update_thread_ |
| Thread for audio updates. | |
| mutex | resource_mutex_ |
| Mutex for thread-safe resource access (mutable for const methods) | |
| std::mt19937 | rng_ {std::random_device{}()} |
| RNG for random playback. | |
Handle Counters | |
| atomic< uint32_t > | next_track_handle_ {1} |
| Counter for generating unique track handles. | |
| atomic< uint32_t > | next_group_handle_ {1} |
| Counter for generating unique group handles. | |
| atomic< uint32_t > | next_sound_handle_ {1} |
| Counter for generating unique sound handles. | |
System Control | |
| static void | SetLogLevel (LogLevel level) |
| Set the global audio log level (runtime). | |
| static LogLevel | GetLogLevel () |
| Get the current audio log level. | |
| void | SetMasterVolume (float volume) |
| Set the master volume for all audio. | |
| float | GetMasterVolume () const |
| Get the current master volume level. | |
Central manager for all audio functionality.
The AudioManager class provides a singleton interface for all audio operations. It manages audio tracks, groups, and individual sounds, providing a high-level API for game code to interact with the audio system.
This class handles resource management, playback control, volume adjustments, and other audio operations. It is the only class that should be directly accessed by game code.
@thread_safety All public methods are thread-safe and can be called from any thread. The internal update thread runs at ~60Hz and updates fading/volume transitions. All resource access is protected by internal mutexes.
|
private |
Constructor - private due to singleton pattern.
|
private |
Destructor.
|
privatedelete |
| void audio::AudioManager::AddLayer | ( | TrackHandle | track, |
| const string & | layerName, | ||
| const string & | filepath, | ||
| GroupHandle | group = GroupHandle::Invalid() |
||
| ) |
Add an audio layer to a track.
Layers are individual sounds that play simultaneously within a track. They can be controlled individually for volume and transitions.
| track | Handle to the track |
| layerName | Name identifier for the layer (unique within the track) |
| filepath | Path to the audio file |
| group | Optional handle of the group this layer should belong to (invalid = default/master) |
| InvalidHandleException | If the track handle is invalid or the group handle is invalid |
| FileLoadException | If the audio file cannot be loaded |
| GroupHandle audio::AudioManager::CreateGroup | ( | ) |
Create a new audio group.
Audio groups allow for collective control of multiple sounds. Groups are referenced by handle; names are not part of the public API.
| AudioException | If group creation fails |
| TrackHandle audio::AudioManager::CreateTrack | ( | ) |
Create a new audio track.
Audio tracks can contain multiple layers of audio that play simultaneously, with individual volume control for each layer.
| void audio::AudioManager::DestroyGroup | ( | GroupHandle | group | ) |
Destroy an audio group.
| group | Handle to the group to destroy |
| void audio::AudioManager::DestroySound | ( | SoundHandle | sound | ) |
Destroy a previously loaded sound.
| sound | Handle to the sound to destroy |
| void audio::AudioManager::DestroyTrack | ( | TrackHandle | track | ) |
Destroy an audio track.
This releases all resources associated with the track.
| track | Handle to the track to destroy |
|
private |
Ensures the audio system is initialized before use.
| NotInitializedException | If Initialize() has not been called |
| void audio::AudioManager::FadeGroup | ( | GroupHandle | group, |
| float | targetVolume, | ||
| std::chrono::milliseconds | duration | ||
| ) |
Fade a group's volume to a target value over time.
| group | Handle to the group |
| targetVolume | Target volume level (0.0 to 1.0) |
| duration | Duration of the fade in milliseconds |
| void audio::AudioManager::FadeLayer | ( | TrackHandle | track, |
| const string & | layerName, | ||
| float | targetVolume, | ||
| std::chrono::milliseconds | duration | ||
| ) |
Fade a layer's volume to a target value over time.
| track | Handle to the track |
| layerName | Name of the layer |
| targetVolume | Target volume level (0.0 to 1.0) |
| duration | Duration of the fade in milliseconds |
| float audio::AudioManager::GetGroupVolume | ( | GroupHandle | group | ) | const |
Get the current volume for an audio group.
| group | Handle to the group |
|
static |
Get the singleton instance of the AudioManager.
| Vec3 audio::AudioManager::GetListenerDirection | ( | uint32_t | listenerIndex = 0 | ) | const |
Get the listener direction.
| listenerIndex | Index of the listener (default 0) |
| Vec3 audio::AudioManager::GetListenerPosition | ( | uint32_t | listenerIndex = 0 | ) | const |
Get the listener position.
| listenerIndex | Index of the listener (default 0) |
| Vec3 audio::AudioManager::GetListenerUp | ( | uint32_t | listenerIndex = 0 | ) | const |
Get the listener up vector.
| listenerIndex | Index of the listener (default 0) |
|
static |
Get the current audio log level.
| float audio::AudioManager::GetMasterVolume | ( | ) | const |
Get the current master volume level.
| float audio::AudioManager::GetSoundMaxDistance | ( | SoundHandle | sound | ) | const |
Get the maximum distance of a sound.
| sound | Handle to the sound |
| InvalidHandleException | If the sound handle is invalid |
| float audio::AudioManager::GetSoundMinDistance | ( | SoundHandle | sound | ) | const |
Get the minimum distance of a sound.
| sound | Handle to the sound |
| InvalidHandleException | If the sound handle is invalid |
| Vec3 audio::AudioManager::GetSoundPosition | ( | SoundHandle | sound | ) | const |
Get the 3D position of a sound.
| sound | Handle to the sound |
| InvalidHandleException | If the sound handle is invalid |
| float audio::AudioManager::GetSoundRolloff | ( | SoundHandle | sound | ) | const |
Get the rolloff factor of a sound.
| sound | Handle to the sound |
| InvalidHandleException | If the sound handle is invalid |
| bool audio::AudioManager::Initialize | ( | ) |
Initialize the audio system.
This function initializes the underlying audio system, including the miniaudio engine. It must be called before any other audio operations.
|
inline |
Check if the audio system is initialized and running.
| bool audio::AudioManager::IsSoundPlaying | ( | SoundHandle | sound | ) | const |
Check if a sound is currently playing.
| sound | Handle to the sound |
| bool audio::AudioManager::IsSoundSpatializationEnabled | ( | SoundHandle | sound | ) | const |
Check if spatialization is enabled for a sound.
| sound | Handle to the sound |
| InvalidHandleException | If the sound handle is invalid |
| SoundHandle audio::AudioManager::LoadSound | ( | const string & | filepath | ) |
Load a sound from a file.
| filepath | Path to the audio file |
| FileLoadException | If the file cannot be found or loaded |
| SoundHandle audio::AudioManager::LoadSound | ( | const string & | filepath, |
| GroupHandle | group | ||
| ) |
Load a sound from a file and assign it to a group.
| filepath | Path to the audio file |
| group | Handle to the audio group to assign the sound to |
| FileLoadException | If the file cannot be found or loaded |
|
inlineprivate |
Generate a new group handle.
|
inlineprivate |
Generate a new sound handle.
|
inlineprivate |
Generate a new track handle.
|
privatedelete |
| void audio::AudioManager::PlayRandomSoundFromFolder | ( | const string & | folderPath, |
| GroupHandle | group = GroupHandle::Invalid() |
||
| ) |
Play a random sound from a folder.
Loads all .wav files from the specified folder and plays one randomly. Sounds are cached after first load for efficiency.
| folderPath | Path to the folder containing sound files |
| group | Optional group handle to assign the sounds to |
| AudioException | If the folder path is empty |
| FileLoadException | If the selected sound file cannot be loaded or initialized for playback |
| void audio::AudioManager::PlaySound | ( | SoundHandle | sound | ) |
Play a sound.
| sound | Handle to the sound to play |
| InvalidHandleException | If the sound handle is invalid |
| FileLoadException | If the sound file cannot be loaded or initialized for playback |
Play a sound
Starts playback of the sound using its current position.
| sound | Handle to the sound |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::PlaySound | ( | SoundHandle | sound, |
| const Vec3 & | position | ||
| ) |
Play a sound at a specific position.
Starts playback of the sound at the specified position. This allows multiple overlapping spatialized sounds from the same audio file to play at different positions simultaneously (e.g., multiple gunshots).
The position is only applied to this new playback instance. Existing instances keep their positions unchanged.
| sound | Handle to the sound |
| position | 3D position for this playback instance |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::PlayTrack | ( | TrackHandle | track | ) |
Start playing an audio track.
All layers in the track will begin playing.
| track | Handle to the track to play |
| InvalidHandleException | If the track handle is invalid |
| FileLoadException | If any layer's sound file cannot be loaded or initialized for playback |
| void audio::AudioManager::RemoveLayer | ( | TrackHandle | track, |
| const string & | layerName | ||
| ) |
Remove a layer from a track.
| track | Handle to the track |
| layerName | Name of the layer to remove |
| void audio::AudioManager::SetGroupVolume | ( | GroupHandle | group, |
| float | volume | ||
| ) |
Set the volume for an entire audio group.
This affects all sounds assigned to the group.
| group | Handle to the group |
| volume | Volume level (0.0 to 1.0) |
| InvalidHandleException | If the group handle is invalid |
| void audio::AudioManager::SetLayerVolume | ( | TrackHandle | track, |
| const string & | layerName, | ||
| float | volume | ||
| ) |
Set the volume of a specific layer.
| track | Handle to the track |
| layerName | Name of the layer |
| volume | Volume level (0.0 to 1.0) |
| void audio::AudioManager::SetListenerDirection | ( | const Vec3 & | direction, |
| uint32_t | listenerIndex = 0 |
||
| ) |
Set the listener direction (forward vector)
The direction vector represents which way the listener is facing. Should be normalized.
| direction | Forward direction vector (should be normalized) |
| listenerIndex | Index of the listener (default 0) |
| void audio::AudioManager::SetListenerPosition | ( | const Vec3 & | position, |
| uint32_t | listenerIndex = 0 |
||
| ) |
Set the listener position in 3D space.
The listener represents the "ears" of the player/camera. All spatialized sounds are positioned relative to the listener.
Coordinate System: Uses OpenGL/miniaudio convention:
For 2D games (Node2D): Simply use z=0:
To use with game engines (e.g., Basilisk Engine nodes): Simply convert your engine's position vector to Vec3:
Performance: This method is optimized to skip updates when the position hasn't changed, so it's safe to call every frame. The mutex overhead is minimal, and spatial audio requires frequent updates for accurate positioning.
| position | 3D position of the listener |
| listenerIndex | Index of the listener (default 0) |
| void audio::AudioManager::SetListenerUp | ( | const Vec3 & | up, |
| uint32_t | listenerIndex = 0 |
||
| ) |
Set the listener up vector.
The up vector defines the orientation of the listener. Typically (0, 1, 0) for a standard Y-up coordinate system.
| up | Up vector (should be normalized) |
| listenerIndex | Index of the listener (default 0) |
|
static |
Set the global audio log level (runtime).
Logging defaults to Off. Use this method to enable logging output.
| void audio::AudioManager::SetMasterVolume | ( | float | volume | ) |
Set the master volume for all audio.
| volume | Volume level (0.0 to 1.0) |
| void audio::AudioManager::SetSoundLooping | ( | SoundHandle | sound, |
| bool | should_loop | ||
| ) |
Set whether a sound should loop.
| sound | Handle to the sound |
| should_loop | Whether the sound should loop continuously |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::SetSoundMaxDistance | ( | SoundHandle | sound, |
| float | maxDistance | ||
| ) |
Set the maximum distance for distance attenuation.
At distances beyond maxDistance, the sound will be at minimum gain.
| sound | Handle to the sound |
| maxDistance | Maximum distance (must be > minDistance) |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::SetSoundMinDistance | ( | SoundHandle | sound, |
| float | minDistance | ||
| ) |
Set the minimum distance for distance attenuation.
At distances less than minDistance, the sound will be at full volume. Beyond minDistance, volume will attenuate based on the attenuation model.
| sound | Handle to the sound |
| minDistance | Minimum distance (must be > 0) |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::SetSoundPitch | ( | SoundHandle | sound, |
| float | pitch | ||
| ) |
Set the pitch of a sound for its next playback.
| sound | Handle to the sound |
| pitch | Pitch multiplier (1.0 = normal, 0.5 = half speed, 2.0 = double speed) |
| void audio::AudioManager::SetSoundPosition | ( | SoundHandle | sound, |
| const Vec3 & | position | ||
| ) |
Set the 3D position of a sound.
Sets the position for the sound. The sound will be spatialized relative to the listener position.
Coordinate System: Uses OpenGL/miniaudio convention:
For 2D games (Node2D): Simply use z=0:
To use with game engines (e.g., Basilisk Engine nodes): Simply convert your engine's node position to Vec3:
| sound | Handle to the sound |
| position | 3D position of the sound |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::SetSoundRolloff | ( | SoundHandle | sound, |
| float | rolloff | ||
| ) |
Set the rolloff factor for distance attenuation.
Higher values mean faster volume dropoff with distance. Typical values: 1.0 (linear), 2.0 (inverse square)
| sound | Handle to the sound |
| rolloff | Rolloff factor (typically 1.0 to 2.0) |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::SetSoundSpatializationEnabled | ( | SoundHandle | sound, |
| bool | enabled | ||
| ) |
Enable or disable spatialization for a sound.
| sound | Handle to the sound |
| enabled | Whether to enable spatialization |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::SetSoundVolume | ( | SoundHandle | sound, |
| float | volume | ||
| ) |
Set the volume of a sound.
| sound | Handle to the sound |
| volume | Volume level (0.0 to 1.0) |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::Shutdown | ( | ) |
Shut down the audio system.
This function cleans up all audio resources and shuts down the miniaudio engine. It should be called before application exit.
| void audio::AudioManager::StopSound | ( | SoundHandle | sound | ) |
Stop a currently playing sound.
| sound | Handle to the sound to stop |
| InvalidHandleException | If the sound handle is invalid |
| void audio::AudioManager::StopTrack | ( | TrackHandle | track | ) |
Stop playing an audio track.
All layers in the track will stop playing.
| track | Handle to the track to stop |
| InvalidHandleException | If the track handle is invalid |
|
private |
Core audio system.
|
private |
Cached sounds per folder.
|
private |
Group storage.
|
private |
Counter for generating unique group handles.
|
private |
Counter for generating unique sound handles.
|
private |
Counter for generating unique track handles.
|
mutableprivate |
Mutex for thread-safe resource access (mutable for const methods)
|
private |
RNG for random playback.
|
private |
Flag indicating if audio system is running.
|
private |
Sound storage.
|
private |
Track storage.
|
private |
Thread for audio updates.