Runtime API

The public runtime API is in:

using PaperLynxStudio.AudioCueToolkit;

Editor waveform, export, Inspector, Welcome, and Documentation types are compiled into an editor-only assembly and must not be referenced by runtime code.

AudioCue#

AudioCue is a ScriptableObject containing variants and shared playback settings.

Read-only properties:

• Clips: IReadOnlyList<AudioCueClip>
• SelectionMode: active AudioCueSelectionMode
• LoopMode: active AudioCueLoopMode
• Volume: clamped target volume
• PitchRange: ordered and clamped pitch range
• Delay: non-negative delay
• MixerGroup: optional AudioMixerGroup
• Spatial: AudioCueSpatialSettings
• Equalizer: AudioCueEqualizerSettings
• Priority: Unity priority from 0 to 256
• MaxSimultaneousVoices: zero or a positive limit
• RetriggerCooldown: non-negative cooldown in seconds

Public methods:

void AddClip(AudioCueClip clip)
bool HasPlayableClip()

AddClip is available for editor tooling or runtime-created ScriptableObjects. Normal authored assets should be edited through the AudioCue Inspector.

AudioCueClip#

Every variant exposes:

• Clip
• Weight
• StartTime
• EndTime
• Duration
• FadeInDuration
• FadeOutDuration
• BypassCueFade
• BypassCueEqualizer

The simple constructor creates a full-length variant with weight 1 and no fades:

AudioCueClip entry = new AudioCueClip(sourceClip);

The complete constructor accepts the clip, weight, range, fades, and baked-processing bypass flags.

AudioCueSelectionMode#

• RandomNoRepeat
• WeightedRandom
• Sequential

AudioCueLoopMode#

• Off
• RepeatSelected
• ReselectEachLoop

AudioCueEqualizerSettings#

Read-only properties:

• Enabled
• LowGainDb
• MidGainDb
• HighGainDb
• IsFlat

Public constants expose the supported gain range, fixed band frequencies, mid-band Q, and smoothing duration. The authored settings are read through AudioCue.Equalizer.

AudioCueSpatialSettings#

Read-only properties:

• OverrideAudioSource
• SpatialBlend
• ReverbZoneMix
• Spread
• DopplerLevel
• RolloffMode
• MinDistance
• MaxDistance
• VolumeRolloff
• SpatialBlendCurve
• SpreadCurve
• ReverbZoneMixCurve

The authored settings are read through AudioCue.Spatial. AudioManager applies them to every acquired voice when OverrideAudioSource is enabled.

ThreeBandEqualizer#

ThreeBandEqualizer is the public DSP processor used by AudioCue's runtime filter and editor preview. It processes interleaved floating-point sample arrays in place.

void Configure(
    int sampleRate,
    float lowGainDb,
    float midGainDb,
    float highGainDb,
    bool immediate = false)

void Reset()
void Process(float[] samples, int channels)

MaximumChannels is 8. Call Configure before Process and call Reset when reusing an instance for an unrelated stream. Most integrations should author AudioCue.Equalizer and let AudioManager own the processor instead of processing sample buffers directly.

AudioPoolOverflowMode#

• CreateTemporaryVoice: expand beyond the initial pool up to Max Temporary Voices, then steal the least important voice
• StealLowestPriority: reuse the least important active voice as soon as the prepared pool is full

AudioManager#

AudioManager.Instance refers only to an explicitly placed, enabled manager. It is null when no manager has completed Awake.

Playback methods:

AudioHandle Play(AudioCue cue)
AudioHandle PlayAt(AudioCue cue, Vector3 position)
AudioHandle PlayAttached(AudioCue cue, Transform followTarget)

Stop methods:

void StopAll()
void StopAll(AudioCue cue)

Runtime statistics:

• ActiveVoiceCount
• PooledVoiceCount
• TemporaryVoiceCount

Play places the voice at the manager position. PlayAt uses a fixed world position. PlayAttached follows the supplied Transform until playback ends; a null target rejects the request.

A play request returns an invalid handle when the manager is inactive, the cue is null or empty, cooldown rejects the request, or no voice can be acquired. Check the result before storing or controlling it.

AudioManager manager = AudioManager.Instance;
if (manager == null)
    return;

AudioHandle handle = manager.PlayAt(_impactCue, hit.point);
if (!handle.IsValid)
    Debug.LogWarning("AudioCue request was not accepted.");

AudioHandle#

AudioHandle is a readonly value identifying a voice ID and generation.

Properties:

• IsValid: true only while that exact voice generation is active
• State: current AudioPlaybackState or Invalid
• EndReason: nullable terminal reason retained by the manager
• IsPlaying: true for Playing and FadingOut

Methods:

bool Pause()
bool Resume()
bool Stop(float fadeOutSeconds = -1f)
bool TryGetEndReason(out AudioPlaybackEndReason reason)

Stop() with the default argument uses the selected variant's fade-out duration. Pass 0 for an immediate stop or a positive value for an explicit stop fade.

A completed or stopped handle is no longer valid, but its end reason can remain available in the manager's bounded history. Do not use IsValid as the only check when reading a terminal reason.

AudioPlaybackState#

• Invalid: no active matching voice
• Scheduled: waiting for cue delay
• Playing: AudioSource is playing the selected segment
• Paused: scheduled, playing, or fading timing is frozen
• FadingOut: a manual stop fade is active

AudioPlaybackEndReason#

• Completed: the non-looping segment ended naturally
• Stopped: playback was stopped manually or through StopAll
• Stolen: cue limits or manager overflow replaced the voice
• FollowTargetDestroyed: the Transform supplied to PlayAttached was destroyed
• ManagerDestroyed: the owning manager was destroyed

AudioCuePlayer#

Properties:

• Cue: get or assign the AudioCue
• Handle: most recently returned handle
• IsPlaying: playback state of the current handle

Methods:

AudioHandle Play()
void PlayFromEvent()
void Pause()
void Resume()
void Stop()
void StopImmediate()

PlayFromEvent is the parameterless void wrapper intended for persistent UnityEvent listeners. Stop uses the cue variant's fade-out. StopImmediate uses zero seconds.

The component exposes Started, Paused, Resumed, Completed, and Stopped UnityEvents. Completed is invoked only for natural completion. Stopped covers manual stop, stealing, a destroyed follow target, and manager destruction.

When the component is disabled, its active handle is stopped immediately. The component does not require a local AudioSource or Collider and does not destroy its GameObject.

AudioCueTrigger#

AudioCueTrigger calls an assigned AudioCuePlayer from OnTriggerEnter and optionally stops it from OnTriggerExit.

Inspector settings:

• Player
• Layers
• optional Required Tag
• Once Per Entry
• Stop On Exit

The component counts accepted colliders inside the trigger. With Once Per Entry enabled, playback starts when the first accepted collider enters. Stop On Exit acts when the last accepted collider leaves.

AudioCueMouseTrigger#

AudioCueMouseTrigger raycasts from the current Input System pointer through Pointer Camera or Camera.main.

Inspector settings:

• Player
• Play On Hover
• Play On Click
• Play Only Once
• Pointer Camera

The primary mouse button, pen tip, and primary touchscreen press are supported. Play Only Once is recorded only after a play request returns a valid handle.

Stop one cue without affecting others#

AudioManager.Instance?.StopAll(_ambientCue);

Observe completion from a coroutine#

using System.Collections;
using PaperLynxStudio.AudioCueToolkit;
using UnityEngine;

public sealed class AudioSequence : MonoBehaviour
{
    [SerializeField] private AudioCue _cue;

    private IEnumerator Start()
    {
        if (AudioManager.Instance == null)
            yield break;

        AudioHandle handle = AudioManager.Instance.Play(_cue);
        if (!handle.IsValid)
            yield break;

        while (handle.IsValid)
            yield return null;

        if (handle.TryGetEndReason(out AudioPlaybackEndReason reason))
            Debug.Log($"Audio ended: {reason}");
    }
}

Call the runtime API from Unity's main thread. AudioCue does not expose a thread-safe background playback interface.