Audio System

Microsoft::Xna::Framework::Audio — SoundEffect, MediaPlayer, XACT classes, microphone input, and the three CNA_AUDIO_PLATFORM implementations

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 the four values are not feature-equivalent: SDL3 (the default) and ALSA define SOUND_ENABLED and provide a mixer — SDL3_mixer for the first, CNA's own mixer for the second. NULL provides a low-level IAudioDevice implementation 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 a mixer-backed choice (SDL3 or ALSA).

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.

Both mixers use the same track-based model behind one internal facade (MixerEngine.hpp): each SoundEffectInstance and each Song played through MediaPlayer occupies its own mixer track, rather than writing to a global shared output. SDL3_mixer is vendored as a Git submodule and built alongside CNA; it uses the MIX_Track model natively, which avoids the global-state pitfalls of older SDL_mixer versions and maps cleanly onto the per-instance XNA API. The ALSA implementation carries its own mixer (CnaMixer) that follows the same semantics: per-track resampling, gain, a per-track mix callback for filter and pan, then a master mix and a post-mix callback.

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. The examples on this page use the real property-style call names (setVolumeProperty, getStateProperty and so on) and were checked against this snapshot's headers.

Audio implementations (CNA_AUDIO_PLATFORM)

The audio device layer is a separate CMake axis from the platform (CNA_PLATFORM) and the renderer. Three values are implemented, SDL3 is the default on every target, and OPENAL and WASAPI are reserved names that fail configuration instead of falling back. Values are case-sensitive.

A WAV decoder that does not depend on any of the four (DecodeWavToPcm16) is compiled into every build, so the content tools and content tests link without SDL. It is not a playback path under NULL.

Choosing and configuring

# Default: SDL3 device + SDL3_mixer (every desktop, mobile and web target)
cmake -S . -B build -DCNA_AUDIO_PLATFORM=SDL3

# Native Linux audio with CNA's own mixer (needs libasound2-dev); the window still comes from SDL3
cmake -S . -B build -DCNA_AUDIO_PLATFORM=ALSA -DCNA_GRAPHICS_RENDERER=OPENGLES3

# No SDL anywhere: a windowless HEADLESS (or TERMINAL) build with ALSA audio
cmake -S . -B build-nosdl \
  -DCNA_ENABLE_SDL=OFF -DCNA_PLATFORM=HEADLESS \
  -DCNA_AUDIO_PLATFORM=ALSA -DCNA_GRAPHICS_RENDERER=HEADLESS

# Deterministic silent build with no mixer: device-contract and logic work only
cmake -S . -B build-headless \
  -DCNA_PLATFORM=HEADLESS -DCNA_AUDIO_PLATFORM=NULL -DCNA_GRAPHICS_RENDERER=HEADLESS

• Normal games: keep SDL3. It is the only choice that provides a mixer on macOS, iOS, Android and Emscripten.
• Linux without SDL audio: ALSA. It gives you the full XNA audio facade — effects, songs, dynamic instances, XACT and capture — without linking SDL or libasound (the library is opened at run time; a machine without it still starts the program, and playback then reports NoAudioHardwareException).
• Tests and CI that must be silent: either the default SDL3 with SDL_AUDIODRIVER=dummy, or ALSA with CNA_AUDIO_DEVICE=null. Both keep a functioning mixer. NULL is the choice only when you do not need any mixer behaviour at all.
• Windows and macOS without SDL: there is no SDL-free audio device there. CNA_ENABLE_SDL=OFF refuses SDL3 audio, so an SDL-free Windows build (a windowless HEADLESS build) has NULL audio only. OPENAL and WASAPI are reserved and rejected.

Environment variables (ALSA)

There is no CNA_AUDIO_PLATFORM environment variable: the implementation is fixed at configure time. On a PipeWire desktop ALSA's default device is PipeWire (through pipewire-alsa), on a PulseAudio desktop it is PulseAudio (through the ALSA plugins), and on a bare system it is the sound card through dmix, so one backend reaches all three provided the distribution installs the corresponding ALSA plugin. The step-by-step guide is Tutorial 137: Native Linux Audio with ALSA.

Tier 1 — Implemented playback (SDL3_mixer or CNA's own mixer)

SoundEffect

SoundEffect represents a loaded audio asset — typically a short sound effect stored as WAV. It is an immutable, move-only 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 (inside a Game subclass)
auto boom = getContentProperty().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.

Every property is a getXProperty()/setXProperty() pair: for example setVolumeProperty(0.7f) and getStateProperty().

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

instance.setVolumeProperty(0.7f);
instance.setPitchProperty(-0.3f);   // slightly lower pitch
instance.setPanProperty(0.5f);      // panned right
instance.setIsLoopedProperty(false);
instance.Play();

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

DynamicSoundEffectInstance

DynamicSoundEffectInstance allows streaming audio data from application-managed buffers rather than from a preloaded file. The engine raises 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. Tutorial 118 walks through it end to end.

// DynamicSoundEffectInstance with a BufferNeeded callback (inside a Game subclass)
dynSfx_ = std::make_unique<DynamicSoundEffectInstance>(44100, AudioChannels::Stereo);

dynSfx_->BufferNeeded += [this](System::Object* sender, const System::EventArgs&) {
    // Generate or decode the next chunk of PCM data
    auto* dyn = static_cast<DynamicSoundEffectInstance*>(sender);
    dyn->SubmitBuffer(GenerateNextAudioChunk());   // std::vector<SharpRuntime::bytecs>
};

// Submit an initial buffer before calling Play()
dynSfx_->SubmitBuffer(GenerateNextAudioChunk());
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. Neither mixer pre-decodes a song: SDL3_mixer decodes the audio file progressively, and CNA's own mixer keeps the compressed bytes in memory and decodes them as they play — either way a Song is suitable for large music files that would be impractical to decode 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. Volume, muting, and looping are controlled through static properties, and the current playback state is available via getStateProperty(). Play() takes a Song* (or a SongCollection).

// MediaPlayer playing a Song (theme_ is a std::optional<Song> member)
theme_ = getContentProperty().Load<Song>("music/main_theme");

MediaPlayer::setIsRepeatingProperty(true);
MediaPlayer::setVolumeProperty(0.8f);
MediaPlayer::Play(&*theme_);

// Mute on focus loss, restore on focus gain
void OnFocusLost()  { MediaPlayer::setIsMutedProperty(true);  }
void OnFocusGained(){ MediaPlayer::setIsMutedProperty(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 the manager's root directory (getRootDirectoryProperty()) and may omit the file extension. Load<T> returns the asset by value. When the manager tries extensions itself, it looks for a compiled .xnb and then a .cnb first; a SoundEffect then falls back to .wav, and a Song to .mp3, .ogg, .wav, .flac, .opus, .aac and .wma in that order — but a name resolving does not mean the file decodes: the audio implementation decides what it can play (see Decoders and file formats).

// Loading audio assets via ContentManager (inside a Game subclass)
auto& content = getContentProperty();          // root directory "Content" by default

// Load a short sound effect (WAV)
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);
std::unique_ptr<SoundEffect> custom(SoundEffect::FromStream(file));

A standalone ContentManager (outside a Game) is constructed with a service provider and a root directory: ContentManager(System::IServiceProvider*, const std::string& rootDirectory). A SoundEffect loaded through the manager is never cached — each Load call returns its own independently owned instance, because the type is move-only.

Decoders and file formats

What can be played is decided by the audio implementation, not by the file extension. CNA's own mixer identifies a file by its content (RIFF/WAVE, OggS, fLaC, an ID3 tag or an MPEG sync word) and refuses anything else with an error naming the formats it does play.

XACT wave banks add their own codecs: 8-bit and 16-bit PCM and MS-ADPCM decode, XMA and WMA do not (see Honest partials). An .xnb SoundEffect is decoded to 16-bit PCM by the content library itself (16-bit PCM directly, 8-bit PCM widened, 32-bit float, MS-ADPCM and IMA-ADPCM through CNA's own WAV decoder, which is compiled into every build) and built through the raw-PCM constructor, so it does not depend on the selected mixer; XMA2 is rejected with a ContentLoadException that names the format. MediaLibrary track durations come from an FFmpeg-based probe: in a build without FFmpeg they report 0 (unknown). See Video Playback for the optional FFmpeg layer.

3D positional audio

3D audio uses the same three pieces as XNA: an AudioListener (the ear), an AudioEmitter (the source) and SoundEffectInstance::Apply3D. Doppler is computed exactly (FAudio's formula); distance and stereo placement are approximated by one attenuation value and one pan value because the mixers have a single stereo gain pair rather than per-listener output matrices. Tutorial 119 covers the attenuation curve, Doppler and the globals in depth.

The old “exactly one listener” limit is gone: multi-listener calls no longer throw NotSupportedException. What CNA cannot reproduce is XACT's own multi-listener DSP, so the dominant-listener rule is an approximation — it is deliberately not “use listeners[0]”, and moving a second, closer listener changes the result. Two more behaviours follow XNA: the effective Doppler scale is the emitter's DopplerScale multiplied by the global SoundEffect one (a stationary sound is not pitch-shifted), and an instance's mode is fixed while it plays — before its first Play() you can still switch between Apply3D and setPanProperty, but on a playing instance calling Apply3D on a pan-mode instance, or setPanProperty on a 3D one, throws InvalidOperationException. Stop() makes the instance re-aimable.

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. It needs a mixer-backed audio implementation: with NULL the banks parse but nothing is audible. For new CNA-only projects without existing XACT content, SoundEffect and SoundEffectInstance remain the simpler Tier 1 API and integrate directly with ContentManager. Tutorial 120 is the end-to-end guide.

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 wave-bank entries are silent, not fatal. A wave-bank entry in either codec does not throw: CNA writes a diagnostic naming the bank, wave index and format to stderr and returns no sound, so the cue simply makes no sound. Re-encode to PCM or MS-ADPCM. (A .xnb SoundEffect in XMA2 is different: the XNB reader rejects it with a ContentLoadException.)
• The reverb send is a no-op. The API accepts it, but no reverb is applied to the signal.

Microphone

Microphone is implemented on the two mixer-backed implementations: real SDL3 capture devices under SDL3 and ALSA capture under ALSA. Device enumeration (Microphone::getAllProperty() lists the machine's devices, getDefaultProperty() returns nullptr when there are none), Start()/Stop(), GetData() and BufferReady delivery all work against genuine hardware input. Capture is mono, signed 16-bit at a requested 44,100 Hz, and BufferDuration accepts 100–1000 ms in steps of 10 ms. Under NULL there is no recording provider, so the microphone list is empty. With ALSA, CNA_AUDIO_RECORDING_DEVICE chooses the PCM and the capture thread queues up to eight seconds so a game polling once a frame loses nothing between polls.

Tests and CI evidence

The audio module's own test executable is CnaAudioTests. The ALSA path is exercised by the SDL-free Headless + ALSA job of platform-ci.yml, which builds a CNA_ENABLE_SDL=OFF configuration with CNA_AUDIO_PLATFORM=ALSA and runs the WavDecoderTest, CnaMixer, CnaMixerXna, AlsaAudioDevice, AlsaAudioRecordingDevice, Microphone, AudioCategory and AudioEngine suites on ALSA's null device; it also asserts that the built executables do not link SDL and do not link libasound. That is evidence about the mixer and the device layer on a machine with no sound card, not a listening test on real hardware. Tests that read SDL3_mixer track handles remain SDL3-only, and mixer-dependent test sources are excluded from NULL builds. See What CI actually covers and Verification & Known Issues.