Audio Integration

Audio currently uses miniaudio for decoding and playback. Steam Audio and spatial ECS components are not implemented in the current engine path.

Current Components

Component	File	Purpose
Engine::Assets::Audio	Engine/include/Engine/Audio/AudioAsset.h	Stores decoded PCM and clip metadata
Engine::Assets::AudioAssetRef	Engine/include/Engine/Audio/AudioAssetRef.h	Stable ref to an audio asset record
Engine::Assets::Loaders::AudioLoader	Engine/include/Engine/Audio/AudioLoader.h	Decodes WAV, FLAC, and MP3 through miniaudio
Engine::Ecs::AudioAssetPipeline	Engine/include/Engine/Ecs/FrameProcessing.h	Async decode pipeline
Engine::Core::AudioEngine	Engine/include/Engine/Audio/AudioEngine.h	Owns ma_engine, registers loaded clips, starts and stops playback

Asset Key

Audio assets are keyed by Asset::Path in AudioAssetManager.

Asset::Path clipPath(Engine::Core::Path::engineSounds() / "Eat.wav");
 
Engine::Assets::AudioAssetRef clipRef =
    scene->getAssetManager()->getAsset<Engine::Assets::Audio>(clipPath);

getAsset<Engine::Assets::Audio>() also accepts a raw std::filesystem::path for compatibility and wraps it in Asset::Path internally.

Loading Flow

AudioAssetPipeline runs once per frame from EngineKern::processResourceLoadingPipelines().

assetManager->getAudioAssetPipeline().tick(true);

The pipeline has two stages.

Stage	Work
submitDecodeJobs()	Move queued paths to worker futures and call AudioLoader::load(path)
retrieveDecodedAudio()	Poll ready futures, create Audio assets, resolve records, notify AudioEngine

Decoded audio is stored directly on Engine::Assets::Audio.

class Audio : public Asset::AssetBase {
    uint32_t sampleRate_ = 0;
    uint32_t channels_ = 0;
    uint64_t frameCount_ = 0;
    float durationSeconds_ = 0.0f;
    std::vector<float> pcmData_;
};

Audio does not use hidden ECS entities for PCM storage. Audio::setAudioData() moves decoded PCM into the asset object and marks it loaded.

Playback Flow

Asset loading and playback are separate.

if (!clipRef.isLoaded()) {
    return;
}
 
auto* audioEngine = Engine::EngineManager::getInstance()
    .getEngineModule()
    ->getAudioEngine();
 
Engine::Core::AudioHandle handle = audioEngine->play(
    clipPath.getFilePath(),
    1.0f,
    false
);

AudioEngine::onAudioLoaded() registers loaded clips by filesystem path. AudioEngine::play() currently takes std::filesystem::path, creates a ma_audio_buffer from decoded PCM, creates a ma_sound, starts playback, and returns an AudioHandle.

Example Actor

AirHockey/source/src/Actors/SoundTestActor.cpp shows the current pattern.

void SoundTestActor::beginPlay()
{
    Actor::beginPlay();
    soundRef_ = getOwningScene()
        ->getAssetManager()
        ->getAsset<Engine::Assets::Audio>(soundPath_);
}
 
void SoundTestActor::tick(double deltaTimeSeconds)
{
    Actor::tick(deltaTimeSeconds);
 
    if (playbackStarted_ || !soundRef_.isLoaded()) {
        return;
    }
 
    auto* audioEngine = Engine::EngineManager::getInstance()
        .getEngineModule()
        ->getAudioEngine();
 
    currentHandle_ = audioEngine->play(soundPath_, volume_, loop_);
    playbackStarted_ = currentHandle_ != Engine::Core::INVALID_AUDIO_HANDLE;
}

Current Limits

Area	Current State
Asset access	Uses Asset::Path and AudioAssetRef
Playback access	Still calls AudioEngine::play(std::filesystem::path, volume, loop)
Spatial audio	Not implemented
Streaming music	Not implemented; clips decode fully into memory
ECS audio source/listener components	Not implemented
Cleanup	AssetManager::unloadAllData() clears audio asset records with the other asset managers

The next audio refactor should remove direct path playback from gameplay code and make playback consume asset refs or a dedicated audio source component.

Configuration

miniaudio uses values from Engine/include/Engine/Audio/AudioConfig.h.

Setting	Value
Sample rate	Engine::Core::Audio::SAMPLE_RATE
Frame size	Engine::Core::Audio::FRAME_SIZE
Output channels	Engine::Core::Audio::OUTPUT_CHANNELS