<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/AudioPlaybackGroupController",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation28AudioPlaybackGroupControllerC"
  },
  "title" : "AudioPlaybackGroupController"
}
-->

# AudioPlaybackGroupController

A controller that manages synchronized playback for a group of audio resources.

```
@MainActor @preconcurrency class AudioPlaybackGroupController
```

## Overview

You obtain an audio playback group controller by calling [`prepareAudio(_:)`](/documentation/RealityKit/Audio/prepareAudio(_:))
or [`playAudio(_:)`](/documentation/RealityKit/Audio/playAudio(_:)) with multiple [`AudioResource`](/documentation/RealityKit/AudioResource)/[`Entity`](/documentation/RealityKit/Entity) pairs. The
controller coordinates all sources so they remain
synchronized through playback, pause, seek, and rate changes.

Each source plays from its associated entity, so RealityKit applies that entity’s
spatial audio characteristics independently. The same entity may appear multiple
times with different resources, and a single entity can participate in multiple
groups simultaneously.

```swift
// Load multiple audio resources.
let drums = try AudioFileResource.load(named: "Drums")
let bass  = try AudioFileResource.load(named: "Bass")
let lead  = try AudioFileResource.load(named: "Lead")

// Pair each resource with the entity that should emit it.
let pairs: [(AudioResource, Entity)] = [
    (drums, drumsEntity),
    (bass,  bassEntity),
    (lead,  leadEntity),
]

// Prepare and start synchronized playback.
let controller = try Audio.playAudio(pairs)

// Adjust the whole group together.
controller.fade(to: -6, duration: 0.5)
```

> Note: Playback commences only after the entities are parented and placed within a scene.

Use [`play(at:)`](/documentation/RealityKit/AudioPlaybackGroupController/play(at:)) to schedule a synchronized start at a
future `AVAudioTime`, which is useful for aligning a group with other audio sources
or external clocks.

To be notified when the group finishes playing, subscribe to
[`AudioEvents.PlaybackGroupCompleted`](/documentation/RealityKit/AudioEvents/PlaybackGroupCompleted) on the scene. The event fires once when
playback reaches the end of the group’s audio stream.

## Topics

### Controlling playback

[`func play(at: AVAudioTime) throws`](/documentation/RealityKit/AudioPlaybackGroupController/play(at:))

Plays all audio resources in the group asynchronously at a specified time.

[`func seek(to: Duration)`](/documentation/RealityKit/AudioPlaybackGroupController/seek(to:))

Sets the playback position to the specified time.

### Accessing playback state

[`let resourcesAndEntities: [(AudioResource, Entity)]`](/documentation/RealityKit/AudioPlaybackGroupController/resourcesAndEntities)

The resource and entity tuples that comprise the playback group

### Instance Properties

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

The individual gain in decibels for all audio resources in the group.

[`var isPlaying: Bool`](/documentation/RealityKit/AudioPlaybackGroupController/isPlaying)

A Boolean value that indicates whether playback is currently active.

[`var speed: Double`](/documentation/RealityKit/AudioPlaybackGroupController/speed)

The rate of playback for all audio resources in the group, with a range of `[.25, 4]`

### Instance Methods

[`func fade(to: Audio.Decibel, duration: TimeInterval)`](/documentation/RealityKit/AudioPlaybackGroupController/fade(to:duration:))

Transitions the gain to the given value over a time interval using a
linear curve for all audio resources in the group.

[`func pause()`](/documentation/RealityKit/AudioPlaybackGroupController/pause())

Pauses playback of the audio resource while maintaining the position in
the audio stream.

[`func play()`](/documentation/RealityKit/AudioPlaybackGroupController/play())

Plays the audio resource.

[`func stop()`](/documentation/RealityKit/AudioPlaybackGroupController/stop())

Stops playback of the audio resource and discards the location in the
audio stream.

## Relationships

### Conforms To

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

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

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

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

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

---

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)