Audio System

Microsoft::Xna::Framework::Audio — SoundEffect, MediaPlayer, XACT classes, and microphone input

Overview

CNA's audio system is split into two tiers. Tier 1 covers playback of sound effects and music. Its device selection is independent through CNA_AUDIO_PLATFORM, but alpha.1's values are not feature-equivalent: SDL3 is the default and the only choice that defines SOUND_ENABLED and links the SDL3_mixer playback/decoding engine. SDL2 and NULL provide low-level IAudioDevice implementations and selection/conformance coverage, while the mixer-dependent XNA playback facade is compiled without its real engine. Tier 2 covers XACT — cue-based audio driven by .xgs/.xsb/.xwb content — and real playback likewise requires the SDL3 choice.

It is worth being precise about what "real XACT" means here, because most XNA reimplementations stop at the API shape. CNA ships a real parser for the three XACT binary formats, and the playback side reproduces FACT's actual volume formula and evaluates real RPC (runtime parameter control) curves rather than approximating them. The 3D positional path uses FAudio's exact Doppler calculation and F3DAudio's attenuation model. The honest partials below are the places where that fidelity currently stops.

SDL3_mixer is vendored as a Git submodule and built alongside CNA. It uses the MIX_Mixer track-based model internally: each SoundEffectInstance and each Song played through MediaPlayer occupies its own mixer track, rather than writing to a global shared output. This avoids the global-state pitfalls present in older SDL_mixer versions and maps cleanly onto the XNA per-instance API.

All audio classes live in the Microsoft::Xna::Framework::Audio namespace, with MediaPlayer and Song in Microsoft::Xna::Framework::Media, matching XNA 4.0 exactly.

Tier 1 — Implemented playback (SDL3_mixer)

SoundEffect

SoundEffect represents a loaded audio asset — typically a short sound effect stored as WAV or OGG. It is an immutable handle to decoded audio data. To play a sound once, call Play() directly. To control playback parameters, call CreateInstance() and manipulate the resulting SoundEffectInstance.

The preferred way to load a SoundEffect is through ContentManager, but FromStream() is provided for loading from arbitrary sources such as network streams or embedded resources.

// One-shot play — simplest usage
auto boom = content.Load<SoundEffect>("audio/explosion");
boom->Play();

SoundEffectInstance

SoundEffectInstance is a controllable playback handle obtained from SoundEffect::CreateInstance(). Unlike a fire-and-forget Play() call, an instance lets you adjust volume, pitch, and pan at any time, pause and resume playback, and query the current playback state. Each instance holds its own mixer track.

// SoundEffectInstance with volume, pitch, and pan control
auto sfx = content.Load<SoundEffect>("audio/laser");
auto instance = sfx->CreateInstance();

instance->SetVolume(0.7f);
instance->SetPitch(-0.3f);   // slightly lower pitch
instance->SetPan(0.5f);      // panned right
instance->SetIsLooped(false);
instance->Play();

// Later, in response to a game event:
if (instance->GetState() == SoundState::Playing) {
    instance->Pause();
}

DynamicSoundEffectInstance

DynamicSoundEffectInstance allows streaming audio data from application-managed buffers rather than from a preloaded file. The engine fires the BufferNeeded event whenever its internal buffer queue runs low, signalling the application to call SubmitBuffer() with the next chunk of PCM data. This is suitable for procedurally generated audio, network audio streams, or decoded-on-the-fly music.

// DynamicSoundEffectInstance with BufferNeeded callback
auto dynSfx = std::make_shared<DynamicSoundEffectInstance>(44100, AudioChannels::Stereo);

dynSfx->BufferNeeded += [&](auto* sender, auto& args) {
    // Generate or decode the next chunk of PCM data
    std::vector<int16_t> samples = GenerateNextAudioChunk();
    dynSfx->SubmitBuffer(samples);
};

// Submit an initial buffer before calling Play()
std::vector<int16_t> initialChunk = GenerateNextAudioChunk();
dynSfx->SubmitBuffer(initialChunk);
dynSfx->Play();

Song

Song represents a music track loaded through the ContentManager. Unlike SoundEffect, a Song is played exclusively through the MediaPlayer static class; only one song plays at a time. SDL3_mixer decodes the audio file progressively, making Song suitable for large music files that would be impractical to load entirely into memory.

MediaPlayer

MediaPlayer is a static class that manages playback of a single Song at a time. It mirrors the XNA 4.0 Microsoft.Xna.Framework.Media.MediaPlayer API exactly. Volume, muting, and looping are controlled through static properties, and the current playback state is available via State.

// MediaPlayer playing a Song
auto theme = content.Load<Song>("music/main_theme");

MediaPlayer::SetIsRepeating(true);
MediaPlayer::SetVolume(0.8f);
MediaPlayer::Play(theme);

// Mute on focus loss, restore on focus gain
void OnFocusLost()  { MediaPlayer::SetIsMuted(true);  }
void OnFocusGained(){ MediaPlayer::SetIsMuted(false); }

Loading audio via ContentManager

Both SoundEffect and Song are loaded through the standard ContentManager pipeline. Place audio files in your content directory; the path passed to Load<T>() is relative to ContentManager::RootDirectory and should omit the file extension. CNA resolves common audio extensions automatically (.wav, .ogg).

// Loading audio assets via ContentManager
ContentManager content(services, "Content");

// Load a short sound effect (WAV or OGG)
auto jumpSfx = content.Load<SoundEffect>("audio/jump");

// Load a music track (OGG recommended for large files)
auto bgMusic = content.Load<Song>("music/level1");

// Alternatively, load a SoundEffect from a raw stream
std::ifstream file("assets/custom.wav", std::ios::binary);
auto custom = SoundEffect::FromStream(file);

Tier 2 — XACT (AudioEngine/SoundBank/WaveBank/Cue)

XACT-driven audio works directly in CNA — you do not need to migrate AudioEngine/SoundBank/Cue calls away. For new CNA-only projects without existing XACT content, SoundEffect and SoundEffectInstance remain the simpler Tier 1 API and integrate directly with ContentManager.

Honest partials

Three limitations are worth knowing before you point a real XACT project at CNA:

• Only the first PlayWave per track is honored. Cues authored with multiple waves on a single track will not play them all.
• XMA and WMA throw. Wave banks using either compressed format cannot be played; re-encode to a supported format.
• The reverb send is a no-op. The API accepts it, but no reverb is applied to the signal.

Microphone

Microphone is implemented using real SDL3 capture devices: device enumeration, Start()/Stop(), and BufferReady delivery all work against genuine hardware input.