AudioAPI reference
Class AudioMixer
Namespace: MicroEngine.Audio
Assembly: MicroEngine.Audio.dll
Guide: Audio
Game-facing audio: a sound bank keyed by name plus music with fades. Games register synthesized clips once and then call Play by name.
public sealed class AudioMixerInheritance
Examples
// In Game.Load (Synth, SfxParams and Wave are in MicroEngine.Audio.Retro):Audio.AddSound("jump", Synth.Render(new SfxParams { Wave = Wave.Square, Frequency = 520, EndFrequency = 880 }));Audio.AddMusicFile("theme", "Content/theme.ogg");Audio.PlayMusic("theme");
// In a scene's Update:if (Input.Pressed("jump")) Audio.Play("jump", pitchJitter: 0.05f);Remarks
Every game has one in Game.Audio. Sounds and music are registered under names that are compared
ordinally (case-sensitive); registering a name again replaces it. On a device without hardware every call still works
and nothing is heard.
Constructors
AudioMixer(IAudioDevice)
Creates a mixer over device. Games use the one in Game.Audio.
public AudioMixer(IAudioDevice device)Parameters
device IAudioDevice
Exceptions
device is null.
Properties
CurrentMusic
Name of the music playing (also while it fades out, and while a song asked for still renders in slices), or null. It follows the game’s requests and the music’s end on the simulation’s timeline, never rendering speed.
public string? CurrentMusic { get; }Property Value
Deterministic
Whether the run is deterministic (scripted runs, tests): the device’s timeline then follows the simulation only, and songs that render in slices render only when the game waits for one, finished in the next Pump whatever SliceBudget, so the same steps give the same sound. The game sets it from its time mode.
public bool Deterministic { get; set; }Property Value
Device
The audio device the mixer plays through.
public IAudioDevice Device { get; }Property Value
MusicPaused
Whether music was paused with PauseMusic.
public bool MusicPaused { get; }Property Value
MusicVolume
Music volume, clamped to 0..1 (default 1). Applies immediately to the playing music, combined with any fade.
public float MusicVolume { get; set; }Property Value
SfxVolume
Volume multiplier for sound effects, 0..1 (default 0.8). Each played volume is multiplied by it and clamped to 0..1.
public float SfxVolume { get; set; }Property Value
Statistics
The voices of the device’s mixer: how many sounds play now, how many can play at once and how many the voice policy refused so far. Zeros for a device without the engine’s mixer (SilentAudioDevice).
public AudioStatistics Statistics { get; }Property Value
Methods
AddMusic(string, AudioClip, bool)
Registers decoded music, such as a rendered Song, under name.
public void AddMusic(string name, AudioClip clip, bool loop = true)Parameters
name string
Name used by PlayMusic.
clip AudioClip
The music samples.
loop bool
Whether the music restarts when it reaches its end.
AddMusic(string, Song, bool)
Registers a Song under name without waiting for it to be rendered: songs render
in the background, side by side, and each is handed to the device the first time it plays (waiting then only for
that song if it is not ready yet). Registering every song of a game this way keeps their synthesis out of
Load. Where the runtime has no background threads (browsers), songs render a few milliseconds per
Pump (once per frame, outside the simulation step) instead, one after another in the order they were
registered; a song asked to play before
it is ready goes first and starts once rendered (CurrentMusic already names it).
public void AddMusic(string name, Song song, bool loop = true)Parameters
name string
Name used by PlayMusic.
song Song
The song; do not change it after registering it.
loop bool
Whether the music restarts when it reaches its end.
Exceptions
The song has no steps.
A track has an invalid note or a drum track an unknown drum.
AddMusic(string, EncodedAudio, bool)
Registers a music file loaded from content (Assets.Music(path)) under name: WAV is
decoded here, other formats are decoded by the device while they play.
public void AddMusic(string name, EncodedAudio music, bool loop = true)Parameters
name string
music EncodedAudio
loop bool
Exceptions
The device does not decode that format (MP3 outside raylib, for example).
The bytes cannot be decoded as their format.
AddMusicFile(string, string, bool)
Registers a music file. WAV is decoded here; other formats are streamed by the device.
public void AddMusicFile(string name, string path, bool loop = true)Parameters
name string
path string
loop bool
Remarks
Every device decodes OGG Vorbis; the raylib device also decodes mp3.
Exceptions
The file does not exist.
AddSound(string, AudioClip)
Registers clip as the sound effect name, replacing any sound with that name.
public void AddSound(string name, AudioClip clip)Parameters
name string
clip AudioClip
AddSoundFile(string, string)
Registers a WAV file as a sound effect.
public void AddSoundFile(string name, string path)Parameters
name string
path string
Exceptions
The file does not exist.
The WAV is not 8, 16 or 24-bit PCM, mono or stereo.
HasMusic(string)
Whether music is registered under name.
public bool HasMusic(string name)Parameters
name string
Returns
HasSound(string)
Whether a sound effect is registered under name.
public bool HasSound(string name)Parameters
name string
Returns
PauseMusic(bool)
Pauses (true) or resumes (false) the music and records the state in MusicPaused.
public void PauseMusic(bool paused)Parameters
paused bool
Play(string, float, float, float, float)
Plays a sound. pitchJitter randomizes pitch (+/-) to avoid repetition fatigue.
The same sound is not retriggered within one frame, preventing volume spikes.
public void Play(string name, float volume = 1, float pitch = 1, float pitchJitter = 0, float pan = 0.5)Parameters
name string
volume float
pitch float
pitchJitter float
pan float
Exceptions
No sound is registered under name; use TryPlay for optional sounds.
PlayMusic(string, float)
Switches music. With a fade, the current track fades out before the new one starts.
public void PlayMusic(string name, float fadeSeconds = 0.4)Parameters
name string
fadeSeconds float
Remarks
With a fade, music starting from silence rises over about a quarter of a second; with fadeSeconds 0 or less it starts at full volume at once. Asking for the music that is already playing does nothing; asking for it while it fades out (towards another track or silence) cancels the fade and brings it back, without restarting it.
Exceptions
No music is registered under name.
A song registered with AddMusic failed while rendering (its content is checked when registered, so only the machine can fail it, for example out of memory); its name is then unregistered. With a fade, this surfaces from Update when the song is due to start.
Pump()
The host frame’s audio work, outside the simulation step: renders songs that render in slices (browsers), then lets the device decode streamed music ahead and pump its sink. The game calls it once per frame; call it yourself only for a mixer you created.
public void Pump()StopMusic(float)
Stops the music, fading it out over fadeSeconds; 0 or less stops it at once.
public void StopMusic(float fadeSeconds = 0.4)Parameters
fadeSeconds float
TryPlay(string, float, float, float, float)
Plays a sound if it is registered; returns false otherwise (useful for optional cues).
public bool TryPlay(string name, float volume = 1, float pitch = 1, float pitchJitter = 0, float pan = 0.5)Parameters
name string
volume float
pitch float
pitchJitter float
pan float
Returns
Update(float)
Advances music fades and ends the device’s simulation step. The game calls it once per update; call it yourself only for a mixer you created.
public void Update(float dt)Parameters
dt float
Elapsed time in seconds.