Class ProceduralSoundSource

Namespace

Stride.CommunityToolkit.Audio

Assembly

Stride.CommunityToolkit.dll

A sound generated on the fly by a callback, with no sound file and no compiled asset.

public sealed class ProceduralSoundSource : DynamicSoundSource, IDisposable

Inheritance

object

DynamicSoundSource

ProceduralSoundSource

Implements

IDisposable

Inherited Members

DynamicSoundSource.Logger

DynamicSoundSource.Dispose()

DynamicSoundSource.Play()

DynamicSoundSource.Pause()

DynamicSoundSource.Stop()

DynamicSoundSource.ReadyToPlay

DynamicSoundSource.Ended

DynamicSoundSource.IsPausedOrPlaying

DynamicSoundSource.PlayRange

Remarks

Sound - the type an AudioEmitterComponent plays - can only come out of the asset pipeline: its constructor is internal and its data is compressed at build time. The one public door into the audio engine is the SoundInstance constructor that takes a DynamicSoundSource, and this class is that source: the engine asks it for a block of samples whenever a device buffer is free, and it asks the callback.

Buffering: four buffers of Stride.CommunityToolkit.Audio.ProceduralSoundSource.FramesPerBuffer frames each, the same shape as the engine's own streaming source. At 44.1 kHz one buffer is about 93 ms, so a change the callback picks up on its next call is heard within roughly a tenth of a second.

The source and the instance reference each other and neither constructor can run first; the engine's own CompressedSoundSource solves this by passing null to the base constructor, assigning the protected soundInstance field afterwards, and adding itself to the worker's queue last. Create(AudioEngine, AudioListener, SampleFiller, int, bool, bool, bool) does the same. One trap: the SoundInstance constructor resets the instance's looping flag, which reaches SetLooped(bool) before the field is assigned - so that override must not touch the instance.

Properties

MaxNumberOfBuffers

public override int MaxNumberOfBuffers { get; }

Property Value

int

Methods

Create(AudioEngine, AudioListener, SampleFiller, int, bool, bool, bool)

Creates a playable SoundInstance whose samples come from fill.

public static SoundInstance Create(AudioEngine engine, AudioListener listener, SampleFiller fill, int sampleRate = 44100, bool mono = true, bool spatialized = false, bool useHrtf = false)

Parameters

engine AudioEngine

The audio engine, game.GetAudioSystem().AudioEngine.

listener AudioListener

The listener the instance is heard by; DefaultListener when in doubt.

fill SampleFiller

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

sampleRate int

Samples per second per channel.

mono bool

One channel when true, two when false. Spatialised sounds must be mono.

spatialized bool

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

useHrtf bool

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

Returns

SoundInstance

The instance. Disposing it disposes the source.

Exceptions

ArgumentException

spatialized without mono.

ArgumentOutOfRangeException

sampleRate is not positive.

ExtractAndFillData()

protected override void ExtractAndFillData()

SetLooped(bool)

No effect: a generated stream has no end to loop back from.

public override void SetLooped(bool looped)

Parameters

looped bool