Skip to main content

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

initialize
bool
Initializes the audio engine. Must be called before using any audio features.Returns: True if initialization succeeded, false otherwise
shutdown
void
Shuts down the audio engine and releases resources.

Listener Configuration

setListenerPosition
void
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
setListenerOrientation
void
Sets the orientation of the audio listener.Parameters:
  • forward (Magnitude3d): Forward direction vector
  • up (Normal3d): Up direction vector
setListenerVelocity
void
Sets the velocity of the audio listener for Doppler effects.Parameters:
  • velocity (Magnitude3d): Listener velocity vector

Global Settings

setMasterVolume
void
Sets the master volume for all audio.Parameters:
  • volume (float): Volume level (0.0 to 1.0)

Properties

deviceName
std::string
Name of the audio output device being used.

AudioData

Class representing loaded audio data that can be played by AudioSource instances.

Static Methods

fromResource
std::shared_ptr<AudioData>
Creates audio data from a resource file.Parameters:
  • resource (Resource): Resource containing audio data
Returns: Shared pointer to the created audio data

Methods

getId
Id
Gets the internal ID of the audio data.Returns: The audio data ID

Properties

isMono
bool
Whether the audio data is mono. Mono audio is required for 3D spatialization.
resource
Resource
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

AudioSource
constructor
Constructs a new AudioSource.
~AudioSource
destructor
Destructor that releases audio source resources.

Loading Audio

setData
void
Sets the audio data for this source.Parameters:
  • buffer (std::shared_ptr<AudioData>): Shared pointer to audio data
fromFile
void
Loads audio data directly from a resource file.Parameters:
  • resource (Resource): Resource containing audio data

Playback Control

play
void
Starts playing the audio.
pause
void
Pauses the audio playback. Can be resumed with play().
stop
void
Stops the audio playback. Resets position to beginning.
playFrom
void
Starts playing from a specific time position.Parameters:
  • seconds (float): Time position in seconds to start from
isPlaying
bool
Checks if the audio is currently playing.Returns: True if playing, false otherwise

Playback Properties

setLooping
void
Sets whether the audio should loop.Parameters:
  • loop (bool): True to enable looping, false to disable
setVolume
void
Sets the volume of the audio source.Parameters:
  • volume (float): Volume level (0.0 to 1.0)
setPitch
void
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

useSpatialization
void
Enables 3D spatialization for this source. Makes audio position-dependent.
Only mono audio can be spatialized. Stereo audio will play without spatialization.
disableSpatialization
void
Disables 3D spatialization for this source. Audio will play uniformly.
setPosition
void
Sets the 3D position of the audio source.Parameters:
  • position (Position3d): New position in 3D space
setVelocity
void
Sets the velocity of the audio source for Doppler effects.Parameters:
  • velocity (Magnitude3d): Velocity vector
getPosition
Position3d
Gets the current position of the audio source.Returns: The current 3D position
getListenerPosition
Position3d
Gets the position of the audio listener.Returns: The listener’s 3D position

Effects

applyEffect
void
Applies an audio effect to this source.Parameters:
  • effect (AudioEffect): The audio effect to apply

Example Usage

Basic Audio Playback

// Create an audio source
AudioSource audioSource;

// Load audio from a resource
audioSource.fromFile(Workspace::get().getResource("explosion"));

// Set 3D position
audioSource.setPosition({5.0, 0.0, 10.0});

// Enable spatialization
audioSource.useSpatialization();

// Play the audio
audioSource.play();

Advanced Configuration

// Create audio data
auto audioData = AudioData::fromResource(Workspace::get().getResource("music"));

// Create source and set data
AudioSource source;
source.setData(audioData);

// Configure playback
source.setLooping(true);
source.setVolume(0.7f);
source.setPitch(1.2f);

// Disable spatialization for background music
source.disableSpatialization();

// Start playing
source.play();

3D Positional Audio with Doppler

AudioSource movingSource;
movingSource.fromFile(Workspace::get().getResource("car_engine"));

// Enable spatialization
movingSource.useSpatialization();

// Set position and velocity for Doppler effect
movingSource.setPosition({10.0f, 0.0f, 0.0f});
movingSource.setVelocity({20.0f, 0.0f, 0.0f}); // Moving at 20 units/sec

// Play with looping
movingSource.setLooping(true);
movingSource.play();

Managing Listener

// Initialize audio engine
AudioEngine audioEngine;
if (!audioEngine.initialize()) {
    // Handle initialization failure
}

// Set master volume
audioEngine.setMasterVolume(0.8f);

// Update listener from camera
Camera* camera = window->getCamera();
audioEngine.setListenerPosition(camera->position);
audioEngine.setListenerOrientation(camera->getFrontVector(), Normal3d{0.0f, 1.0f, 0.0f});
audioEngine.setListenerVelocity(camera->getVelocity());

Applying Effects

AudioSource source;
source.fromFile(Workspace::get().getResource("voice"));

// Create and apply an audio effect
AudioEffect reverbEffect;
// Configure effect parameters...
source.applyEffect(reverbEffect);

source.play();

Playing from Specific Time

AudioSource source;
source.fromFile(Workspace::get().getResource("long_track"));

// Start playback at 30 seconds
source.playFrom(30.0f);

// Check playback state
if (source.isPlaying()) {
    std::cout << "Audio is playing" << std::endl;
}

Notes

Finewave automatically handles:
  • Audio format conversion
  • Sample rate conversion
  • Mono/stereo detection
  • Distance-based attenuation for 3D audio
  • Doppler shift calculations
Only mono audio files can be spatialized in 3D. Stereo files will play without positional audio even if spatialization is enabled.
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
Format support depends on the underlying audio backend.

Build docs developers (and LLMs) love