<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "macOS: 12.0.0 -",
    "tvOS: 17.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "PHASE",
  "identifier" : "/documentation/PHASE/PHASEAmbientMixerDefinition",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "PHASE"
    ],
    "preciseIdentifier" : "c:objc(cs)PHASEAmbientMixerDefinition"
  },
  "title" : "PHASEAmbientMixerDefinition"
}
-->

# PHASEAmbientMixerDefinition

An audio-layering object that outputs sound in a particular direction in 3D space.

```
class PHASEAmbientMixerDefinition
```

## Overview

As an audio-layering object, this class combines multiple audio signals to a single signal for the output device. Play audio with a 3D orientation using this class when you supply a quaternion for the `orientation` argument of the [`init(channelLayout:orientation:)`](/documentation/PHASE/PHASEAmbientMixerDefinition/init(channelLayout:orientation:)) initializer. For information on orientation the sound, see <doc://com.apple.documentation/documentation/Accelerate/working-with-quaternions>.

You also supply the intitializer with a channel layout in either mono, stereo, or surround formats. Surround audio files create the best listening experience due to their extra channel data. The framework renders each channel from the direction of its corresponding speaker in the channel layout. This class ignores low-frequency effect channels that may be present in the layout.

> Note:
> For one-time sounds that require no position or orientation, use ``doc://com.apple.phase/documentation/PHASE/PHASEChannelMixerDefinition`` instead of this class. If your audio playback needs to react to distance or contain environmental effects, use a spatial mixer; for more information, see <doc://com.apple.phase/documentation/PHASE/spatial-mixing>.

### Play Sound with a Specific Orientation, Channel Layout, and Listener

To play ambient sound, define an orientation for the mixer and a channel layout for the source audio data. For example, the following code creates a 5.0 surround-sound ambient source from a 5.1 surround-sound asset.

```swift
// Orient the mixer.
let orientation: PHASEQuaternion3D = simd_quaternion(1.0, 0.0, 0.0, 0.0)

// Create a channel layout corresponding to the sound asset’s channel layout.
let surroundLayout = AVAudioChannelLayout(
    layoutTag: kAudioChannelLayoutTag_MPEG_5_1_A)

// Create the ambient mixer.
let ambientMixer = PHASEAmbientMixerDefinition(channelLayout: surroundLayout!,
    orientation: orientation)
```

Ambient mixers require the app to specify a listener, for which you define an orientation by setting the listener’s [`transform`](/documentation/PHASE/PHASEObject/transform). Continuing on the example above, the following code completes a mixer by attaching a listener, and then plays a sound event.

```swift
// Attach the mixer to a listener.
let mixerParams = PHASEMixerParameters()
mixerParams.addAmbientMixerParameters(ambientMixer.uid, listener: listener)


// Create a sound event object.    
var ambientSoundEvent: PHASESoundEvent!
do { ambientSoundEvent = try PHASESoundEvent(engine: engine,
        registeredSoundEventNodeAssetUID: ambientSoundEventAsset.uid,
        mixerParameters: mixerParams)
} catch { fatalError("Failed to create a sound event.") }


// Play the ambient sound.
do { try ambientSoundEvent.start() } 
catch { print("Failed to start a sound event.") }
```

PHASE changes the channel output of ambient-mixer sound dynamically, depending on the respective directions of the mixer and the listener. For example, you can use an ambient mixer in a game to play the environmental sound of birds all around and the sound of traffic on a road in just one audio channel. Depending on the direction the player is facing, the mixer can rotate the audio so that the road always sounds like it’s coming from the same direction, for example, the west.

## Topics

### Creating an Ambient Mixer

[`-  initWithChannelLayout:orientation:`](/documentation/PHASE/PHASEAmbientMixerDefinition/init(channelLayout:orientation:))

Creates an ambient mixer with the given channel layout and orientation.

[`-  initWithChannelLayout:orientation:identifier:`](/documentation/PHASE/PHASEAmbientMixerDefinition/init(channelLayout:orientation:identifier:))

Creates a named ambient mixer with the given channel layout and orientation.

### Inspecting the Mixer

[`inputChannelLayout`](/documentation/PHASE/PHASEAmbientMixerDefinition/inputChannelLayout)

The channel layout of input audio.

[`orientation`](/documentation/PHASE/PHASEAmbientMixerDefinition/orientation)

A quaternion that describes the orientation of the speaker layout relative to the scene origin.

## Relationships

### Conforms To

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

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

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

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

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

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

### Inherits From

[`PHASEMixerDefinition`](/documentation/PHASE/PHASEMixerDefinition)

---

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)