Version

Concrete implementations of the Mixer class can be instantiated with CreateMixer to play sound and music.

Audio resource

The mixer API can replay two kind of audio sources: Sound and stream.

  • A sound is played from memory, this is usually the fastest resource to play. However, since it must fully be stored in memory longer audio samples are best streamed.
  • A stream is read from storage in small increments as it is being played by the platform hardware. While it consumes very little memory a stream is usually more performance taxing as it requires constant access to storage and processor time to decode.

It is recommended to use sounds for short, ponctual effects and streams for background music or narrative talk-over.

Audio channel

A mixer implementation manages a finite number of audio channels. A channel can only play a single audio source at a time. The mixer will automatically select a free channel when asked to play an audio source. If no free channel is available the playback request will fail and ChannelError is returned.

Each channel has a set of independently configurable properties that can be specified when calling Start and Stream using a MixerChannelState object. The current state of a channel can be retrieved using GetChannelState.

Channel priority

In order to prevent situations where an important audio source cannot be played due to a lack of free channel, each playing channel is assigned a priority. When a new play request is submitted the mixer looks for a non-playing channel and if it cannot find any for the playing channel with the lowest priority.

Playing sound and stream

In order to play a sound it must first be loaded using LoadSound, the returned object can then be passed to Start which returns the channel on which the sound is now playing.

Playing a stream only requires to call Stream with the path to the stream data file.

The GetPlayState function can be used to determine if a channel is playing, paused or stopped.

Looping

Sound and stream can be set to repeat after the last sample has been played by setting the MixerLoopMode of the current MixerChannelState. Additionally, stream's loop point can be specified in millisecond by using SetStreamLoopPoint. This is useful to skip a background music intro part when looping.

Loop properties can be changed during playback.

Spacialization

Each channel has a set of independently configurable spacialization properties such as position and velocity. Both values are specified in the 3d world coordinates system as Vector3.

The mixer supports a single listener which is defined by a transformation matrix (see TransformationMatrix).