<!--
{
  "documentType" : "article",
  "framework" : "PHASE",
  "identifier" : "/documentation/PHASE/playback-parameterization",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Playback Parameterization"
}
-->

# Playback Parameterization

Change the characteristics of in-flight audio by adjusting its properties at runtime.

## Discussion

Metaparameters control several features of a sound source or sound event, as they play back. For instance, metaparameters can adjust a switch node’s toggle, or the amount of reverb that a sound source emanates.

### Attach Metaparameters to a Particular Sound

To use a metaparameter, you attach it to a sound event or sound source. PHASE provides the following ways to attach metaparameters:

- [`PHASEGeneratorNodeDefinition`](/documentation/PHASE/PHASEGeneratorNodeDefinition): [`gainMetaParameterDefinition`](/documentation/PHASE/PHASEGeneratorNodeDefinition/gainMetaParameterDefinition), [`rateMetaParameterDefinition`](/documentation/PHASE/PHASEGeneratorNodeDefinition/rateMetaParameterDefinition)
- [`PHASEMixerDefinition`](/documentation/PHASE/PHASEMixerDefinition): [`gainMetaParameterDefinition`](/documentation/PHASE/PHASEMixerDefinition/gainMetaParameterDefinition)
- [`PHASESwitchNodeDefinition`](/documentation/PHASE/PHASESwitchNodeDefinition): [`init(switchMetaParameterDefinition:)`](/documentation/PHASE/PHASESwitchNodeDefinition/init(switchMetaParameterDefinition:))
- [`PHASEBlendNodeDefinition`](/documentation/PHASE/PHASEBlendNodeDefinition): [`init(blendMetaParameterDefinition:)`](/documentation/PHASE/PHASEBlendNodeDefinition/init(blendMetaParameterDefinition:))
- [`PHASEMappedMetaParameterDefinition`](/documentation/PHASE/PHASEMappedMetaParameterDefinition): [`init(inputMetaParameterDefinition:envelope:identifier:)`](/documentation/PHASE/PHASEMappedMetaParameterDefinition/init(inputMetaParameterDefinition:envelope:identifier:))
- [`PHASESpatialPipelineEntry`](/documentation/PHASE/PHASESpatialPipelineEntry): [`sendLevelMetaParameterDefinition`](/documentation/PHASE/PHASESpatialPipelineEntry/sendLevelMetaParameterDefinition)

### Adjust a Property of a Single Audio Signal

The framework refers to metaparameters that you access through a sound event’s [`metaParameters`](/documentation/PHASE/PHASESoundEvent/metaParameters) dictionary as *local* metaparameters. When you adjust the value of a local metaparameter, it affects just the sound event.

The following code changes the volume on a specific sound event:

```swift
// Create a `PHASEMetaParameterDefinition` instance.
let myGainParam = PHASENumberMetaParameterDefinition(value: 1, identifier: "gain")

// Create a sampler node that plays an audio file named "mySound".
let mySampler = PHASESamplerNodeDefinition(
    soundAssetIdentifier: "mySound",
    mixerDefinition: myMixer)

// Attach the metaparameter to the sampler node.
mySampler.gainMetaParameterDefinition = myGainParam;

// Invoke the sound event.
mySoundEvent.start()

// Access the local metaparameter and change the gain.
if let metaparameter = mySoundEvent.metaParameters["gain"] {
    metaparameter.value = 0.5
}
```

### Share a Parameter with Multiple Audio Signals

The framework refers to parameters that affect many sound events or sound sources as *global* metaparameters. Real-time adjustments to global metaparameters affect the playback of all sound events that initialize with the metaparameter.

The following code changes a `weather` metaparameter for all of its associated sound events:

```swift
// Create a `PHASEMetaParameterDefinition` instance.
let myGlobalWeatherParam = PHASEStringMetaParameterDefinition(
    value: "sunny", identifier: "weather")

// Register it as a global metaparameter.
do {
    try myEngine.assetRegistry.registerGlobalMetaParameter(metaParameterDefinition: myGlobalWeatherParam)
} catch {
    fatalError("Unable to register the weather metaparameter.")
}

// Attach it to a sound event node definition.
let mySwitchNode = PHASESwitchNodeDefinition(switchMetaParameterDefinition: myGlobalWeatherParam)

// Change the its value at runtime.
if let metaparameter = myEngine.assetRegistry.globalMetaParameters["weather"] {
    metaparameter.value = "rainy"
}
```

As part of the engine’s asset registry, the [`globalMetaParameters`](/documentation/PHASE/PHASEAssetRegistry/globalMetaParameters) dictionary affects every playing sound event that shares a metaparameter that the dictionary contains.

## Topics

### Base Metaparameters

[`class PHASEMetaParameter`](/documentation/PHASE/PHASEMetaParameter)

A named parameter with a value that the app can change over time.

[`class PHASEMetaParameterDefinition`](/documentation/PHASE/PHASEMetaParameterDefinition)

A specification for a named parameter with a constant value.

[`class PHASEGlobalMetaParameterAsset`](/documentation/PHASE/PHASEGlobalMetaParameterAsset)

A reference to a registered metaparameter that the app can share with multiple sound events or sources.

### Linear Metaparameters

[`class PHASENumberMetaParameter`](/documentation/PHASE/PHASENumberMetaParameter)

A metaparameter defined by a number that can change over time.

[`class PHASENumberMetaParameterDefinition`](/documentation/PHASE/PHASENumberMetaParameterDefinition)

A specification for a metaparameter defined by a number.

### Textual Metaparameters

[`class PHASEStringMetaParameter`](/documentation/PHASE/PHASEStringMetaParameter)

A metaparameter with a text definition that can change over time.

[`class PHASEStringMetaParameterDefinition`](/documentation/PHASE/PHASEStringMetaParameterDefinition)

A specification for a metaparameter defined by text.

### Graphed Metaparameters

[`class PHASEMappedMetaParameterDefinition`](/documentation/PHASE/PHASEMappedMetaParameterDefinition)

A metaparameter that graphs an input value on a set of mathematical curves.


---

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)