SoundEffectPoolComponent

Artifact: androidx.xr.scenecore:scenecore

Kotlin |Java

class SoundEffectPoolComponent : Component, SoundEffectPlayer

kotlin.Any
↳	androidx.xr.scenecore.Component
	↳	androidx.xr.scenecore.SoundEffectPoolComponent

Provides positional sound pool audio playback for an Entity.

This component provides a method to play short sounds loaded by a SoundEffectPool. The audio is spatialized based on the Entity's transform and the provided PointSourceParams.

This component can only be attached to one Entity at a time. If the component is detached from an Entity, the audio will become head-locked until re-attached.

Summary

Public companion functions
`SoundEffectPoolComponent`	`create( session: Session, soundEffectPool: SoundEffectPool, params: PointSourceParams )` Creates a `SoundEffectPoolComponent`.

Public functions
`open Unit`	`pause(stream: Stream)` Pauses a currently playing sound stream.
`open Stream`	`play( soundEffect: SoundEffect, volume: @FloatRange(from = 0.0, to = 1.0) Float, priority: @IntRange(from = 0) Int, isLooping: Boolean )` Plays a loaded sound effect.
`open Unit`	`resume(stream: Stream)` Resumes a previously paused sound stream.
`open Unit`	`setLooping(stream: Stream, isLooping: Boolean)` Updates the looping status of an active stream.
`open Unit`	`setVolume(stream: Stream, volume: @FloatRange(from = 0.0, to = 1.0) Float)` Updates the volume of an active stream.
`open Unit`	`stop(stream: Stream)` Stops a currently playing or paused sound stream and releases that stream ID.

Protected functions
`open Boolean`	`onAttach(entity: Entity)` Called by the framework when this component is being added to an `Entity`.
`open Unit`	`onDetach(entity: Entity)` Called by the framework when this component is being removed from an `Entity`.

Public companion functions

create

Added in 1.0.0-alpha15

fun create(
    session: Session,
    soundEffectPool: SoundEffectPool,
    params: PointSourceParams
): SoundEffectPoolComponent

Creates a SoundEffectPoolComponent.

Parameters
`session: Session`	the active XR session
`soundEffectPool: SoundEffectPool`	pool that manages the loaded sound assets
`params: PointSourceParams`	initial spatial audio parameters for this source

Returns
`SoundEffectPoolComponent`	new instance of `SoundEffectPoolComponent`

Public functions

pause

open fun pause(stream: Stream): Unit

Pauses a currently playing sound stream.

If the stream has already been stopped or released due to hitting the max stream count then this method has no effect.

Parameters
`stream: Stream`	a `Stream` returned by `play`

play

open fun play(
    soundEffect: SoundEffect,
    volume: @FloatRange(from = 0.0, to = 1.0) Float,
    priority: @IntRange(from = 0) Int,
    isLooping: Boolean
): Stream

Plays a loaded sound effect.

The SoundEffects can play concurrently up to the max stream count of the SoundEffectPool from which they were loaded. If the max stream count is exceeded, streams with lower priority are stopped first.

Parameters
`soundEffect: SoundEffect`	the handle to the loaded `SoundEffect` to play
`volume: @FloatRange(from = 0.0, to = 1.0) Float`	volume in the range 0.0 to 1.0
`priority: @IntRange(from = 0) Int`	playback priority (0 = lowest)
`isLooping: Boolean`	true to loop indefinitely, false to play once

Returns
`Stream`	a `Stream` for controlling this specific instance of the sound

Throws
`RuntimeException`	if the sound effect fails to play

resume

open fun resume(stream: Stream): Unit

Resumes a previously paused sound stream.

If the stream has already been stopped or released due to hitting the max stream count then this method has no effect.

Parameters
`stream: Stream`	a `Stream` returned by `play`

setLooping

open fun setLooping(stream: Stream, isLooping: Boolean): Unit

Updates the looping status of an active stream.

If the stream has already been stopped or released due to hitting the max stream count then this method has no effect.

Parameters
`stream: Stream`	a `Stream` returned by `play`
`isLooping: Boolean`	true to loop indefinitely, false to stop looping

setVolume

open fun setVolume(stream: Stream, volume: @FloatRange(from = 0.0, to = 1.0) Float): Unit

Updates the volume of an active stream.

If the stream has already been stopped or released due to hitting the max stream count then this method has no effect.

Parameters
`stream: Stream`	a `Stream` returned by `play`
`volume: @FloatRange(from = 0.0, to = 1.0) Float`	volume in the range 0.0 to 1.0

stop

open fun stop(stream: Stream): Unit

Stops a currently playing or paused sound stream and releases that stream ID.

If the stream has already been stopped or released due to hitting the max stream count then this method has no effect.

Parameters
`stream: Stream`	a `Stream` returned by `play`

Protected functions

onAttach

protected open fun onAttach(entity: Entity): Boolean

Called by the framework when this component is being added to an Entity.

This method is triggered when Entity.addComponent is invoked. Implementations should override this method to perform setup logic or to validate if the component is compatible with the provided entity.

Parameters
`entity: Entity`	The `Entity` to which this component is being attached.

Returns
`Boolean`	`true` if the component was successfully attached; `false` if the `entity` does not support this component or if attachment failed.

onDetach

protected open fun onDetach(entity: Entity): Unit

Called by the framework when this component is being removed from an Entity.

This method is triggered when Entity.removeComponent is invoked. Implementations should override this method to release resources or undo any changes made during onAttach.

Parameters
`entity: Entity`	The `Entity` from which this component is being detached.