Class AudioSystemExtensions

Namespace

Stride.CommunityToolkit.Audio

Assembly

Stride.CommunityToolkit.dll

Sound for a game with no sound assets: generated sounds, .wav files read at runtime, and a listener that follows an entity. All on game.Audio.

public static class AudioSystemExtensions

Inheritance

object

AudioSystemExtensions

Remarks

Every method needs the audio engine, and the engine may be missing: AudioSystem.Initialize swallows the native initialisation failure and leaves AudioEngine null. On Windows the engine ships in the package (XAudio2), so this happens on Linux without OpenAL and on headless machines. Each method throws InvalidOperationException naming that cause rather than failing later with a null reference; check AudioEngine first to degrade silently instead.

Call these once the game is running - in the start callback of Run or later. The engine does not exist before Initialize.

Methods

AttachListener(AudioSystem, Entity)

Gives entity an AudioListenerComponent and returns its listener, which the engine then moves with the entity every frame. Put it on the camera and pass the result as the listener of every spatialised sound.

public static AudioListener AttachListener(this AudioSystem audio, Entity entity)

Parameters

audio AudioSystem

The game's audio system, game.Audio.

entity Entity

The entity to listen from. Must already be in the scene: the engine creates the listener when the component enters one.

Returns

AudioListener

The entity's listener. Calling again for the same entity returns the same listener.

Remarks

Without this, a runtime sound is heard by DefaultListener, which nothing ever moves: it sits at the origin facing +Z however the camera turns. The engine only updates listeners that belong to a component, and this is the way to get one of those for a runtime sound.

Exceptions

InvalidOperationException

The audio engine is not available, or the entity is not in a scene.

CreateProceduralSound(AudioSystem, SampleFiller, int, bool, bool, bool, AudioListener?)

Creates a sound whose samples come from a callback: a tone, noise, a synthesiser - anything with no file behind it.

public static SoundInstance CreateProceduralSound(this AudioSystem audio, SampleFiller fill, int sampleRate = 44100, bool mono = true, bool spatialized = false, bool useHrtf = false, AudioListener? listener = null)

Parameters

audio AudioSystem

The game's audio system, game.Audio.

fill SampleFiller

Produces each block of samples. Runs on the audio worker thread; see SampleFiller.

sampleRate int

Samples per second per channel.

mono bool

One channel when true, two when false.

spatialized bool

Whether the instance can be positioned with Apply3D(AudioEmitter). Mono only.

useHrtf bool

Head-related transfer function spatialisation; needs AudioEngineSettings.HrtfSupport through UseGameSettings, and works on Windows only.

listener AudioListener

The listener the instance is heard by; the engine's default listener when omitted. See AttachListener(AudioSystem, Entity).

Returns

SoundInstance

A stopped instance; call Play(). Dispose it when done.

Examples

A 440 Hz sine:

var phase = 0.0;
var tone = game.GetAudioSystem().CreateProceduralSound((samples, rate, channels) =>
{
    for (var i = 0; i < samples.Length; i++)
    {
        samples[i] = (short)(Math.Sin(phase) * short.MaxValue * 0.25);
        phase += 2 * Math.PI * 440 / rate;
    }
});
tone.Play();

Exceptions

InvalidOperationException

The audio engine is not available.

LoadWav(AudioSystem, Stream)

Reads a .wav from a stream into memory, ready to create instances from.

public static WavSound LoadWav(this AudioSystem audio, Stream stream)

Parameters

audio AudioSystem

The game's audio system, game.Audio.

stream Stream

The WAVE data, read from its current position to the end of the data chunk. Not disposed.

Returns

WavSound

Exceptions

InvalidOperationException

The audio engine is not available.

InvalidDataException

The stream is not a WAVE file, or holds a format WavSound does not decode.

LoadWav(AudioSystem, string)

Reads a .wav file into memory, ready to create instances from.

public static WavSound LoadWav(this AudioSystem audio, string path)

Parameters

audio AudioSystem

The game's audio system, game.Audio.

path string

The file. Relative paths resolve against the working directory, so prefer a path built from the executable's folder.

Returns

WavSound

The decoded sound. Keep it and call CreateInstance(bool, bool, AudioListener?) per playback.

Exceptions

InvalidOperationException

The audio engine is not available.

InvalidDataException

The file is not a WAVE file, or holds a format WavSound does not decode.