Spatializer
public
class
Spatializer
extends Object
java.lang.Object | |
↳ | android.media.Spatializer |
Spatializer provides access to querying capabilities and behavior of sound spatialization
on the device.
Sound spatialization simulates sounds originating around the listener as if they were coming
from virtual speakers placed around the listener.
Support for spatialization is optional, use AudioManager#getSpatializer()
to obtain an
instance of this class if the feature is supported.
Summary
Nested classes | |
---|---|
interface |
Spatializer.OnHeadTrackerAvailableListener
Interface to be notified of changes to the availability of a head tracker on the audio device to be used by the spatializer effect. |
interface |
Spatializer.OnSpatializerStateChangedListener
An interface to be notified of changes to the state of the spatializer effect. |
Constants | |
---|---|
int |
SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL
Constant indicating the |
int |
SPATIALIZER_IMMERSIVE_LEVEL_NONE
Constant indicating there are no spatialization capabilities supported on this device. |
int |
SPATIALIZER_IMMERSIVE_LEVEL_OTHER
Constant indicating the |
Public methods | |
---|---|
void
|
addOnHeadTrackerAvailableListener(Executor executor, Spatializer.OnHeadTrackerAvailableListener listener)
Adds a listener to be notified of changes to the availability of a head tracker. |
void
|
addOnSpatializerStateChangedListener(Executor executor, Spatializer.OnSpatializerStateChangedListener listener)
Adds a listener to be notified of changes to the enabled state of the
|
boolean
|
canBeSpatialized(AudioAttributes attributes, AudioFormat format)
Returns whether audio of the given |
int
|
getImmersiveAudioLevel()
Return the level of support for the spatialization feature on this device. |
boolean
|
isAvailable()
Returns whether spatialization is available. |
boolean
|
isEnabled()
Returns whether spatialization is enabled or not. |
boolean
|
isHeadTrackerAvailable()
Returns whether a head tracker is currently available for the audio device used by the spatializer effect. |
void
|
removeOnHeadTrackerAvailableListener(Spatializer.OnHeadTrackerAvailableListener listener)
Removes a previously registered listener for the availability of a head tracker. |
void
|
removeOnSpatializerStateChangedListener(Spatializer.OnSpatializerStateChangedListener listener)
Removes a previously added listener for changes to the enabled state of the
|
Inherited methods | |
---|---|
Constants
SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL
public static final int SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL
Constant indicating the Spatializer
on this device supports multichannel
spatialization.
See also:
Constant Value: 1 (0x00000001)
SPATIALIZER_IMMERSIVE_LEVEL_NONE
public static final int SPATIALIZER_IMMERSIVE_LEVEL_NONE
Constant indicating there are no spatialization capabilities supported on this device.
See also:
Constant Value: 0 (0x00000000)
SPATIALIZER_IMMERSIVE_LEVEL_OTHER
public static final int SPATIALIZER_IMMERSIVE_LEVEL_OTHER
Constant indicating the Spatializer
on this device supports a spatialization
mode that differs from the ones available at this SDK level.
See also:
Constant Value: -1 (0xffffffff)
Public methods
addOnHeadTrackerAvailableListener
public void addOnHeadTrackerAvailableListener (Executor executor, Spatializer.OnHeadTrackerAvailableListener listener)
Adds a listener to be notified of changes to the availability of a head tracker.
Parameters | |
---|---|
executor |
Executor : the Executor handling the callback
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
Spatializer.OnHeadTrackerAvailableListener : the listener to receive availability updates
This value cannot be null . |
addOnSpatializerStateChangedListener
public void addOnSpatializerStateChangedListener (Executor executor, Spatializer.OnSpatializerStateChangedListener listener)
Adds a listener to be notified of changes to the enabled state of the
Spatializer
.
Parameters | |
---|---|
executor |
Executor : the Executor handling the callback
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
Spatializer.OnSpatializerStateChangedListener : the listener to receive enabled state updates
This value cannot be null . |
See also:
canBeSpatialized
public boolean canBeSpatialized (AudioAttributes attributes, AudioFormat format)
Returns whether audio of the given AudioFormat
, played with the given
AudioAttributes
can be spatialized.
Note that the result reflects the capabilities of the device and may change when
audio accessories are connected/disconnected (e.g. wired headphones plugged in or not).
The result is independent from whether spatialization processing is enabled or not.
Parameters | |
---|---|
attributes |
AudioAttributes : the AudioAttributes of the content as used for playback
This value cannot be null . |
format |
AudioFormat : the AudioFormat of the content as used for playback
This value cannot be null . |
Returns | |
---|---|
boolean |
true if the device is capable of spatializing the combination of audio format
and attributes, false otherwise. |
getImmersiveAudioLevel
public int getImmersiveAudioLevel ()
Return the level of support for the spatialization feature on this device.
This level of support is independent of whether the Spatializer
is currently
enabled or available and will not change over time.
Returns | |
---|---|
int |
the level of spatialization support
Value is SPATIALIZER_IMMERSIVE_LEVEL_OTHER , SPATIALIZER_IMMERSIVE_LEVEL_NONE , or SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL |
See also:
isAvailable
public boolean isAvailable ()
Returns whether spatialization is available.
Reasons for spatialization being unavailable include situations where audio output is
incompatible with sound spatialization, such as playback on a monophonic speaker.
Note that spatialization can be available, but disabled by the user, in which case this
method would still return true
, whereas isEnabled()
would return false
.
Also when the feature is not supported on the device (indicated
by getImmersiveAudioLevel()
returning SPATIALIZER_IMMERSIVE_LEVEL_NONE
),
the return value will be false.
Returns | |
---|---|
boolean |
true if the spatializer effect is available and capable
of processing the audio for the current configuration of the device,
false otherwise. |
See also:
isEnabled
public boolean isEnabled ()
Returns whether spatialization is enabled or not.
A false value can originate for instance from the user electing to
disable the feature, or when the feature is not supported on the device (indicated
by getImmersiveAudioLevel()
returning SPATIALIZER_IMMERSIVE_LEVEL_NONE
).
Note that this state reflects a platform-wide state of the "desire" to use spatialization,
but availability of the audio processing is still dictated by the compatibility between
the effect and the hardware configuration, as indicated by isAvailable()
.
Returns | |
---|---|
boolean |
true if spatialization is enabled |
See also:
isHeadTrackerAvailable
public boolean isHeadTrackerAvailable ()
Returns whether a head tracker is currently available for the audio device used by the spatializer effect.
Returns | |
---|---|
boolean |
true if a head tracker is available and the effect is enabled, false otherwise. |
removeOnHeadTrackerAvailableListener
public void removeOnHeadTrackerAvailableListener (Spatializer.OnHeadTrackerAvailableListener listener)
Removes a previously registered listener for the availability of a head tracker.
Parameters | |
---|---|
listener |
Spatializer.OnHeadTrackerAvailableListener : the listener previously registered with
addOnHeadTrackerAvailableListener(java.util.concurrent.Executor, android.media.Spatializer.OnHeadTrackerAvailableListener)
This value cannot be null . |
removeOnSpatializerStateChangedListener
public void removeOnSpatializerStateChangedListener (Spatializer.OnSpatializerStateChangedListener listener)
Removes a previously added listener for changes to the enabled state of the
Spatializer
.
Parameters | |
---|---|
listener |
Spatializer.OnSpatializerStateChangedListener : the listener to receive enabled state updates
This value cannot be null . |
See also:
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-11 UTC.