GvrAudioEngine

public class GvrAudioEngine

Engine to spatialize sound sources in 3D space.

The GvrAudioEngine allows the user to spatialize sound sources in 3D space, including distance and height cues. The GvrAudioEngine is capable of playing back spatial sound in two separate ways:

  • The first method, known as Sound Object rendering, allows the user to create a virtual sound source in 3D space. These sources, while spatialized, are fed with mono audio data. Caution is encouraged when using very loud (e.g. 0dB FS normalized) mono audio data, audio data that has been heavily dynamic range compressed or when using multiple sources. In order to avoid clipping, individual sound object volumes can be reduced by calling setSoundVolume() method.
  • The second method allows the user to play back Ambisonic soundfield recordings. Ambisonic recordings are multi-channel audio files which are spatialized all around the listener in 360 degrees. These can be thought of as recorded or prebaked soundfields. They can be of great use for creating spatialized background effects. Examples include rain, crowd noise or even the sound of the ocean off to one side. Full 3D First Order Ambisonic recordings are supported which use ACN channel ordering and SN3D normalization (for more information please see Spatial Audio specification).
  • The third method, referred to here as Stereo Sounds, allow the user to directly play back non-spatialized mono or stereo audio files. This is useful for music and other such audio.

Nested Classes

class GvrAudioEngine.DistanceRolloffModel Defines constants representing different distance effect rolloff models. 
class GvrAudioEngine.MaterialName Defines constants representing the surface materials for use with room effects. 
class GvrAudioEngine.RenderingMode Defines constants to adjust rendering mode. 

Constants

int INVALID_ID Invalid sound object id.

Public Constructors

GvrAudioEngine(Context context, int renderingMode)
Constructs the GVR Audio system with an Android context and GvrAudioEngine.RenderingMode.

Public Methods

int
createSoundObject(String filename)
Returns a new sound object handle.
int
createSoundfield(String filename)
Returns a new Ambisonic soundfield handle.
int
createStereoSound(String filename)
Returns a new non-spatialized stereo sound.
void
enableRoom(boolean enable)
Turns on/off the room reverberation effects.
void
enableSpeakerStereoMode(boolean enable)
Enables the stereo speaker mode.
boolean
isSoundPlaying(int sourceId)
Checks if a sound is playing.
boolean
isSourceIdValid(int sourceId)
Checks if a |sourceId| is valid, and that the corresponding source is in a playable state.
void
pause()
Pauses the GVR Audio system.
void
pauseSound(int sourceId)
Pauses the playback of a sound.
void
playSound(int sourceId, boolean loopingEnabled)
Starts the playback of a sound.
boolean
preloadSoundFile(String filename)
Preloads a sound file.
void
resume()
Resumes the GVR Audio system.
void
resumeSound(int sourceId)
Resumes the playback of a sound.
void
setHeadPosition(float x, float y, float z)
Sets the head position.
void
setHeadRotation(float x, float y, float z, float w)
Sets the head rotation.
void
setRoomProperties(float sizeX, float sizeY, float sizeZ, int wallMaterial, int ceilingMaterial, int floorMaterial)
Sets the room properties describing the dimensions and surface materials of a given room.
void
setRoomReverbAdjustments(float gain, float timeAdjust, float brightnessAdjust)
Adjusts the properties of the current reverb, allowing changes to the reverb's gain, duration and low/high frequency balance.
void
setSoundObjectDistanceRolloffModel(int soundObjectId, int rolloffModel, float minDistance, float maxDistance)
Sets the given sound object source's distance attenuation method with minimum and maximum distances.
void
setSoundObjectPosition(int soundObjectId, float x, float y, float z)
Repositions an existing sound object.
void
setSoundVolume(int sourceId, float volume)
Changes the volume of an existing sound.
void
setSoundfieldRotation(int soundfieldId, float x, float y, float z, float w)
Sets the rotation of an existing Ambisonic soundfield.
void
stopSound(int sourceId)
Stops the playback of a sound and destroys the corresponding Sound Object or Soundfield.
void
unloadSoundFile(String filename)
Unloads a sound file from the sample cache.
void
update()
The update method must be called from the main thread at a regular rate.

Inherited Methods

Constants

public static final int INVALID_ID

Invalid sound object id.

Constant Value: -1

Public Constructors

public GvrAudioEngine (Context context, int renderingMode)

Constructs the GVR Audio system with an Android context and GvrAudioEngine.RenderingMode.

Parameters
context Android context.
renderingMode chooses the configuration preset

Public Methods

public int createSoundObject (String filename)

Returns a new sound object handle. Note that the sample should only contain a single audio channel (stereo sources are automatically downmixed to mono). The handle automatically destroys itself at the moment the sound playback has stopped.

Parameters
filename path/name of the file to be played
Returns
  • id of new sound object. Returns INVALID_ID if the sound file could not be loaded

public int createSoundfield (String filename)

Returns a new Ambisonic soundfield handle. Note that the sample must have 4 audio channels. Ambisonic soundfields do *not* need to be preloaded. They are directly streamed and rendered from the compressed audio file. The handle automatically destroys itself at the moment the sound playback has stopped.

Parameters
filename path/name of the file to be played
Returns
  • id of new soundfield. Returns INVALID_ID if the sound file could not be loaded

public int createStereoSound (String filename)

Returns a new non-spatialized stereo sound. Note that the sample must have at most two audio channels. Both mono and stereo audio files are supported. The handle automatically destroys itself at the moment the sound playback has stopped.

Parameters
filename path/name of the file to be played
Returns
  • id of new soundfield. Returns INVALID_ID if the sound file could not be loaded

public void enableRoom (boolean enable)

Turns on/off the room reverberation effects.

Parameters
enable true to enable room effects

public void enableSpeakerStereoMode (boolean enable)

Enables the stereo speaker mode.

It enforces stereo-panning when headphone are not plugged into the phone. This helps to avoid HRTF-based coloring effects and reduces computational complexity when speaker playback is active. By default the stereo speaker mode optimization is disabled. Note that switching between rendering modes can lead to varying CPU usage based on the audio output routing.

Parameters
enable true to enable the speaker stereo mode

public boolean isSoundPlaying (int sourceId)

Checks if a sound is playing.

Parameters
sourceId id of the audio source to be checked
Returns
  • true if the sound is being played

public boolean isSourceIdValid (int sourceId)

Checks if a |sourceId| is valid, and that the corresponding source is in a playable state. Sources that have been stopped will be reported as invalid.

Parameters
sourceId id of the audio source to be checked
Returns
  • true if the source exists and is in a playable state

public void pause ()

Pauses the GVR Audio system.

public void pauseSound (int sourceId)

Pauses the playback of a sound.

Parameters
sourceId id of the audio source to be paused

public void playSound (int sourceId, boolean loopingEnabled)

Starts the playback of a sound.

Parameters
sourceId id of the audio source to be stopped
loopingEnabled enables looped playback

public boolean preloadSoundFile (String filename)

Preloads a sound file. This method can be used for both mono and Ambisonic sound files.

Parameters
filename path/name of the file to be played
Returns
  • true on success

public void resume ()

Resumes the GVR Audio system.

public void resumeSound (int sourceId)

Resumes the playback of a sound.

Parameters
sourceId id of the audio source to be resumed

public void setHeadPosition (float x, float y, float z)

Sets the head position.

Parameters
x x coordinate of head position in world space
y y coordinate of head position in world space
z z coordinate of head position in world space

public void setHeadRotation (float x, float y, float z, float w)

Sets the head rotation.

Parameters
x x component of quaternion
y y component of quaternion
z z component of quaternion
w w component of quaternion

public void setRoomProperties (float sizeX, float sizeY, float sizeZ, int wallMaterial, int ceilingMaterial, int floorMaterial)

Sets the room properties describing the dimensions and surface materials of a given room.

Parameters
sizeX dimension along X axis
sizeY dimension along Y axis
sizeZ dimension along Z axis
wallMaterial MaterialName id for the four walls
ceilingMaterial MaterialName id for the ceiling
floorMaterial MaterialName id for the floor

public void setRoomReverbAdjustments (float gain, float timeAdjust, float brightnessAdjust)

Adjusts the properties of the current reverb, allowing changes to the reverb's gain, duration and low/high frequency balance.

Parameters
gain reverb volume (linear) adjustment in range [0, 1] for attenuation, range [1, inf) for gain boost
timeAdjust reverb time adjustment multiplier to scale the reverberation tail length.
brightnessAdjust reverb brightness adjustment that controls the reverberation ratio across low and high frequency bands

public void setSoundObjectDistanceRolloffModel (int soundObjectId, int rolloffModel, float minDistance, float maxDistance)

Sets the given sound object source's distance attenuation method with minimum and maximum distances. Maximum distance must be greater than the minimum distance for the method to be set.

Parameters
soundObjectId id of sound object source
rolloffModel DistanceRolloffModel, note setting the rolloff model to DistanceRolloffModel::NONE will allow distance attenuation to be set manually
minDistance minimum distance to apply distance attenuation method
maxDistance maximum distance to apply distance attenuation method

public void setSoundObjectPosition (int soundObjectId, float x, float y, float z)

Repositions an existing sound object.

Parameters
soundObjectId id of the sound object to be moved
x x coordinate the sound will be placed at
y y coordinate the sound will be placed at
z z coordinate the sound will be placed at

public void setSoundVolume (int sourceId, float volume)

Changes the volume of an existing sound.

Parameters
sourceId id of the audio source to be modified
volume volume value. Should range from 0 (mute) to 1 (max)

public void setSoundfieldRotation (int soundfieldId, float x, float y, float z, float w)

Sets the rotation of an existing Ambisonic soundfield.

Parameters
soundfieldId id of the Ambisonic soundfield to be rotated
x x component of the quaternion describing the rotation
y y component of the quaternion describing the rotation
z z component of the quaternion describing the rotation
w w component of the quaternion describing the rotation

public void stopSound (int sourceId)

Stops the playback of a sound and destroys the corresponding Sound Object or Soundfield.

Parameters
sourceId id of the audio source to be stopped

public void unloadSoundFile (String filename)

Unloads a sound file from the sample cache. Note that memory is freed at the moment the playback of the sound file stops.

Parameters
filename of sound file to be freed from memory

public void update ()

The update method must be called from the main thread at a regular rate. It is used to execute background operations outside of the audio thread.