Skip to main content

​
Overview

Audio sources are the primary way to play audio in Atlas Engine. You can use either the low-level AudioSource class or the high-level AudioPlayer component.

​
Loading Audio Files

​
Using AudioPlayer Component

The AudioPlayer component is the recommended way to add audio to game objects: 
#include "atlas/audio.h"

class BackpackAttach : public Component {
public:
    void init() override {
        auto player = this->object->getComponent<AudioPlayer>();
        player->setSource(Workspace::get().createResource(
            "exampleMP3.mp3", "ExampleAudio", ResourceType::Audio));
        player->useSpatialization();
        player->source->setLooping(true);
        player->play();
    }
};
This example from test/main.cpp shows how to:
  1. Get the AudioPlayer component from the object
  2. Load an audio resource from the workspace
  3. Enable spatial audio for 3D positioning
  4. Set the audio to loop continuously
  5. Start playback

​
Using AudioSource Directly

For more control, you can use AudioSource directly: 
#include "finewave/audio.h"

// Create an audio source
AudioSource audioSource;

// Load audio from a resource
audioSource.fromFile(
    Workspace::get().createResource(
        "explosion.wav", 
        "ExplosionSound", 
        ResourceType::Audio
    )
);

// Configure playback
audioSource.setVolume(0.8f);
audioSource.setPitch(1.2f);

// Play the audio
audioSource.play();

​
Sharing Audio Data

For sounds that are played frequently, you can load the data once and share it: 
// Load audio data once
auto footstepData = AudioData::fromResource(
    Workspace::get().getResource("footstep")
);

// Share across multiple sources
AudioSource leftFoot, rightFoot;
leftFoot.setData(footstepData);
rightFoot.setData(footstepData);

​
Playback Control

​
Basic Controls

AudioPlayer player;

// Start playing
player.play();

// Pause (can be resumed)
player.pause();

// Stop (resets to beginning)
player.stop();

​
Check Playback State

if (audioSource.isPlaying()) {
    std::cout << "Audio is currently playing" << std::endl;
}

​
Play From Specific Time

// Start playing from 5 seconds in
audioSource.playFrom(5.0f);

​
Audio Properties

​
Volume

Control the volume of individual audio sources (0.0 to 1.0): 
// Set volume to 50%
audioSource.setVolume(0.5f);

// Full volume
audioSource.setVolume(1.0f);

// Muted
audioSource.setVolume(0.0f);

​
Pitch

Adjust the playback speed and pitch: 
// Normal pitch
audioSource.setPitch(1.0f);

// Higher pitch (faster)
audioSource.setPitch(1.5f);

// Lower pitch (slower)
audioSource.setPitch(0.75f);

​
Looping

Set audio to repeat continuously: 
// Enable looping for background music
audioSource.setLooping(true);

// Disable looping for one-shot sounds
audioSource.setLooping(false);

​
Supported Audio Formats

Finewave supports common audio formats including:
  • MP3: Compressed, good for music
  • WAV: Uncompressed, low latency for sound effects
  • OGG: Compressed, open format

​
Complete Example: Background Music

class GameScene : public Scene {
    CoreObject musicPlayer;
    
public:
    void initialize(Window &window) override {
        // Set up resource path
        Workspace::get().setRootPath("resources/");
        
        // Create music resource
        Resource music = Workspace::get().createResource(
            "music/main_theme.mp3",
            "MainTheme",
            ResourceType::Audio
        );
        
        // Create object with audio player
        musicPlayer = CoreObject();
        auto player = musicPlayer.addComponent<AudioPlayer>();
        
        // Configure audio
        player->setSource(music);
        player->source->setLooping(true);
        player->source->setVolume(0.6f);
        player->disableSpatialization(); // Global sound
        
        // Start playing
        player->play();
        
        window.addObject(&musicPlayer);
    }
};

​
Complete Example: Sound Effects

class WeaponSystem : public Component {
    AudioSource fireSound;
    AudioSource reloadSound;
    
public:
    void init() override {
        // Load sound effects
        fireSound.fromFile(
            Workspace::get().getResource("weapon_fire")
        );
        reloadSound.fromFile(
            Workspace::get().getResource("weapon_reload")
        );
        
        // Configure as one-shot sounds
        fireSound.setLooping(false);
        reloadSound.setLooping(false);
    }
    
    void update(float deltaTime) override {
        if (Window::mainWindow->isKeyClicked(Key::Space)) {
            fireSound.play();
        }
        if (Window::mainWindow->isKeyClicked(Key::R)) {
            reloadSound.play();
        }
    }
};

​
Best Practices

The AudioPlayer component automatically handles updates and integrates with the component system. Use it for audio attached to objects in your scene.
Load AudioData once and share it across multiple AudioSource instances to save memory and loading time.
Balance your audio by setting relative volumes. Background music typically ranges from 0.3 to 0.7, while sound effects can be louder.
Use WAV for short, frequently played sound effects (low latency). Use MP3 or OGG for longer music tracks (smaller file size).

​
Next Steps

Spatial Audio

Learn how to add 3D positional audio to your sources

Build docs developers (and LLMs) love

Get started for freeTalk to us