Skip to main content

​
What is Finewave?

Finewave is Atlas Engine’s built-in audio subsystem that provides comprehensive audio playback, 3D spatial audio, and real-time audio effects. It handles everything from basic sound playback to advanced positional audio with Doppler effects.

​
Key Features

  • 3D Spatial Audio: Position-based audio with automatic attenuation and panning
  • Audio Effects: Reverb, echo, and distortion effects for enhanced realism
  • Component-Based: Attach audio to any game object using the AudioPlayer component
  • Resource Management: Seamless integration with Atlas workspace resource system
  • Real-Time Updates: Automatic listener positioning based on camera movement

​
Core Components

Finewave consists of three main classes:

​
AudioEngine

The central audio engine manages global audio settings and the listener position. 
class AudioEngine {
public:
    bool initialize();
    void shutdown();
    
    void setListenerPosition(Position3d position);
    void setListenerOrientation(Magnitude3d forward, Normal3d up);
    void setListenerVelocity(Magnitude3d velocity);
    void setMasterVolume(float volume);
};

​
AudioData

Represents loaded audio data that can be shared across multiple audio sources. 
class AudioData {
public:
    static std::shared_ptr<AudioData> fromResource(Resource resource);
    Id getId() const;
    bool isMono = false;
};

​
AudioSource

An audio source that plays audio data with configurable properties. 
class AudioSource {
public:
    void fromFile(Resource resource);
    void play();
    void pause();
    void stop();
    
    void setLooping(bool loop);
    void setVolume(float volume);
    void setPitch(float pitch);
    
    void setPosition(Position3d position);
    void useSpatialization();
    void disableSpatialization();
};

​
AudioPlayer Component

Atlas provides the AudioPlayer component for easy integration with game objects: 
class AudioPlayer : public Component {
public:
    std::unique_ptr<AudioSource> source;
    
    void init() override;
    void play();
    void pause();
    void stop();
    
    void setSource(Resource sourceResource);
    void useSpatialization();
    void setPosition(Position3d position);
};

​
Quick Example

Here’s a complete example of setting up audio in your scene: 
#include "atlas/audio.h"
#include "atlas/object.h"

class MyScene : public Scene {
    CoreObject audioObject;
    
public:
    void initialize(Window &window) override {
        // Create audio resource
        Resource audioResource = Workspace::get().createResource(
            "background_music.mp3", 
            "BackgroundMusic", 
            ResourceType::Audio
        );
        
        // Create object with audio player
        audioObject = CoreObject();
        auto player = audioObject.addComponent<AudioPlayer>();
        player->setSource(audioResource);
        player->source->setLooping(true);
        player->source->setVolume(0.7f);
        player->play();
        
        window.addObject(&audioObject);
    }
};

​
Audio Engine Initialization

The AudioEngine is automatically initialized when you create a Window. It manages:
  • Audio device selection and initialization
  • Global audio context
  • Listener position and orientation
  • Master volume control
The listener is automatically updated based on the active camera’s position, ensuring accurate 3D audio positioning.

​
Next Steps

Audio Sources

Learn how to load and play audio files

Spatial Audio

Implement 3D positional audio in your scenes

Audio Effects

Add reverb, echo, and distortion effects

API Reference

Explore the complete Finewave API

Build docs developers (and LLMs) love

Get started for freeTalk to us