<!--
{
  "availability" : [
    "iOS: 18.0.0 -",
    "iPadOS: 18.0.0 -",
    "macCatalyst: 18.0.0 -",
    "macOS: 15.0.0 -",
    "tvOS: 26.0.0 -",
    "visionOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/PlayAudioAction",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation15PlayAudioActionV"
  },
  "title" : "PlayAudioAction"
}
-->

# PlayAudioAction

An action which plays an audio resource on the given target entity.

```
struct PlayAudioAction
```

## Overview

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`](/documentation/RealityKit/AudioResource) from the [`AudioLibraryComponent`](/documentation/RealityKit/AudioLibraryComponent) on the
[`targetEntity`](/documentation/RealityKit/PlayAudioAction/targetEntity). Add all audio resources to the audio library
component that this action will play, ensuring the name of the audio matches the [`audioResourceName`](/documentation/RealityKit/PlayAudioAction/audioResourceName)
being supplied.

[`useControlledPlayback`](/documentation/RealityKit/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 [`pause()`](/documentation/RealityKit/AnimationPlaybackController/pause()) and
[`resume()`](/documentation/RealityKit/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 ``doc://com.apple.RealityKit/documentation/RealityKit/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 ``doc://com.apple.RealityKit/documentation/RealityKit/BindTarget/transform``.

## Topics

### Initializers

[`init(targetEntity: ActionEntityResolution, audioResourceName: String, gain: Audio.Decibel, useControlledPlayback: Bool)`](/documentation/RealityKit/PlayAudioAction/init(targetEntity:audioResourceName:gain:useControlledPlayback:))

Creates a new play audio action.

### Instance Properties

[`var animatedValueType: (any AnimatableData.Type)?`](/documentation/RealityKit/PlayAudioAction/animatedValueType)

The type for the value that the action modifies over time.

[`var audioResourceName: String`](/documentation/RealityKit/PlayAudioAction/audioResourceName)

The name of the audio stored in audio library component of the target entity to start playing.

[`var gain: Audio.Decibel`](/documentation/RealityKit/PlayAudioAction/gain)

The individual gain in decibels of the audio.

[`var targetEntity: ActionEntityResolution`](/documentation/RealityKit/PlayAudioAction/targetEntity)

The entity to play the audio.

[`var useControlledPlayback: Bool`](/documentation/RealityKit/PlayAudioAction/useControlledPlayback)

A Boolean that indicates whether this action has control over the playback of the audio.

## Relationships

### Conforms To

[`EntityAction`](/documentation/RealityKit/EntityAction)

[`Decodable`](/documentation/Swift/Decodable)

[`Encodable`](/documentation/Swift/Encodable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)