Urho.Audio Namespace

The audio subsystem implementation

Remarks

The Audio subsystem implements an audio output stream. Once it has been initialized, the following operations are supported:

  • Playing raw audio, Ogg Vorbis or WAV Sound resources using the SoundSource component. This allows manual stereo panning of mono sounds; stereo sounds will be output with their original stereo mix.
  • Playing the above sound formats in pseudo-3D using the SoundSource3D component. It has stereo positioning and distance attenuation, but does not (at least yet) filter the sound depending on the direction.

To hear pseudo-3D positional sounds, a SoundListener component must exist in a scene node and be assigned to the audio subsystem by setting the Audio.Listener property. If the sound listener's scene node exists within a specific scene, it will only hear sounds from that scene, but if it has been created into a "sceneless" node it will hear sounds from all scenes.

The output is software mixed for an unlimited amount of simultaneous sounds. Ogg Vorbis sounds are decoded on the fly, and decoding them can be memory- and CPU-intensive, so WAV files are recommended when a large number of short sound effects need to be played.

For purposes of volume control, each SoundSource can be classified into a user defined group which is multiplied with a master category and the individual SoundSource gain set using SoundSource.Gain for the final volume level.

To control the category volumes, set the Audio.SetMasterGain, which defines the category if it didn't already exist.

The SoundSource components support automatic removal from the node they belong to, once playback is finished. To use, set the Urho.Audio.SoundSource.AutoRemove property on them. This may be useful when a game object plays several "fire and forget" sound effects.

Sound Parameters

A standard WAV file can not tell whether it should loop, and raw audio does not contain any header information. Parameters for the. resource can optionally be specified through an XML file that has the same name as the sound, but .xml extension. Possible elements are “format” which allows optional attributes “frequency” (and a value in Hz), “sixteenbits” (with either “true” and “false” values) and “stereo” (with either “true” and “false” values).  The other element is “loop” and it allows the optional attributes “enable” (with either “true” and “false” values) and “start” and “end” 

The frequency is in Hz, and loop start and end are bytes from the start of audio data. If a loop is enabled without specifying the start and end, it is assumed to be the whole sound. Ogg Vorbis compressed sounds do not support specifying the loop range, only whether whole sound looping is enabled or disabled.

The . subsystem is always instantiated, but in headless mode it is not active. In headless mode the playback of sounds is simulated, taking the sound length and frequency into account. This allows basing logic on whether a specific sound is still playing or not, even in server code.

Sound Streaming

In addition to playing existing sound resources, sound can be generated during runtime using the SoundSource  class and its subclasses. To start playback of a stream on a SoundSource, call SoundSource.Play(SoundStream).

Sound streaming is used internally to implement on-the-fly Ogg Vorbis decoding. See the SoundSynthesis sample for an example of using the BufferedSoundStream subclass, which allows the sound data to be queued for playback from the main thread.

Classes

TypeReason
Audio Audio subsystem, used to playback both regular audio and 3D sound.
BufferedSoundStreamSound stream that supports manual buffering of data from the main thread.
OggVorbisSoundStream Ogg Vorbis sound stream.
SoundSound resource.
SoundListenerSound listener component
SoundSourceSound source component with stereo position.
SoundSource3DSound source component with three-dimensional position.
SoundStream Base class for sound streams.