Overview
Finewave is the low-level audio engine powering Atlas’s audio capabilities. It provides direct control over audio data loading, source management, 3D spatial audio, and effects processing.Most users should use the high-level AudioPlayer component from the Atlas Audio API. Use Finewave directly only when you need fine-grained control.
AudioEngine
Central audio engine that manages the audio system and global audio settings.Methods
Initializes the audio engine. Must be called before using any audio features.Returns: True if initialization succeeded, false otherwise
Shuts down the audio engine and releases resources.
Listener Configuration
Sets the position of the audio listener in 3D space. The listener represents where the player/camera is located.Parameters:
position(Position3d): New listener position
Sets the orientation of the audio listener.Parameters:
forward(Magnitude3d): Forward direction vectorup(Normal3d): Up direction vector
Sets the velocity of the audio listener for Doppler effects.Parameters:
velocity(Magnitude3d): Listener velocity vector
Global Settings
Sets the master volume for all audio.Parameters:
volume(float): Volume level (0.0 to 1.0)
Properties
Name of the audio output device being used.
AudioData
Class representing loaded audio data that can be played by AudioSource instances.Static Methods
Creates audio data from a resource file.Parameters:
resource(Resource): Resource containing audio data
Methods
Gets the internal ID of the audio data.Returns: The audio data ID
Properties
Whether the audio data is mono. Mono audio is required for 3D spatialization.
The resource from which this audio data was loaded.
AudioSource
Class representing an audio source that can play audio data with 3D spatial positioning.Constructor & Destructor
Constructs a new AudioSource.
Destructor that releases audio source resources.
Loading Audio
Sets the audio data for this source.Parameters:
buffer(std::shared_ptr<AudioData>): Shared pointer to audio data
Loads audio data directly from a resource file.Parameters:
resource(Resource): Resource containing audio data
Playback Control
Starts playing the audio.
Pauses the audio playback. Can be resumed with
play().Stops the audio playback. Resets position to beginning.
Starts playing from a specific time position.Parameters:
seconds(float): Time position in seconds to start from
Checks if the audio is currently playing.Returns: True if playing, false otherwise
Playback Properties
Sets whether the audio should loop.Parameters:
loop(bool): True to enable looping, false to disable
Sets the volume of the audio source.Parameters:
volume(float): Volume level (0.0 to 1.0)
Sets the pitch of the audio source.Parameters:
pitch(float): Pitch multiplier (1.0 is normal pitch, 2.0 is double speed, 0.5 is half speed)
3D Spatial Audio
Enables 3D spatialization for this source. Makes audio position-dependent.
Only mono audio can be spatialized. Stereo audio will play without spatialization.
Disables 3D spatialization for this source. Audio will play uniformly.
Sets the 3D position of the audio source.Parameters:
position(Position3d): New position in 3D space
Sets the velocity of the audio source for Doppler effects.Parameters:
velocity(Magnitude3d): Velocity vector
Gets the current position of the audio source.Returns: The current 3D position
Gets the position of the audio listener.Returns: The listener’s 3D position
Effects
Applies an audio effect to this source.Parameters:
effect(AudioEffect): The audio effect to apply
Example Usage
Basic Audio Playback
Advanced Configuration
3D Positional Audio with Doppler
Managing Listener
Applying Effects
Playing from Specific Time
Notes
Finewave automatically handles:
- Audio format conversion
- Sample rate conversion
- Mono/stereo detection
- Distance-based attenuation for 3D audio
- Doppler shift calculations
For optimal performance:
- Reuse AudioData instances for sounds that play multiple times
- Use spatialization only for sounds that need 3D positioning
- Keep the number of simultaneous playing sources reasonable (< 32 typically)
Supported Audio Formats
Finewave supports common audio formats including:- WAV (PCM)
- OGG Vorbis
- MP3
- FLAC