<!--
{
  "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/PHASESoundEvent",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "PHASE"
    ],
    "preciseIdentifier" : "c:objc(cs)PHASESoundEvent"
  },
  "title" : "PHASESoundEvent"
}
-->

# PHASESoundEvent

An object that determines which audio to play.

```
class PHASESoundEvent
```

## Overview

A sound event represents a logic tree, or hierarchy, that defines what, when, and how the framework plays a sound at runtime. You configure the tree with conditions based on your app’s state. When you invoke a sound event’s root node at runtime, the framework navigates the tree by branching based on the logic, landing on a playable node that sends the right audio to the output device:

- To invoke a specific one-time sound, create a sound event from a single sampler node.
- To invoke a sound event that tailors its sound based on your app’s state, define a sound event hierarchy containing one or more control nodes; see [Sound Event Nodes](/documentation/PHASE/sound-event-nodes). For example, to play either footsteps or a jumping noise depending on the hero’s state, you configure a switch node that navigates based on the hero’s hypothetical `isJumping` metaparameter.

For sound event nodes that play audio, the asset’s [`playbackMode`](/documentation/PHASE/PHASESamplerNodeDefinition/playbackMode) determines whether the audio loops. One-time sound events stop automatically at the end of the audio data. Looping sound events (those with [`playbackMode`](/documentation/PHASE/PHASESamplerNodeDefinition/playbackMode) `=` [`PHASEPlaybackMode.looping`](/documentation/PHASE/PHASEPlaybackMode/looping)) require you to explicitly call [`stopAndInvalidate()`](/documentation/PHASE/PHASESoundEvent/stopAndInvalidate()) to stop the audio.

### Playing a one-shot channel-based sound

Apps create a sound event by requesting one from a sound event node asset. To create a sound event node asset, combine a sound asset (the source audio data) with a mixer object (which combines sound layers for output) to create a node, and add the node to the asset registry. By creating a sound event from a sampler node ([`PHASESamplerNodeDefinition`](/documentation/PHASE/PHASESamplerNodeDefinition)), the following code plays an audio file once before discarding it.

```swift
// Create a channel layout for audio types that contain no channel metadata. 
let stereoLayout = AVAudioChannelLayout(layoutTag: kAudioChannelLayoutTag_Stereo)    

// Load an audio file from the bundle.
let bangSoundURL = Bundle.main.url(forResource: "bangSound", withExtension: "wav")!

// Create and register a sound asset.
var bangSoundAsset:PHASESoundAsset!
do { 
    bangSoundAsset = try engine.assetRegistry.registerSoundAsset(
        url: bangSoundURL, 
        identifier: "bangSound", 
        assetType: .resident, 
        channelLayout: stereoLayout,
        normalizationMode: .dynamic)
} catch { print("Failed to register the sound asset.") }

// Create a mixer that routes sound directly to the output.
let stereoMixer = PHASEChannelMixerDefinition(channelLayout:stereoLayout!)

// Create a sound event node.
let bangSoundSamplerNode = PHASESamplerNodeDefinition(
    soundAssetIdentifier: bangSoundAsset.identifier, 
    mixerDefinition: stereoMixer, identifier:"bangSoundNode")

// Add the sound event node to the asset registry and retrieve the asset object.
var bangSoundSoundEventAsset: PHASESoundEventNodeAsset! 
do {
    bangSoundEventAsset = try engine.assetRegistry.registerSoundEventAsset(
        rootNode: bangSoundSamplerNode, identifier:"bangSoundTree")
} catch { print ("Failed to register the sound event node.") }
```

The resulting node asset represents a template for audio that’s ready for playback. To play the audio, spawn a sound event off of the node asset and call [`start(completion:)`](/documentation/PHASE/PHASESoundEvent/start(completion:)) to invoke the sound event.

```swift
// Create a playable sound event from the template sound event asset.
var bangSoundEvent: PHASESoundEvent!
do {
        bangSoundEvent = try PHASESoundEvent(engine:engine, 
        assetIdentifier: bangSoundEventAsset.identifier)
} catch { print ("Failed to create the sound event.") }

// Play the one-shot sound event.
bangSoundEvent.start()
```

> Important:
> To play the same sound asset again, create another sound event object. After the first ``doc://com.apple.phase/documentation/PHASE/PHASESoundEvent/start(completion:)`` call on a particular `PHASESoundEvent` instance, subsequent calls have no effect.

## Topics

### Creating a Sound Event

[`init(engine:assetIdentifier:)`](/documentation/PHASE/PHASESoundEvent/init(engine:assetIdentifier:))

Creates a sound event node with the given asset.

[`init(engine:assetIdentifier:mixerParameters:)`](/documentation/PHASE/PHASESoundEvent/init(engine:assetIdentifier:mixerParameters:))

Creates a sound event node with the given asset and mixer parameters.

### Configuring Mixers and Metaparameters

[`mixers`](/documentation/PHASE/PHASESoundEvent/mixers)

Nodes in the event tree that control the volume of their child nodes.

[`metaParameters`](/documentation/PHASE/PHASESoundEvent/metaParameters)

The object’s meta parameters.

### Preparing Playback

[`prepare(completion:)`](/documentation/PHASE/PHASESoundEvent/prepare(completion:))

Enables a sound event to play and runs the argument code when the sound event plays back.

[`PHASESoundEvent.PrepareHandlerReason`](/documentation/PHASE/PHASESoundEvent/PrepareHandlerReason)

Indicates the results of sound-event preparation.

[`prepareState`](/documentation/PHASE/PHASESoundEvent/prepareState-swift.property)

The status of sound-event preparation.

[`PHASESoundEvent.PrepareState`](/documentation/PHASE/PHASESoundEvent/PrepareState-swift.enum)

Indicates the state of sound-event preparation.

### Checking Playback Status

[`renderingState`](/documentation/PHASE/PHASESoundEvent/renderingState-swift.property)

The sound event’s playback status.

[`PHASESoundEvent.RenderingState`](/documentation/PHASE/PHASESoundEvent/RenderingState-swift.enum)

The playback status of audio.

### Providing Buffered Data

[`pushStreamNodes`](/documentation/PHASE/PHASESoundEvent/pushStreamNodes)

A collection of audio streams for playback.

### Starting Playback

[`start(completion:)`](/documentation/PHASE/PHASESoundEvent/start(completion:))

Invokes the sound event and runs the specified code on completion.

[`PHASESoundEvent.StartHandlerReason`](/documentation/PHASE/PHASESoundEvent/StartHandlerReason)

Indicates the status after starting a sound event.

### Seeking a Time

[`seek(to:completion:)`](/documentation/PHASE/PHASESoundEvent/seek(to:completion:))

Advances the sound event’s playback position to a specific time.

[`PHASESoundEvent.SeekHandlerReason`](/documentation/PHASE/PHASESoundEvent/SeekHandlerReason)

Indicates the status after a sound event changes its playback position.

### Pausing Playback

[`pause()`](/documentation/PHASE/PHASESoundEvent/pause())

Pauses the sound event.

[`resume()`](/documentation/PHASE/PHASESoundEvent/resume())

Resumes the sound event.

### Stopping Playback

[`stopAndInvalidate()`](/documentation/PHASE/PHASESoundEvent/stopAndInvalidate())

Stops a sound event and prevents it from resuming.

[`isIndefinite`](/documentation/PHASE/PHASESoundEvent/isIndefinite)

A Boolean value that indicates whether the sound loops or stops on its own.


---

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)