AudioAPI reference
Class AudioEngine
Namespace: MicroEngine.Audio
Assembly: MicroEngine.Audio.dll
Guide: Audio
The engine’s one mixer: game code plays sounds here on the main thread, a sink renders them. Every backend plays through it, so voices, priorities, stealing, buses and fades behave the same everywhere, and an offline sink renders exactly what a device would play.
public sealed class AudioEngine : IDisposableInheritance
Implements
Remarks
Time is counted in simulation steps ([Advance](/docs/api/microengine.audio.audioengine/#MicroEngine_Audio_AudioEngine_Advance), once per fixed step). A sound starts at an exact output frame: its step's frame plus [DelayFrames](/docs/api/microengine.audio.audioengine/#MicroEngine_Audio_AudioEngine_DelayFrames) (at least the sink's latency), so the output does not depend on the block sizes the sink asks for. The voice policy runs on the main thread, against that timeline, never against what the sink has rendered: which sound plays is the same on every backend and in every run.
Commands reach the render function through a single-producer, single-consumer queue; rendering never allocates, locks or reads files. Music streams are decoded ahead in [Pump](/docs/api/microengine.audio.audioengine/#MicroEngine_Audio_AudioEngine_Pump), outside the simulation step.
Constructors
AudioEngine(IAudioSink, AudioEngineSettings?)
Creates the mixer and starts sink rendering it.
public AudioEngine(IAudioSink sink, AudioEngineSettings? settings = null)Parameters
sink IAudioSink
settings AudioEngineSettings?
Exceptions
The sink’s format is not 1 or 2 channels at a positive rate, or a setting is out of range.
Fields
MasterBus
The bus every other bus plays into.
public const string MasterBus = "master"Field Value
MusicBus
The bus music plays through.
public const string MusicBus = "music"Field Value
SfxBus
The default bus of sounds.
public const string SfxBus = "sfx"Field Value
Properties
ActiveVoices
Sounds playing now on the mixer’s timeline.
public int ActiveVoices { get; }Property Value
Buses
The buses, “master”, “sfx” and “music” first.
public IReadOnlyList<AudioBus> Buses { get; }Property Value
DelayFrames
Frames between a step and the sounds it starts.
public int DelayFrames { get; }Property Value
Deterministic
Whether the timeline follows the simulation only (true: the same sounds in every run, as deterministic runs need) or also catches up with the sink after the game fell behind it (false, the default for real-time play).
public bool Deterministic { get; set; }Property Value
DroppedCommands
Commands lost because the sink stopped reading them (its queue was full).
public int DroppedCommands { get; }Property Value
Format
The sink’s format, which the mixer renders.
public AudioFormat Format { get; }Property Value
MaxVoices
Sounds that can play at once.
public int MaxVoices { get; }Property Value
Now
The output frame the current step’s sounds start at (the step’s frame plus DelayFrames).
public long Now { get; }Property Value
RefusedSounds
Sounds the voice policy refused because every voice played something of higher priority.
public int RefusedSounds { get; }Property Value
RenderedFrames
Frames rendered so far (read from any thread).
public long RenderedFrames { get; }Property Value
Steps
Simulation steps counted by Advance.
public long Steps { get; }Property Value
StreamAheadFrames
Output frames of each music stream decoded ahead.
public int StreamAheadFrames { get; }Property Value
Methods
AddBus(string, string)
Creates a bus playing into parent.
public AudioBus AddBus(string name, string parent = "master")Parameters
name string
parent string
Returns
Exceptions
A bus already has that name.
parent does not exist.
The engine has 32 buses already.
Advance()
Ends a simulation step: sounds played from now on start one step later. The game calls it once per fixed step.
public void Advance()Bus(string)
The bus named name.
public AudioBus Bus(string name)Parameters
name string
Returns
Exceptions
No such bus.
Dispose()
Stops the sink (it no longer renders after this returns) and the streams.
public void Dispose()IsPlaying(VoiceHandle)
Whether voice is still playing (or paused, or fading out) on the mixer’s timeline.
public bool IsPlaying(VoiceHandle voice)Parameters
voice VoiceHandle
Returns
Pause(VoiceHandle, bool)
Pauses (true) or resumes (false) voice from the current step’s frame; a paused sound keeps its voice.
public bool Pause(VoiceHandle voice, bool paused)Parameters
voice VoiceHandle
paused bool
Returns
Whether it was playing.
Play(AudioClip, in PlayParameters)
Plays clip from the current step’s frame; returns its handle, or None when the voice policy refused it.
public VoiceHandle Play(AudioClip clip, in PlayParameters parameters)Parameters
clip AudioClip
parameters PlayParameters
Returns
Exceptions
The bus does not exist.
Play(IAudioStream, in PlayParameters)
Plays stream (music decoded while it plays); the engine disposes it when the sound ends or is stopped.
public VoiceHandle Play(IAudioStream stream, in PlayParameters parameters)Parameters
stream IAudioStream
parameters PlayParameters
Returns
Exceptions
The bus does not exist.
Pump()
The host frame’s audio work, on the main thread outside the simulation step: decodes music streams ahead, frees streams that ended, then pumps the sink (which renders here when it is pumped by the host).
public void Pump()Render(Span<float>)
The render function the sink calls (AudioRender): mixes the next frames into buffer.
public void Render(Span<float> buffer)Parameters
Set(VoiceHandle, float?, float?)
Changes the volume (0..1) and pan (0..1) of voice from the current step’s frame; null keeps a value.
public bool Set(VoiceHandle voice, float? volume = null, float? pan = null)Parameters
voice VoiceHandle
volume float?
pan float?
Returns
Whether it was playing.
StepFrame(long)
The first output frame of simulation step step.
public long StepFrame(long step)Parameters
step long
Returns
Stop(VoiceHandle, double)
Stops voice at the current step’s frame, fading it out over fadeSeconds.
public bool Stop(VoiceHandle voice, double fadeSeconds = 0)Parameters
voice VoiceHandle
fadeSeconds double
Returns
Whether it was playing.