struct · iOS 18.0+ · SDK 27.1
struct SpatialAudioComponentA component that configures how sounds emit from an entity into a person's environment. The audio system continuously updates the position and orientation of spatial audio sources automatically, so sounds come from an entity wherever it goes and wherever it points. Spatial audio sources incorporate a person's environment acoustics so that they blend in naturally with the surrounding area. The system distance-attenuates the spatial audio sources so they become quieter the farther away they are from the person. - Note: Spatial audio sources emit only a single channel (that is, mono). The engine mixes any stereo or multichannel audio resources down to a single channel before spatialization. To avoid any unwanted mixdown artifacts, use mono source material where possible. RealityKit audio playback is spatial by default, so no additional configuration is necessary to opt into sophisticated spatial rendering. ```swift let entity = Entity() let resource = try AudioFileResource.load(named: "MyAudioFile") entity.playAudio(resource) // Audio file is played spatially from entity ``` `SpatialAudioComponent` allows you to further customize the playback characteristics of spatial audio sources. The ``gain``, ``directLevel``, and ``reverbLevel`` properties are in relative decibels, in the range `[-Decibel.infinity, Decibel.zero]`, where `-Decibel.infinity` is silent and `Decibel.zero` is nominal. For example, you can adjust the overall level of all sounds the entity plays with the ``gain`` property. ```swift entity.spatialAudio = SpatialAudioComponent(gain: -10) ``` You can reduce the amount of reverb you apply to all sounds the entity plays with the ``reverbLevel`` property. Reduce this value to make the sounds less reverberant and more intimate. Set ``reverbLevel`` to `-Decibel.infinity` to cause the sounds to collapse into the head of the listener. ```swift entity.spatialAudio?.reverbLevel = -6 ``` You can update ``gain``, ``directLevel``, and ``reverbLevel`` properties dynamically. For example, you can update them when your app's state changes, or in the context of a custom RealityKit system. The ``directivity`` property allows you to configure the radiation pattern for sound that an entity emits. ```swift entity.spatialAudio?.directivity = .beam(focus: 0.5) ``` Spatial audio sources project sounds along their negative z-axis. If you colocate and co-orient a spatial audio source using visual content that you author with a positive z-forward coordinate convention, you need to rotate your spatial audio source 180º about the y-axis. ```swift let parent = Entity() // Add a model entity. let model = try ModelEntity.load(named: "PositiveZForward") parent.addChild(model) // Add an audio source entity. let audioSource = Entity() parent.addChild(audioSource) // Orient the audio source toward +Z. audioSource.orientation = .init(angle: .pi, axis: [0, 1, 0]) ``` This is only a consideration if you explicitly set a ``directivity`` other than the default `.beam(focus: .zero)`, which projects sound evenly for all frequencies in all directions. The ``distanceAttenuation`` property allows you to configure the way that a sound level decreases as the distance between the listener and the sound source increases. ```swift entity.spatialAudio?.distanceAttenuation = .rolloff(factor: 2) ```
get directLevel(): numbervar directLevel: Audio.Decibel { get set }The level of the direct unreverberated signal that an entity emits. The direct level is in relative decibels, in the range `[-Decibel.infinity, Decibel.zero]`, where `Decibel.zero` is the default.
set directLevel(value: number)var directLevel: Audio.Decibel { get set }The level of the direct unreverberated signal that an entity emits. The direct level is in relative decibels, in the range `[-Decibel.infinity, Decibel.zero]`, where `Decibel.zero` is the default.
get directivity(): Audio_Directivityvar directivity: Audio.DirectivityThe radiation pattern for sound that an entity emits. - Note: You can't update the `directivity` property dynamically. Set it before you prepare or play an audio resource on an entity.
set directivity(value: Audio_Directivity)var directivity: Audio.DirectivityThe radiation pattern for sound that an entity emits. - Note: You can't update the `directivity` property dynamically. Set it before you prepare or play an audio resource on an entity.
get reverbLevel(): numbervar reverbLevel: Audio.Decibel { get set }The level of reverberated signal that an entity emits. The reverb level is in relative decibels, in the range `[-Decibel.infinity, Decibel.zero]`, where `Decibel.zero` is the default. Reduce this value to make the sounds less reverberant and more intimate. Reduce this value to `-Decibel.infinity` to cause the sounds to collapse into the head of the listener.
set reverbLevel(value: number)var reverbLevel: Audio.Decibel { get set }The level of reverberated signal that an entity emits. The reverb level is in relative decibels, in the range `[-Decibel.infinity, Decibel.zero]`, where `Decibel.zero` is the default. Reduce this value to make the sounds less reverberant and more intimate. Reduce this value to `-Decibel.infinity` to cause the sounds to collapse into the head of the listener.
get distanceAttenuation(): Audio_DistanceAttenuationvar distanceAttenuation: Audio.DistanceAttenuation { get set }A value that specifies the way that the sound level decreases as the distance between the listener and the sound source increases. - Note: You can't update the `distanceAttenuation` property dynamically. Set it before you prepare or play an audio resource on an entity.
set distanceAttenuation(value: Audio_DistanceAttenuation)var distanceAttenuation: Audio.DistanceAttenuation { get set }A value that specifies the way that the sound level decreases as the distance between the listener and the sound source increases. - Note: You can't update the `distanceAttenuation` property dynamically. Set it before you prepare or play an audio resource on an entity.
static initGainDirectLevelReverbLevelDirectivityDistanceAttenuation(gain: number, directLevel: number, reverbLevel: number, directivity: Audio_Directivity, distanceAttenuation: Audio_DistanceAttenuation): SpatialAudioComponentinit(gain: Audio.Decibel = .zero, directLevel: Audio.Decibel = .zero, reverbLevel: Audio.Decibel = .zero, directivity: Audio.Directivity = .beam(focus: .zero), distanceAttenuation: Audio.DistanceAttenuation)Creates a spatial audio component from a gain value, a direct level, a reverb level, a directivity value, and a distance attenuation value. - Parameters: - gain: The overall level for all sounds that an entity emits. - directLevel: The level of the direct unreverberated signal that an entity emits. - reverbLevel: The level of reverberated signal that an entity emits. - directivity: The radiation pattern for sound that an entity emits. - distanceAttenuation: The way that a sound level reduces as a listener moves away from the source.
static initGainDirectLevelReverbLevelDirectivity(gain?: number, directLevel?: number, reverbLevel?: number, directivity?: Audio_Directivity): SpatialAudioComponentinit(gain: Audio.Decibel = .zero, directLevel: Audio.Decibel = .zero, reverbLevel: Audio.Decibel = .zero, directivity: Audio.Directivity = .beam(focus: .zero))Creates a spatial audio component from a gain value, a direct level, a reverb level, and a directivity value. - Parameters: - gain: The overall level for all sounds that an entity emits. - directLevel: The level of the direct unreverberated signal that an entity emits. - reverbLevel: The level of reverberated signal that an entity emits. - directivity: The radiation pattern for sound that an entity emits.
get gain(): numbervar gain: Audio.Decibel { get set }The overall level for all sounds that an entity emits. The gain level is in relative decibels, in the range `[-Decibel.infinity, Decibel.zero]`, where `Decibel.zero` is the default.
set gain(value: number)var gain: Audio.Decibel { get set }The overall level for all sounds that an entity emits. The gain level is in relative decibels, in the range `[-Decibel.infinity, Decibel.zero]`, where `Decibel.zero` is the default.
No declarations were skipped in this snapshot.