One Logo Pool Ball
X
Github
Discord

System

RealityFoundation · IOS API REFERENCE

AudioPlaybackController

class · iOS 13.0+ · SDK 27.1

@MainActor @preconcurrency class AudioPlaybackController

A controller that manages an audio playback instance. You can obtain an audio playback controller by calling an entity’s Entity/prepareAudio(_:) or Entity/playAudio(_:) method which creates a controller with the associated ``AudioResource``. To play multiple instances of a resource, call ``Entity/playAudio(_:)`` to obtain new AudioPlaybackControllers. During playback, the audio appears to come from the entity that you used to create the controller. As you move around the MR scene, RealityKit modulates the characteristics of the audio to account for your location. - Note: Playback commences only after the entity is parented and placed within a scene. After playback completes, or if you call the ``AudioPlaybackController/stop()`` method, the audio resource resets, allowing you to replay the resource from the beginning. Alternatively, you can enable indefinite looping by setting the `loops` property of the audio resource to `true`. Look for one of the events in ``AudioEvents`` if you want to be alerted when certain aspects of audio playback occur.

Members (18)

get · iOS 13.0+ · Deprecated in iOS 18.0

reverbSendLevel

TypeScript
get reverbSendLevel(): Promise<number>
Swift declaration
@MainActor @preconcurrency var reverbSendLevel: AudioPlaybackController.Decibel { get set }

The send level from this playback controller to the reverb system.

set · iOS 13.0+ · Deprecated in iOS 18.0

reverbSendLevel

TypeScript
setReverbSendLevel(value: number): Promise<void>
Swift declaration
@MainActor @preconcurrency var reverbSendLevel: AudioPlaybackController.Decibel { get set }

The send level from this playback controller to the reverb system.

get · iOS 13.0+

completionHandler

TypeScript
get completionHandler(): Promise<((() => Promise<void>)) | null>
Swift declaration
@MainActor @preconcurrency var completionHandler: (() -> Void)? { get set }

A closure that the playback controller executes when it reaches the end of the audio stream. The controller doesn’t call the closure if you manually stop the audio by calling the ``AudioPlaybackController/stop()`` or the ``AudioPlaybackController/pause()`` method. - Note: You can only register one handler at a time. If you set a new handler, the controller discards the old one.

set · iOS 13.0+

completionHandler

TypeScript
setCompletionHandler(value?: ((() => void)) | null): Promise<void>
Swift declaration
@MainActor @preconcurrency var completionHandler: (() -> Void)? { get set }

A closure that the playback controller executes when it reaches the end of the audio stream. The controller doesn’t call the closure if you manually stop the audio by calling the ``AudioPlaybackController/stop()`` or the ``AudioPlaybackController/pause()`` method. - Note: You can only register one handler at a time. If you set a new handler, the controller discards the old one.

get · iOS 13.0+

id

TypeScript
get id(): Promise<number>
Swift declaration
@MainActor @preconcurrency var id: UInt64 { get }

The stable identity of the entity associated with this instance.

method · iOS 13.0+

fade

TypeScript
fade(newValue: number, duration: number): Promise<void>
Swift declaration
@MainActor @preconcurrency func fade(to newValue: AudioPlaybackController.Decibel, duration: TimeInterval)

Transitions the gain to the given value over a time interval using a linear curve. 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 · iOS 13.0+

gain

TypeScript
get gain(): Promise<number>
Swift declaration
@MainActor @preconcurrency var gain: AudioPlaybackController.Decibel { get set }

The individual gain in decibels of the audio playback controller output. 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 ``AudioPlaybackController/fade(to:duration:)`` method to change the gain gradually and create smooth transitions.

set · iOS 13.0+

gain

TypeScript
setGain(value: number): Promise<void>
Swift declaration
@MainActor @preconcurrency var gain: AudioPlaybackController.Decibel { get set }

The individual gain in decibels of the audio playback controller output. 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 ``AudioPlaybackController/fade(to:duration:)`` method to change the gain gradually and create smooth transitions.

method · iOS 27.0+

play

TypeScript
playAt(time: _AVFAudio_AVAudioTime): Promise<void>
Swift declaration
@MainActor @preconcurrency func play(at time: AVAudioTime) throws

Plays the audio resource asynchronously at a specified time. Use this method to schedule playback of a sound source to a precise time in the future. This method enables sample-accurate timing for individual sounds and synchronization of multiple audio sources. Any call to ``AudioPlaybackController/play()`` cancels a pending scheduled time and plays audio immediately. Any call to ``AudioPlaybackController/play(at:)`` cancels a pending scheduled time and reschedules to the new time. The controller ignores calls to ``AudioPlaybackController/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 ``AudioPlaybackController/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 multiple sounds, use the same base time for all scheduled playback calls. - Parameter time: The `AVAudioTime` at which the audio resource should start playing. - Throws: An error if the controller fails to schedule playback.

method · iOS 13.0+

play

TypeScript
play(): Promise<void>
Swift declaration
@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 ``AudioPlaybackController/pause()`` method during playback. The controller ignores calls to ``AudioPlaybackController/play()`` when audio is already playing.

method · iOS 18.0+

seek

TypeScript
seek(time: SDKHandle): Promise<void>
Swift declaration
@MainActor @preconcurrency func seek(to time: Duration)

Sets the playback position to the specified time. - Parameter time: The desired playback position.

method · iOS 13.0+

stop

TypeScript
stop(): Promise<void>
Swift declaration
@MainActor @preconcurrency func stop()

Stops playback of the audio resource and discards the location in the audio stream. The next time you call ``AudioPlaybackController/play()``, playback starts at the beginning of the stream.

method · iOS 13.0+

pause

TypeScript
pause(): Promise<void>
Swift declaration
@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 ``AudioPlaybackController/play()`` method.

get · iOS 13.0+

speed

TypeScript
get speed(): Promise<number>
Swift declaration
@MainActor @preconcurrency var speed: Double { get set }

The rate of playback of the audio resource, with a range of `[.25, 4]` Set the speed to `1` for a normal playback rate.

set · iOS 13.0+

speed

TypeScript
setSpeed(value: number): Promise<void>
Swift declaration
@MainActor @preconcurrency var speed: Double { get set }

The rate of playback of the audio resource, with a range of `[.25, 4]` Set the speed to `1` for a normal playback rate.

get · iOS 13.0+

entity

TypeScript
get entity(): Promise<(Entity) | null>
Swift declaration
@MainActor @preconcurrency weak var entity: Entity? { get }

The entity from which the audio stream emanates.

get · iOS 13.0+

resource

TypeScript
get resource(): Promise<AudioResource>
Swift declaration
@MainActor @preconcurrency final let resource: AudioResource

The resource that provides the audio stream.

get · iOS 13.0+

isPlaying

TypeScript
get isPlaying(): Promise<boolean>
Swift declaration
@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 ``AudioPlaybackController/play()`` method and when the ``AudioPlaybackController/isPlaying`` property reports `true`.

Skipped declarations

No declarations were skipped in this snapshot.

All RealityFoundation types →