SpatialAudioTrackExtension
Provides spatial audio extensions for Android AudioTrack.
This extension enables third-party players (e.g., video players) to leverage spatial audio rendering capabilities while continuing to use standard Android AudioTrack APIs.
API Structure
SpatialAudioTrackExtension
├── attachToEntity (Bind spatial audio to an Entity's position)
│ ├── withBuilder (Configure and bind before AudioTrack creation)
│ └── withAudioTrack (Bind after AudioTrack creation)
└── attachToContainer (Bind spatial audio at container/window level)
├── withBuilder (Configure and bind before AudioTrack creation)
└── withAudioTrack (Bind after AudioTrack creation)Choosing the Right Method
withBuilder vs withAudioTrack:
Use
withBuildermethods when you have access to the AudioTrack.Builder before callingbuild(). This is the typical case when you control the AudioTrack creation pipeline.Use
withAudioTrackmethods when the AudioTrack is already created by an external framework (e.g., ExoPlayer, MediaPlayer) and handed to you after instantiation.
Entity vs Container:
Use
attachToEntitywhen the audio should follow a specific 3D object's position in the scene (e.g., a video panel entity).Use
attachToContainerwhen the audio only needs to follow the window/container position (e.g., fixed background music).
Usage Examples
Entity + Builder (recommended for custom players)
val extension = SpatialAudioTrackExtension()
extension.spatialAudioTrackExtensionConfig(
mode = SpatialAudioMode.OBJECT,
isAmbisonic = false,
builder = audioTrackBuilder
)
extension.attachToEntityWithBuilder(targetEntity, audioTrackBuilder)
val audioTrack = audioTrackBuilder.build()Entity + AudioTrack (for third-party frameworks)
val extension = SpatialAudioTrackExtension()
extension.spatialAudioTrackExtensionConfig(
mode = SpatialAudioMode.OBJECT,
isAmbisonic = false,
builder = audioTrackBuilder
)
val audioTrack = audioTrackBuilder.build() // created by framework
extension.attachToEntityWithAudioTrack(targetEntity, audioTrack)Container + Builder (window-level audio)
val extension = SpatialAudioTrackExtension()
extension.spatialAudioTrackExtensionConfig(
mode = SpatialAudioMode.AMBIENT,
isAmbisonic = false,
builder = audioTrackBuilder
)
extension.attachToContainerWithBuilder(context, audioTrackBuilder)
val audioTrack = audioTrackBuilder.build()Container + AudioTrack
val extension = SpatialAudioTrackExtension()
extension.spatialAudioTrackExtensionConfig(
mode = SpatialAudioMode.AMBIENT,
isAmbisonic = false,
builder = audioTrackBuilder
)
val audioTrack = audioTrackBuilder.build()
extension.attachToContainerWithAudioTrack(context, audioTrack)See also
for available spatialization modes.
Functions
Attaches spatial audio to a Container/Context using an already-created AudioTrack.
Attaches spatial audio to a Container/Context using a pre-configured AudioTrack.Builder.
Attaches spatial audio to an Entity using an already-created AudioTrack.
Attaches spatial audio to an Entity using a pre-configured AudioTrack.Builder.
Enables or disables spatial audio processing for the given AudioTrack.
Configures spatial audio parameters on the AudioTrack.Builder.