An action which plays an audio resource on the given target entity.
Use this action to initiate the playback of audio in a data-driven way.
For example, this action can play an animation group which contains a nested action,
which plays audio with specific playback properties.
This action plays the ``AudioResource`` from the ``AudioLibraryComponent`` on the
``PlayAudioAction/targetEntity``. Add all audio resources to the audio library
component that this action will play, ensuring the name of the audio matches the ``PlayAudioAction/audioResourceName``
being supplied.
``PlayAudioAction/useControlledPlayback`` is used to determine the playback behavior of
the audio this action is playing. Set this to `true` to control the playback of the audio.
Calling methods such as ``AnimationPlaybackController/pause()`` and
``AnimationPlaybackController/resume()`` on the animation playback controller
generated from this action will give you control of the audio being played. When the action ends,
the audio playback also ends.
Set this to `false` to ensure the audio being played runs independently of the action. This would behave
as a one shot audio.
The example below creates an animation which will play an audio resource after five seconds.
```swift
// Create an action which plays a specified audio resource.
//
// The audio resource exists within the target entity's
// animation library component.
//
// Control playback is set to false, audio will
// play independently of the animation.
let snapAudioAction = PlayAudioAction(audioResourceName: "snap",
useControlledPlayback: false)
// Creates an animation from the action, with a five second delay.
let snapAudioAnimation = try AnimationResource
.makeActionAnimation(for: snapAudioAction,
delay: 5.0)
// Play the animation which will play the audio after five seconds.
entity.playAnimation(snapAudioAnimation)
```
- Note: If ``PlayAudioAction/useControlledPlayback`` is set to `true`, the animation will play
for the duration of the action. Set the duration of the action to match the length of the audio being played
to ensure the entire audio plays.
- Important: This action does not directly animate a bound property, such as ``BindTarget/transform``.
Creates a new play audio action.
- Parameters:
- targetEntity: The entity to play the audio.
- audioResourceName: The name of the audio stored in audio library component of the target entity to start playing.
- gain: The individual gain in decibels of the audio.
- useControlledPlayback: Determines whether this action has control over the playback of the audio.
get · iOS 18.0+
targetEntity
TypeScript
get targetEntity(): ActionEntityResolution
Swift declaration
var targetEntity: ActionEntityResolution
The entity to play the audio.
set · iOS 18.0+
targetEntity
TypeScript
set targetEntity(value: ActionEntityResolution)
Swift declaration
var targetEntity: ActionEntityResolution
The entity to play the audio.
get · iOS 18.0+
audioResourceName
TypeScript
get audioResourceName(): string
Swift declaration
var audioResourceName: String
The name of the audio stored in audio library component of the target entity to start playing.
set · iOS 18.0+
audioResourceName
TypeScript
set audioResourceName(value: string)
Swift declaration
var audioResourceName: String
The name of the audio stored in audio library component of the target entity to start playing.
get · iOS 18.0+
useControlledPlayback
TypeScript
get useControlledPlayback(): boolean
Swift declaration
var useControlledPlayback: Bool
A Boolean that indicates whether this action has control over the playback of the audio.
Setting the value of this property to true indicates the action has control over the playback of the audio.
Setting this to false indicates the audio plays independently from the action, behaving like a one shot audio.
set · iOS 18.0+
useControlledPlayback
TypeScript
set useControlledPlayback(value: boolean)
Swift declaration
var useControlledPlayback: Bool
A Boolean that indicates whether this action has control over the playback of the audio.
Setting the value of this property to true indicates the action has control over the playback of the audio.
Setting this to false indicates the audio plays independently from the action, behaving like a one shot audio.
get · iOS 18.0+
gain
TypeScript
get gain(): number
Swift declaration
var gain: Audio.Decibel
The individual gain in decibels of the audio.
set · iOS 18.0+
gain
TypeScript
set gain(value: number)
Swift declaration
var gain: Audio.Decibel
The individual gain in decibels of the audio.
Skipped declarations
1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
