Virtualizer

An audio virtualizer is a general name for an effect to spatialize audio channels. The exact
behavior of this effect is dependent on the number of audio input channels and the types and
number of audio output channels of the device. For example, in the case of a stereo input and
stereo headphone output, a stereo widening effect is used when this effect is turned on.

An application creates a Virtualizer object to instantiate and control a virtualizer engine
in the audio framework.

The methods, parameter types and units exposed by the Virtualizer implementation are directly
mapping those defined by the OpenSL ES 1.0.1 Specification (http://www.khronos.org/opensles/)
for the SLVirtualizerItf interface. Please refer to this specification for more details.

To attach the Virtualizer to a particular AudioTrack or MediaPlayer, specify the audio session
ID of this AudioTrack or MediaPlayer when constructing the Virtualizer.

NOTE: attaching a Virtualizer to the global audio output mix by use of session 0 is
deprecated.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

VIRTUALIZATION_MODE_BINAURAL

A virtualization mode typically used over headphones.
Binaural virtualization describes an audio processing configuration for virtualization
where the left and right channels are respectively reaching the left and right ear of the
user, without also feeding the opposite ear (as is the case when listening over speakers).

Such a mode is therefore meant to be used when audio is playing over stereo wired
headphones or headsets, but also stereo headphones through a wireless A2DP Bluetooth link.

VIRTUALIZATION_MODE_TRANSAURAL

A virtualization mode typically used over speakers.
Transaural virtualization describes an audio processing configuration that differs from
binaural (as described in VIRTUALIZATION_MODE_BINAURAL in that cross-talk is
present, i.e. audio played from the left channel also reaches the right ear of the user,
and vice-versa.

When supported, such a mode is therefore meant to be used when audio is playing over the
built-in stereo speakers of a device, if they are featured.

Public constructors

Virtualizer

int: the priority level requested by the application for controlling the Virtualizer
engine. As the same engine can be shared by several applications, this parameter indicates
how much the requesting application needs control of effect parameters. The normal priority
is 0, above normal is a positive number, below normal a negative number.

audioSession

int: system wide unique audio session identifier. The Virtualizer will
be attached to the MediaPlayer or AudioTrack in the same audio session.

Public methods

canVirtualize

Checks if the combination of a channel mask and virtualization mode is supported by this
virtualizer.
Some virtualizer implementations may only support binaural processing (i.e. only support
headphone output, see VIRTUALIZATION_MODE_BINAURAL), some may support transaural
processing (i.e. for speaker output, see VIRTUALIZATION_MODE_TRANSAURAL) for the
built-in speakers. Use this method to query the virtualizer implementation capabilities.

true if the combination of channel mask and virtualization mode is supported, false
otherwise.
An indication that a certain channel mask is not supported doesn't necessarily mean
you cannot play content with that channel mask, it more likely implies the content will
be downmixed before being virtualized. For instance a virtualizer that only supports a
mask such as CHANNEL_OUT_STEREO
will still be able to process content with a mask of
CHANNEL_OUT_5POINT1, but will downmix the content to stereo first, and
then will virtualize, as opposed to virtualizing each channel individually.

getSpeakerAngles

Queries the virtual speaker angles (azimuth and elevation) for a combination of a channel
mask and virtualization mode.
If the virtualization configuration (mask and mode) is supported (see
canVirtualize(int, int), the array angles will contain upon return the
definition of each virtual speaker and its azimuth and elevation angles relative to the
listener.
Note that in some virtualizer implementations, the angles may be strength-dependent.

int: a non-null array whose length is 3 times the number of channels in the channel
mask.
If the method indicates the configuration is supported, the array will contain upon return
triplets of values: for each channel i among the channels of the mask:

setStrength

Sets the strength of the virtualizer effect. If the implementation does not support per mille
accuracy for setting the strength, it is allowed to round the given strength to the nearest
supported value. You can use the getRoundedStrength() method to query the
(possibly rounded) value that was actually set.

Parameters

strength

short: strength of the effect. The valid range for strength strength is [0, 1000],
where 0 per mille designates the mildest effect and 1000 per mille designates the strongest.