class · iOS 27.0+ · SDK 27.1
@MainActor @preconcurrency class AudioPlaybackGroupControllerA controller that manages synchronized playback for a group of audio resources. You obtain an audio playback group controller by calling ``Audio/prepareAudio(_:)`` or ``Audio/playAudio(_:)`` with multiple ``AudioResource``/``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 ``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`` on the scene. The event fires once when playback reaches the end of the group's audio stream.
get resourcesAndEntities(): Promise<Array<[AudioResource, Entity]>>@MainActor @preconcurrency final let resourcesAndEntities: [(AudioResource, Entity)]The resource and entity tuples that comprise the playback group
get id(): Promise<number>@MainActor @preconcurrency var id: UInt64 { get }The stable identity of the entity associated with this instance.
fade(newValue: number, duration: number): Promise<void>@MainActor @preconcurrency func fade(to newValue: Audio.Decibel, duration: TimeInterval)Transitions the gain to the given value over a time interval using a linear curve for all audio resources in the group. The target gain must be zero or negative, where zero is nominal loudness and negative infinity is silent. If the gain is positive, it will be reset to zero. - Parameter newValue: The target decibel level. - Parameter duration: How long in seconds the fade should last.
get gain(): Promise<number>@MainActor @preconcurrency var gain: Audio.Decibel { get set }The individual gain in decibels for all audio resources in the group. The gain must be zero or negative, where zero is nominal loudness and negative infinity is silent. If the gain is positive, it will be reset to zero. Use the ``AudioPlaybackGroupController/fade(to:duration:)`` method to change the gain gradually and create smooth transitions.
setGain(value: number): Promise<void>@MainActor @preconcurrency var gain: Audio.Decibel { get set }The individual gain in decibels for all audio resources in the group. The gain must be zero or negative, where zero is nominal loudness and negative infinity is silent. If the gain is positive, it will be reset to zero. Use the ``AudioPlaybackGroupController/fade(to:duration:)`` method to change the gain gradually and create smooth transitions.
playAt(time: _AVFAudio_AVAudioTime): Promise<void>@MainActor @preconcurrency func play(at time: AVAudioTime) throwsPlays all audio resources in the group asynchronously at a specified time. Use this method to schedule playback of the group to a precise time in the future. This method enables sample-accurate timing for the group and synchronization with other audio sources. Any call to ``AudioPlaybackGroupController/play()`` cancels a pending scheduled time and plays audio immediately. Any call to ``AudioPlaybackGroupController/play(at:)`` cancels a pending scheduled time and reschedules to the new time. The controller ignores calls to ``AudioPlaybackGroupController/play()`` when audio is already playing. Audio preparation must complete before the scheduled playback time to maintain precise timing. If preparation is still in progress when the scheduled time arrives, or if the scheduled time is in the past, playback starts immediately, which may result in timing drift. For accurate synchronization, schedule a time sufficiently far in the future. The ``AudioPlaybackGroupController/isPlaying`` property becomes `true` immediately after this call returns. Code that checks `isPlaying` to decide whether to trigger another action reads the correct state without racing against the scheduled start time. To synchronize this group with other audio sources, use the same base time for all scheduled playback calls. - Parameter time: The `AVAudioTime` at which the group should start playing. - Throws: An error if the controller fails to schedule playback.
play(): Promise<void>@MainActor @preconcurrency func play()Plays the audio resource. The controller plays from the beginning of the resource, or from the point at which it was paused if you previously called the ``AudioPlaybackGroupController/pause()`` method during playback. The controller ignores calls to ``AudioPlaybackGroupController/play()`` when audio is already playing.
seek(time: SDKHandle): Promise<void>@MainActor @preconcurrency func seek(to time: Duration)Sets the playback position to the specified time. - Parameter time: The desired playback position.
stop(): Promise<void>@MainActor @preconcurrency func stop()Stops playback of the audio resource and discards the location in the audio stream. The next time you call ``AudioPlaybackGroupController/play()``, playback starts at the beginning of the stream.
pause(): Promise<void>@MainActor @preconcurrency func pause()Pauses playback of the audio resource while maintaining the position in the audio stream. Resume playback of a paused audio resource by calling the ``AudioPlaybackGroupController/play()`` method.
get speed(): Promise<number>@MainActor @preconcurrency var speed: Double { get set }The rate of playback for all audio resources in the group, with a range of `[.25, 4]` Set the speed to `1` for a normal playback rate. All audio sources in the group will play at the same speed to maintain synchronization.
setSpeed(value: number): Promise<void>@MainActor @preconcurrency var speed: Double { get set }The rate of playback for all audio resources in the group, with a range of `[.25, 4]` Set the speed to `1` for a normal playback rate. All audio sources in the group will play at the same speed to maintain synchronization.
get isPlaying(): Promise<boolean>@MainActor @preconcurrency var isPlaying: Bool { get }A Boolean value that indicates whether playback is currently active. You may experience a small delay between when you call the ``AudioPlaybackGroupController/play()`` method and when the ``AudioPlaybackGroupController/isPlaying`` property reports `true`.
No declarations were skipped in this snapshot.