Spatializer
open class Spatializer
kotlin.Any | |
↳ | 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 | |
---|---|
abstract |
Interface to be notified of changes to the availability of a head tracker on the audio device to be used by the spatializer effect. |
abstract |
An interface to be notified of changes to the state of the spatializer effect. |
Constants | |
---|---|
static Int |
Constant indicating the |
static Int |
Constant indicating there are no spatialization capabilities supported on this device. |
static Int |
Constant indicating the |
Public methods | |
---|---|
open Unit |
addOnHeadTrackerAvailableListener(executor: Executor, listener: Spatializer.OnHeadTrackerAvailableListener) Adds a listener to be notified of changes to the availability of a head tracker. |
open Unit |
addOnSpatializerStateChangedListener(executor: Executor, listener: Spatializer.OnSpatializerStateChangedListener) Adds a listener to be notified of changes to the enabled state of the |
open Boolean |
canBeSpatialized(attributes: AudioAttributes, format: AudioFormat) Returns whether audio of the given |
open Int |
Return the level of support for the spatialization feature on this device. |
open Boolean |
Returns whether spatialization is available. |
open Boolean |
Returns whether spatialization is enabled or not. |
open Boolean |
Returns whether a head tracker is currently available for the audio device used by the spatializer effect. |
open Unit |
Removes a previously registered listener for the availability of a head tracker. |
open Unit |
Removes a previously added listener for changes to the enabled state of the |
Constants
SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL
static val SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL: Int
Constant indicating the Spatializer
on this device supports multichannel spatialization.
Value: 1
See Also
SPATIALIZER_IMMERSIVE_LEVEL_NONE
static val SPATIALIZER_IMMERSIVE_LEVEL_NONE: Int
Constant indicating there are no spatialization capabilities supported on this device.
Value: 0
See Also
SPATIALIZER_IMMERSIVE_LEVEL_OTHER
static val SPATIALIZER_IMMERSIVE_LEVEL_OTHER: Int
Constant indicating the Spatializer
on this device supports a spatialization mode that differs from the ones available at this SDK level.
Value: -1
See Also
Public methods
addOnHeadTrackerAvailableListener
open fun addOnHeadTrackerAvailableListener(
executor: Executor,
listener: Spatializer.OnHeadTrackerAvailableListener
): Unit
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
open fun addOnSpatializerStateChangedListener(
executor: Executor,
listener: Spatializer.OnSpatializerStateChangedListener
): Unit
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
open fun canBeSpatialized(
attributes: AudioAttributes,
format: AudioFormat
): Boolean
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 . |
Return | |
---|---|
Boolean |
true if the device is capable of spatializing the combination of audio format and attributes, false otherwise. |
getImmersiveAudioLevel
open fun getImmersiveAudioLevel(): Int
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.
Return | |
---|---|
Int |
the level of spatialization support Value is android.media.Spatializer#SPATIALIZER_IMMERSIVE_LEVEL_OTHER , android.media.Spatializer#SPATIALIZER_IMMERSIVE_LEVEL_NONE , or android.media.Spatializer#SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL |
See Also
isAvailable
open fun isAvailable(): Boolean
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.
Return | |
---|---|
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
open fun isEnabled(): Boolean
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()
.
Return | |
---|---|
Boolean |
true if spatialization is enabled |
See Also
isHeadTrackerAvailable
open fun isHeadTrackerAvailable(): Boolean
Returns whether a head tracker is currently available for the audio device used by the spatializer effect.
Return | |
---|---|
Boolean |
true if a head tracker is available and the effect is enabled, false otherwise. |
removeOnHeadTrackerAvailableListener
open fun removeOnHeadTrackerAvailableListener(listener: Spatializer.OnHeadTrackerAvailableListener): Unit
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
open fun removeOnSpatializerStateChangedListener(listener: Spatializer.OnSpatializerStateChangedListener): Unit
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