AudioHandle & AudioMultiHandle

AudioHandle

Namespace: AudioSystem Description: Controls a single audio playback instance: every voice the post started, including voices that start later. A Routing container with several clips, every layer of a Blend, and each clip an auto-advancing Sequence goes on to play all belong to the handle, so Stop, Pause, the volume and pitch calls, SeekTo and SetLoop reach the whole sound. OnFinished fires only when nothing is sounding and nothing more is coming: after a Sequence’s last clip (not during a Delay After gap), and after any delayed Play actions. Stop() also cancels whatever was still to come.

Properties

public string EventName { get; }
public AudioEvent SourceEvent { get; }
public AudioEmitter Emitter { get; } // The emitter it was posted on, or null
public bool IsPaused { get; }
public bool isPlaying { get; }  // True while any voice is playing
public float time { get; }      // Playback time of the primary (first) voice, in seconds
public float duration { get; }  // Clip duration of the primary (first) voice, in seconds

---

Events

public event System.Action OnStarted;
public event System.Action OnLoop;      // declared, but not raised in this version
public event System.Action OnStopping;
public event System.Action OnFinished;

Description: Callbacks for playback lifecycle events.

• OnStarted: a voice of this post started.
• OnStopping: a Stop(fadeTime) fade-out has begun. Not raised for Stop(0) or by crossfades.
• OnFinished: the post has finished: every voice has ended and nothing is still to come. Subscribing after it finished invokes the handler at once.
• OnLoop: declared but never raised in this version. Don’t rely on it.
• Subscribing OnStarted, OnStopping or OnLoop once the handle has finished does nothing: they can’t fire any more. (An inert process’s posts all return one such shared handle; see AudioManager.Inert.)

Example:

AudioHandle handle = myEvent.Post();
handle.OnStarted += () => Debug.Log("Started");
handle.OnFinished += () => Debug.Log("Finished");

---

Methods

SetVolumeScale

public void SetVolumeScale(float scale)

Description: Scales the sound relative to its authored volume. 1 = as authored, 0.5 = half. Calling it twice with 0.5 means 0.5, not 0.25. Container volume randomization and bus levels still apply on top. Reaches the voices playing now and the ones the sound starts later: a Sequence’s next clip, a playing Switch’s new choice, a delayed Play action (since 3.1.0-dev.7; before, only the voices playing then). VolumeScale reads it back.

Parameters:

• scale - Multiplier on the authored volume

SetVolumeOffset

public void SetVolumeOffset(float db)
public float VolumeOffsetDb { get; }

Description: SetVolumeScale in dB (3.1.0-dev.7): -3 plays the sound 3 dB below how it was authored, now and in the voices it starts later. The same slot as SetVolumeScale: the last call wins. Settable at the post with PostValues.WithVolumeOffset. Composes with the emitter’s Volume Offset. A raise can’t take a voice past its AudioSource’s full volume.

SetVolumeAbsolute

public void SetVolumeAbsolute(float linear)

Description: Replaces the authored volume with an exact level (linear, 1 = full scale), so SetVolumeAbsolute(1f) can be louder than the sound was authored. Use SetVolumeScale unless you mean to ignore the authored level.

SetVolume(float) is obsolete. It has always been absolute, so it forwards to SetVolumeAbsolute. Switch to SetVolumeScale if you wanted a multiplier.

SetPitchOffset

public void SetPitchOffset(float semitones)

Description: Shifts the voices by semitones on top of their own pitch: container pitch randomization and the other pitch-stack slots still apply. Idempotent: SetPitchOffset(2f) twice means +2, not +4. Clears an absolute pitch. Reaches the voices playing now and the ones the sound starts later (the same as SetVolumeScale, since 3.1.0-dev.7). Settable at the post with PostValues.WithPitchOffset. PitchOffset reads it back.

Parameters:

• semitones - Pitch offset (-12 to +12 typical range)

SetPitchAbsolute

public void SetPitchAbsolute(float semitones)

Description: Plays the voices at exactly semitones from their recorded pitch, replacing container pitch randomization and every other pitch-stack slot (Doppler included). Use SetPitchOffset unless you mean to discard the authored variation. Unlike the offset, it reaches only the voices playing now (as does SetVolumeAbsolute).

SetLocalOffset / SetWorldPosition

public void SetLocalOffset(Vector3 offset)
public void SetWorldPosition(Vector3 position)

Description: Move a playing sound (3.1.0-dev.7): a scrape loop following the contact along a wall. SetLocalOffset puts it at offset (metres) from the object it was posted on (its emitter, or the GameObject), in that object’s space; it keeps moving and turning with it, attached or following (On Disable). SetWorldPosition puts it at a world position: on a sound posted on an object that becomes an offset from it; a sound posted at a world position moves there (and SetLocalOffset on it is from the world’s origin). Voices the sound starts later, and Play actions still waiting out a Delay, start where it was moved to. Takes effect at once.

SetPitch(float) is obsolete. It has always replaced the randomized pitch, so it forwards to SetPitchAbsolute. Switch to SetPitchOffset for a shift on top of the authored pitch.

Parameters (the play scope)

public void SetParameter(AudioParameter parameter, float value)
public void ClearParameter(AudioParameter parameter)
public void RampParameter(AudioParameter parameter, float target, float seconds)
public void SnapParameter(AudioParameter parameter)
public void SnapAllParameters()
public void SetSlewOverride(AudioParameter parameter, ParameterSlew slew)
public void ClearSlewOverride(AudioParameter parameter)
public bool TryGetParameter(AudioParameter parameter, out float value)
public float GetEffectiveParameter(AudioParameter parameter)

// For tools: the values on this handle, as on an emitter (the Live View lists them)
public int ParameterCount { get; }
public string GetParameterNameAt(int index)
public float GetParameterValueAt(int index)     // as heard now (after smoothing)
public float GetParameterTargetAt(int index)    // as written
public bool IsParameterMovingAt(int index)      // ramping, smoothing or easing away

Description: A value for this sound only: it wins over its emitter’s and the global value. Use it for values that differ between sounds on one emitter (each axle’s slide speed). It is smoothed separately from the emitter’s value; the first value set here is heard at once. ClearParameter falls back to the emitter’s or global value, easing over if smoothed. RampParameter moves the written value in a straight line (unscaled time), smoothing on top; a new ramp, a Set, a Snap or a Clear replaces it. SnapParameter / SnapAllParameters skip the smoothing now. SetSlewOverride smooths this sound’s value with other settings. TryGetParameter returns the value set on this handle, as written. GetEffectiveParameter returns what the sound hears now: its own value after smoothing, else its emitter’s, else the global value, else the default, clamped to the range.

AudioHandle frontAxle = car.Post(tyreEvent);
frontAxle.SetParameter(slideSpeed, 3.5f);

Attenuation (this play)

public void SetAttenuation(AudioAttenuation attenuation)   // null = ClearAttenuation
public void ClearAttenuation()

Description: Play this sound’s 3D voices with another AudioAttenuation (a hero car heard further away), now and for voices it starts later; ClearAttenuation goes back to its containers’ own. Changes this play only, never an asset. GetEffectiveParameter on a built-in parameter (Distance, Approach Speed, Angle) returns this sound’s value.

Switches (the play scope)

public void SetSwitch(AudioSwitchGroup group, string value)
public void ClearSwitch(AudioSwitchGroup group)
public bool TryGetSwitch(AudioSwitchGroup group, out string value)
public string GetEffectiveSwitch(AudioSwitchGroup group)

Description: A switch value for this sound only (one axle’s surface): it wins over its emitter’s and the global value. A Switch Container in the sound follows it as its WhenSwitchChanges says (USER_GUIDE §4.5). GetEffectiveSwitch returns what the sound reads: its own value, else its emitter’s, else the global one, else the group’s Default Value; for a group driven by a parameter, what the parameter gives in this sound’s scopes (without a playing Switch’s hysteresis). A driven group ignores SetSwitch, with one warning.

Stop

public void Stop(float fadeTime = 0.1f)

Description: Stops playback with optional fade.

Parameters:

• fadeTime - Fade-out duration in seconds

Pause

public void Pause()

Description: Pauses playback (can be resumed).

Resume

public void Resume()

Description: Resumes paused playback.

Dispose

public void Dispose()

Description: Cleans up event handlers to prevent memory leaks.

Note: Dispose() is called automatically when OnFinished is triggered. Manual disposal is only needed if you want to clean up before the sound finishes (e.g., when destroying a GameObject that subscribed to events).

---

AudioMultiHandle

Namespace: AudioSystem Description: Controls multiple synchronized voices (multi-position playback).

Properties

public string EventName { get; }
public AudioEvent SourceEvent { get; }
public bool IsPaused { get; }
public bool isPlaying { get; }
public float time { get; }
public float duration { get; }
public int VoiceCount { get; }
public bool HasVoices { get; }
public MultiPositionType PositionType { get; }

---

Events

public event System.Action OnStarted;
public event System.Action OnLoop;      // declared, but not raised in this version
public event System.Action OnStopping;
public event System.Action OnFinished;

Same meaning as on AudioHandle.

---

Global Methods (All Voices)

SetVolumeScale / SetVolumeAbsolute

public void SetVolumeScale(float scale)
public void SetVolumeAbsolute(float linear)

Description: Same as on AudioHandle, applied to every voice. SetVolumeAbsolute keeps each emitter’s relative balance. SetVolume(float) is obsolete and forwards to SetVolumeAbsolute.

SetPitchOffset / SetPitchAbsolute

public void SetPitchOffset(float semitones)
public void SetPitchAbsolute(float semitones)

Description: Same as on AudioHandle, applied to every voice. The offset keeps each voice’s randomization and Decorrelated nudge; the absolute pitch replaces them. SetPitch(float) is obsolete and forwards to SetPitchAbsolute.

Stop

public void Stop(float fadeTime = 0.1f)

Description: Stops all voices with fade.

Pause / Resume

public void Pause()
public void Resume()

Description: Pauses/resumes all voices.

Dispose

public void Dispose()

Description: Cleans up event handlers and voice references.

---

Per-Emitter Methods

These methods take an emitter index: the position’s index in the array (or emitter list) the post was given. Each one acts on every voice that emitter started. If the container starts several voices per play (a multi-clip Routing, a Blend), all of an emitter’s layers are affected together. The index does not shift when other voices end.

SetVoiceVolumeScale

public void SetVoiceVolumeScale(int emitterIndex, float scale)

Description: Scales one emitter relative to how it was authored (idempotent). SetVoiceVolume is deprecated and forwards here.

SetVoicePitchOffset / SetVoicePitchAbsolute

public void SetVoicePitchOffset(int emitterIndex, float semitones)
public void SetVoicePitchAbsolute(int emitterIndex, float semitones)

Description: The pitch methods for one emitter. SetVoicePitch is obsolete and forwards to SetVoicePitchAbsolute.

StopVoice

public void StopVoice(int emitterIndex, float fadeTime = 0.1f)

Description: Stops one emitter with fade.

PauseVoice / ResumeVoice

public void PauseVoice(int emitterIndex)
public void ResumeVoice(int emitterIndex)

Description: Pauses/resumes one emitter.

---

Position Methods

UpdatePositions

public void UpdatePositions(Vector3[] newPositions)
public void UpdatePositions(Transform[] newTransforms)

Description: Updates emitter positions, one entry per emitter. Every voice an emitter started moves with it.

RefreshPositions

public void RefreshPositions()

Description: Re-reads positions from tracked transforms.

GetVoicePosition

public Vector3? GetVoicePosition(int emitterIndex)

Description: Gets the position of one emitter.

Returns: Position, or null if that emitter has no live voice.

GetAllPositions

public Vector3[] GetAllPositions()

Description: Gets positions of all voices, one entry per voice. An emitter whose container started several voices appears once for each of them.