MoonWorks-docs/content/Audio/_index.md

title	date	weight
Audio	2021-01-24T20:15:28-08:00	4

MoonWorks.Audio is implemented using the FAudio library. The main entry point for audio-related functions is AudioDevice. A reference to this class is automatically created and can be retrieved from your Game subclass.

There are two main kinds of audio content: static and streaming. MoonWorks supports WAV and Ogg Vorbis files by default, but you can support whatever kind of audio file you want by providing a custom decoder of your choice.

Static Audio

Static audio is loaded completely into memory, and multiple "instances" of the audio can be created and played. This kind of audio is ideal for short sound effects that may be played simultaneously.

The trade-off is that static audio takes a lot more memory than streaming audio, since the entire sound must be stored in memory in order to be played. This kind of audio is not a good choice for things like long music tracks.

To load and play a static sound, you would do something like this:

var jumpSoundEffect = StaticSound.LoadWav(AudioDevice, "jump.wav");
var jumpSoundEffectInstance = jumpSoundEffect.CreateInstance();

jumpSoundEffectInstance.Play();

Static audio can be loaded from a WAV or Ogg Vorbis file.

Streaming Audio

Streaming audio is streamed from file storage over its duration, and only a small portion of the audio is stored in memory while it is played. This kind of audio is ideal for recorded dialogue and music.

The trade-off here is that streaming audio needs to be read continuously and decoded from memory, which may be slow. If you stream too much audio at once you may notice audio stuttering.

To load and play streaming sound, you would do something like this:

var music = StreamingSoundOgg.Load(AudioDevice, "my_music.ogg");
music.Play();

By default MoonWorks only provides Ogg Vorbis streaming, if you want to stream other kinds of audio you will need to hook up a decoder function.

Effects

MoonWorks.Audio sound playback can be modified with several effects, such as panning, reverb, pass filters, and more. To apply these effects, simply set the relevant properties on the sound instance.

jumpSoundEffectInstance.Reverb = 1.5f;
jumpSoundEffectInstance.Pitch = -0.25f;
jumpSoundEffectInstance.Pan = -0.5f;
jumpSoundEffectInstance.Play();

3D Audio

MoonWorks has support for 3-dimensional audio. To use it, you must create an AudioListener, and any sounds that are emitted in 3-dimensional space should use an AudioEmitter. Emitters and listeners use position, orientation, and velocity to determine audio playback. Then you can call Apply3D on a sound effect instance and provide the emitter and listener.

var audioEmitter = new AudioEmitter(AudioDevice);
var audioListener = new AudioListener(AudioDevice);

audioEmitter.Position = thingPosition;
audioEmitter.Forward = thingForward;
audioEmitter.Up = thingUp;
audioEmitter.Velocity = thingVelocity;

audioListener.Position = cameraPosition;
audioListener.Forward = cameraForward;
audioListener.Up = cameraUp;
audioListener.Velocity = cameraVelocity;

thingSound.Apply3D(audioListener, audioEmitter);