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

From class java.lang.Object

boolean	equals(Object arg0)
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

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.