Skip to main content

​
Overview

The Audio API provides high-level audio playback capabilities for game objects. It integrates with the Finewave audio engine to provide 3D spatial audio with support for effects, positioning, and listener-based attenuation.
Finewave is required for audio components to work.

​
AudioPlayer Component

Component that provides audio playback capabilities to any object in the scene. It allows playing, pausing, and stopping audio with 3D spatial positioning.

​
Constructor

​
AudioPlayer
constructor
Creates a new empty AudioPlayer object.

​
Lifecycle Methods

​
init
void
Initialize the audio player and prepare it for playback. Must be called before using the player.

​
Playback Control

​
play
void
Play the audio from the beginning or resume if paused.
​
pause
void
Pause the audio playback. Can be resumed later with play().
​
stop
void
Stop the audio playback and reset to the beginning.

​
Audio Source Configuration

​
setSource
void
Set the source from where the audio will be played.Parameters:
  • sourceResource (Resource): Resource containing the audio file

​
Spatial Audio

​
setPosition
void
Set the position of the audio source in 3D space.Parameters:
  • position (Position3d): New position of the audio source
Only effective when spatialization is enabled.
​
useSpatialization
void
Enable spatialization for the audio source, making it 3D and affected by the listener’s position.
​
disableSpatialization
void
Disable spatialization for the audio source, making it play uniformly regardless of the listener’s position.

​
Properties

​
source
std::unique_ptr<AudioSource>
The underlying audio source. Allows for advanced manipulation of audio playback.

​
Example Usage

// Create an AudioPlayer component
auto audioPlayer = std::make_shared<AudioPlayer>();

// Initialize the audio player
audioPlayer->init();

// Set the audio source from a file
audioPlayer->setSource(Workspace::get().getResource("AudioResource"));

// Enable 3D positioning
audioPlayer->useSpatialization();

// Play the audio
audioPlayer->play();

​
Attaching to GameObject

// Create a game object
auto soundObject = std::make_shared<GameObject>();

// Attach the audio player
auto audioPlayer = std::make_shared<AudioPlayer>();
audioPlayer->init();
audioPlayer->setSource(Workspace::get().getResource("explosion"));
audioPlayer->useSpatialization();

soundObject->addComponent(audioPlayer);

// Position the object in 3D space
soundObject->setPosition({10.0f, 5.0f, 20.0f});

// Play the sound
audioPlayer->play();

​
Background Music

// Create background music without spatialization
auto musicPlayer = std::make_shared<AudioPlayer>();
musicPlayer->init();
musicPlayer->setSource(Workspace::get().getResource("background_music"));
musicPlayer->disableSpatialization(); // Play uniformly

// Access the source for advanced control
musicPlayer->source->setLooping(true);
musicPlayer->source->setVolume(0.3f);

musicPlayer->play();

​
Integration with Camera

The AudioPlayer automatically updates the audio listener position based on the main camera: 
// The update() method automatically handles listener positioning
// No manual intervention needed - just attach AudioPlayer to objects

// The listener will track:
// - Camera position
// - Camera orientation (front vector)
// - Camera velocity (for Doppler effects)

​
Advanced Usage

Access the underlying AudioSource for more control: 
auto audioPlayer = std::make_shared<AudioPlayer>();
audioPlayer->init();

// Advanced source manipulation
audioPlayer->source->setLooping(true);
audioPlayer->source->setVolume(0.8f);
audioPlayer->source->setPitch(1.2f);
audioPlayer->source->setVelocity({5.0f, 0.0f, 0.0f}); // For Doppler

// Apply audio effects
AudioEffect reverbEffect;
// ... configure effect ...
audioPlayer->source->applyEffect(reverbEffect);

// Check playback state
if (audioPlayer->source->isPlaying()) {
    // Audio is currently playing
}

// Start from specific time
audioPlayer->source->playFrom(5.0f); // Start at 5 seconds

​
Notes

The AudioPlayer component calls update() every frame to synchronize the listener position with the camera and update the audio source position with its parent GameObject.
Ensure the AudioPlayer is initialized with init() before calling any playback methods. The component will automatically initialize if needed, but explicit initialization is recommended.
For best performance with many audio sources, use spatialization only for sounds that need 3D positioning. Background music and UI sounds should disable spatialization.

Build docs developers (and LLMs) love

Get started for freeTalk to us