Class AuditySource

Component front-end for playing an DarkEffekt.Audity.AudityGraph on an AudioSource with per-instance control. Optional - assigning a graph to UnityEngine.AudioSource.generator and calling Play works too, with full per-instance control through DarkEffekt.Audity.AudityMessaging (keyed by the AudioSource). Listener and time data are still fed automatically. What this component adds: Play On Enable, the inspector override form, batch groups, and quantized-play priming.

Assembly: DarkEffekt.Audity.Runtime

Declaration

[RequireComponent(typeof(AudioSource))]
[AddComponentMenu("Audio/Audity Source")]
[Icon("Packages/com.darkeffekt.audity/Editor/Icons/Assets/AuditySource.png")]
public sealed class AuditySource : MonoBehaviour

Inheritance: System.Object -> UnityEngine.Object -> UnityEngine.Component -> UnityEngine.Behaviour -> UnityEngine.MonoBehaviour

Properties

IsPlaying

True while the underlying AudioSource is playing.

Declaration

public bool IsPlaying { get; }

Instance

Handle to the live playing instance (DarkEffekt.Audity.AudityInstance.Invalid when not playing). A fresh handle is issued by every DarkEffekt.Audity.AuditySource.Play(float); expired handles no-op harmlessly, so it is safe to hold one across the instance’s end.

Declaration

public AudityInstance Instance { get; }

Fields

graph

What this component plays: an DarkEffekt.Audity.AudityPlayable - a node DarkEffekt.Audity.AudityGraph today. Typed to the base so a form-authored playable that lowers to a graph stays assignable if one returns later; existing graph references resolve unchanged.

Declaration

[FormerlySerializedAs("asset")]
public AudityPlayable graph

playOnEnable

Plays automatically on enable (mirrors AudioSource.playOnAwake).

Declaration

[Tooltip("Play automatically on enable (mirrors AudioSource.playOnAwake).")]
public bool playOnEnable

batchGroup

Optional group this source shares its playback cap with; sources assigned the same group are batched together by DarkEffekt.Audity.AuditySource.Play(float). Pure main-thread policy - does not shape the DSP graph.

Declaration

[Tooltip("Optional: sources sharing a Batch Group are capped together - dense bursts are stolen, rejected, or swapped for the group's composite sound.")]
public AudityBatchGroup batchGroup

overrides

Consumer-form overrides for the graph’s Public interface members (Tier-1: form over a locked template - Public IS the form). Entries exist only for fields the user edited; everything else tracks the graph’s defaults live. Applied on every DarkEffekt.Audity.AuditySource.Play(float), before any code-issued binds (code wins).

Declaration

public List<AuditySourceOverride> overrides

Methods

Play(float)

Assigns DarkEffekt.Audity.AuditySource.graph to the AudioSource and starts playback.

Declaration

public void Play(float fadeInSeconds = 0)

Parameters

Type	Name	Description
System.Single	fadeInSeconds	Fade-in length in seconds; 0 starts at full volume immediately.

PlayQuantized(AudityQuantize, float)

Starts playback aligned to the musical grid: the instance renders silence until the next startQuantize boundary of its effective transport, then begins exactly there (On Play fires at the boundary sample) - the bar-aligned song handoff and the in-phase layer spin-up. A DarkEffekt.Audity.AudityTempoMode.Drive graph re-anchors its transport at that boundary. With no active transport, starts immediately.

Declaration

public void PlayQuantized(AudityQuantize startQuantize, float fadeInSeconds = 0)

Parameters

Type	Name
DarkEffekt.Audity.AudityQuantize	startQuantize
System.Single	fadeInSeconds

Stop(float)

Stops playback, optionally fading out first.

Declaration

public void Stop(float fadeOutSeconds = 0)

Parameters

Type	Name
System.Single	fadeOutSeconds

SetParameter(AudityParameterId, float, float, int)

Sets a parameter on THIS SOURCE: the value applies to the live instance immediately (with glide) and is remembered by the component - every future DarkEffekt.Audity.AuditySource.Play(float) re-applies it to the fresh instance, the same stickiness as DarkEffekt.Audity.AuditySource.BindSource(System.String%2cDarkEffekt.Audity.AudityBankHandle). Setting before Play is therefore fine. It takes precedence over global parameter updates while that instance plays. For strictly live-instance-only messaging use DarkEffekt.Audity.AudityMessaging directly.

Declaration

public void SetParameter(AudityParameterId id, float value, float smoothSeconds = -1, int elementIndex = 0)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
System.Single	value
System.Single	smoothSeconds
System.Int32	elementIndex

SetParameter(string, float, float, int)

Declaration

public void SetParameter(string name, float value, float smoothSeconds = -1, int elementIndex = 0)

Parameters

Type	Name
System.String	name
System.Single	value
System.Single	smoothSeconds
System.Int32	elementIndex

SetFloat(AudityParameterId, float, float, int)

Declaration

public void SetFloat(AudityParameterId id, float value, float smoothSeconds = -1, int elementIndex = 0)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
System.Single	value
System.Single	smoothSeconds
System.Int32	elementIndex

SetFloat(string, float, float, int)

Declaration

public void SetFloat(string name, float value, float smoothSeconds = -1, int elementIndex = 0)

Parameters

Type	Name
System.String	name
System.Single	value
System.Single	smoothSeconds
System.Int32	elementIndex

TryGetFloat(AudityParameterId, out float, int)

Reads back a member the GRAPH writes (Direction = Out) - an Envelope Follower’s level, a Noise Gate’s Open, anything a Parameter Out node feeds. The read half of DarkEffekt.Audity.AuditySource.SetFloat(System.String%2cSystem.Single%2cSystem.Single%2cSystem.Int32).

Declaration

public bool TryGetFloat(AudityParameterId id, out float value, int element = 0)

Returns

System.Boolean: False when this source is not playing, the member is not marked Out, or the engine has not reported it yet (the first frame of playback). The value is a snapshot as of the engine’s last report, roughly a frame old: it crosses the audio thread, so it can never be sample-accurate. Keep sample-accurate reactions inside the graph, where the value already is.

Parameters

Type	Name	Description
DarkEffekt.Audity.AudityParameterId	id
System.Single	value
System.Int32	element	Array/vector element; 0 for scalars.

TryGetFloat(string, out float, int)

Reads back a member the GRAPH writes (Direction = Out) - an Envelope Follower’s level, a Noise Gate’s Open, anything a Parameter Out node feeds. The read half of DarkEffekt.Audity.AuditySource.SetFloat(System.String%2cSystem.Single%2cSystem.Single%2cSystem.Int32).

Declaration

public bool TryGetFloat(string name, out float value, int element = 0)

Returns

System.Boolean: False when this source is not playing, the member is not marked Out, or the engine has not reported it yet (the first frame of playback). The value is a snapshot as of the engine’s last report, roughly a frame old: it crosses the audio thread, so it can never be sample-accurate. Keep sample-accurate reactions inside the graph, where the value already is.

Parameters

Type	Name	Description
System.String	name
System.Single	value
System.Int32	element	Array/vector element; 0 for scalars.

GetFloat(AudityParameterId, float, int)

Read-back with a fallback, for call sites that would rather not branch.

Declaration

public float GetFloat(AudityParameterId id, float fallback = 0, int element = 0)

Returns

System.Single

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
System.Single	fallback
System.Int32	element

GetFloat(string, float, int)

Read-back with a fallback, for call sites that would rather not branch.

Declaration

public float GetFloat(string name, float fallback = 0, int element = 0)

Returns

System.Single

Parameters

Type	Name
System.String	name
System.Single	fallback
System.Int32	element

TryGetVector(AudityParameterId, out Vector4, int)

Reads back a Vector2/3/4 member the graph writes, componentwise.

Declaration

public bool TryGetVector(AudityParameterId id, out Vector4 value, int componentCount = 4)

Returns

System.Boolean

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
UnityEngine.Vector4	value
System.Int32	componentCount

TryGetVector(string, out Vector4, int)

Reads back a Vector2/3/4 member the graph writes, componentwise.

Declaration

public bool TryGetVector(string name, out Vector4 value, int componentCount = 4)

Returns

System.Boolean

Parameters

Type	Name
System.String	name
UnityEngine.Vector4	value
System.Int32	componentCount

GetFloats(AudityParameterId, Span<float>)

Reads a Float ARRAY member the graph writes - a Spectrum Analyzer’s bands, say - into destination, element 0 first. A float[] converts implicitly, so pass one you keep around rather than allocating per frame. Reading stops at the first element the engine has not reported, which is the member’s real length: a shorter member fills only its own elements and leaves the rest of the span untouched.

Declaration

public int GetFloats(AudityParameterId id, Span<float> destination)

Returns

System.Int32: How many elements were filled; 0 if the instance is not playing or nothing has been reported yet.

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
System.Span<System.Single>	destination

GetFloats(string, Span<float>)

Reads a Float ARRAY member the graph writes - a Spectrum Analyzer’s bands, say - into destination, element 0 first. A float[] converts implicitly, so pass one you keep around rather than allocating per frame. Reading stops at the first element the engine has not reported, which is the member’s real length: a shorter member fills only its own elements and leaves the rest of the span untouched.

Declaration

public int GetFloats(string name, Span<float> destination)

Returns

System.Int32: How many elements were filled; 0 if the instance is not playing or nothing has been reported yet.

Parameters

Type	Name
System.String	name
System.Span<System.Single>	destination

SetBool(AudityParameterId, bool)

Declaration

public void SetBool(AudityParameterId id, bool value)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
System.Boolean	value

SetBool(string, bool)

Declaration

public void SetBool(string name, bool value)

Parameters

Type	Name
System.String	name
System.Boolean	value

SetInt(AudityParameterId, int)

Declaration

public void SetInt(AudityParameterId id, int value)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
System.Int32	value

SetInt(string, int)

Declaration

public void SetInt(string name, int value)

Parameters

Type	Name
System.String	name
System.Int32	value

SetVector(AudityParameterId, Vector4, int, float)

Sets a Vector2/3/4 member componentwise (per-element glide, sticky like DarkEffekt.Audity.AuditySource.SetParameter(DarkEffekt.Audity.AudityParameterId%2cSystem.Single%2cSystem.Single%2cSystem.Int32)).

Declaration

public void SetVector(AudityParameterId id, Vector4 value, int componentCount, float smoothSeconds = -1)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
UnityEngine.Vector4	value
System.Int32	componentCount
System.Single	smoothSeconds

SetVector(AudityParameterId, Vector2, float)

Declaration

public void SetVector(AudityParameterId id, Vector2 value, float smoothSeconds = -1)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
UnityEngine.Vector2	value
System.Single	smoothSeconds

SetVector(string, Vector2, float)

Declaration

public void SetVector(string name, Vector2 value, float smoothSeconds = -1)

Parameters

Type	Name
System.String	name
UnityEngine.Vector2	value
System.Single	smoothSeconds

SetVector(AudityParameterId, Vector3, float)

Declaration

public void SetVector(AudityParameterId id, Vector3 value, float smoothSeconds = -1)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
UnityEngine.Vector3	value
System.Single	smoothSeconds

SetVector(string, Vector3, float)

Declaration

public void SetVector(string name, Vector3 value, float smoothSeconds = -1)

Parameters

Type	Name
System.String	name
UnityEngine.Vector3	value
System.Single	smoothSeconds

SetVector(AudityParameterId, Vector4, float)

Declaration

public void SetVector(AudityParameterId id, Vector4 value, float smoothSeconds = -1)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
UnityEngine.Vector4	value
System.Single	smoothSeconds

SetVector(string, Vector4, float)

Declaration

public void SetVector(string name, Vector4 value, float smoothSeconds = -1)

Parameters

Type	Name
System.String	name
UnityEngine.Vector4	value
System.Single	smoothSeconds

Trigger(AudityQuantize)

Declaration

public void Trigger(AudityQuantize quantize = AudityQuantize.Immediate)

Parameters

Type	Name
DarkEffekt.Audity.AudityQuantize	quantize

Trigger(AudityParameterId, AudityQuantize)

Declaration

public void Trigger(AudityParameterId id, AudityQuantize quantize = AudityQuantize.Immediate)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
DarkEffekt.Audity.AudityQuantize	quantize

Trigger(string, AudityQuantize)

Declaration

public void Trigger(string name, AudityQuantize quantize = AudityQuantize.Immediate)

Parameters

Type	Name
System.String	name
DarkEffekt.Audity.AudityQuantize	quantize

SetTempo(double, int)

Declaration

public void SetTempo(double bpm, int beatsPerBar = 4)

Parameters

Type	Name
System.Double	bpm
System.Int32	beatsPerBar

SetBlackboard(AudityParameterId, float, float, int)

Writes a scalar blackboard slot (Float/Bool/Int/Enum/Time member): the slot smooths over its authored glide and the next block reads it. Live, cheap, allocation-free - safe to call every frame. Use the DarkEffekt.Audity.AudityParameterId overload as the hashed fast path for hot setters. Blackboard keys and source-bind keys share one namespace, typed by domain: a scalar write against a Sample Set slot is a logged typed error, not a silent miss.

Declaration

public void SetBlackboard(AudityParameterId id, float value, float smoothSeconds = -1, int elementIndex = 0)

Parameters

Type	Name
DarkEffekt.Audity.AudityParameterId	id
System.Single	value
System.Single	smoothSeconds
System.Int32	elementIndex

SetBlackboard(string, float, float, int)

Writes a scalar blackboard slot (Float/Bool/Int/Enum/Time member): the slot smooths over its authored glide and the next block reads it. Live, cheap, allocation-free - safe to call every frame. Use the DarkEffekt.Audity.AudityParameterId overload as the hashed fast path for hot setters. Blackboard keys and source-bind keys share one namespace, typed by domain: a scalar write against a Sample Set slot is a logged typed error, not a silent miss.

Declaration

public void SetBlackboard(string name, float value, float smoothSeconds = -1, int elementIndex = 0)

Parameters

Type	Name
System.String	name
System.Single	value
System.Single	smoothSeconds
System.Int32	elementIndex

BindSource(string, AudityBankHandle)

Points a rebindable source key (a Sample Set interface member) at a resident bank - the hot path: repoint + refcount only, cannot load. The bind is a persistent per-source slot: it survives across DarkEffekt.Audity.AuditySource.Play(float) calls (re-issued to each new instance) and applies to future triggers; voices already playing ride their old bank to completion. A looping voice never completes - stop and retrigger it to observe a rebind. The handle stays caller-owned: keep it loaded for as long as the bind should outlive playing instances.

Declaration

public void BindSource(string key, AudityBankHandle bank)

Parameters

Type	Name
System.String	key
DarkEffekt.Audity.AudityBankHandle	bank

BindSource(string, AuditySampleSet)

Convenience cold path: prepares (or re-adopts) the Set’s bank and binds it. Loads-if-cold - a documented slow path that warns once; for pooled/hot binding, warm the bank yourself (DarkEffekt.Audity.AudityBank.Load(DarkEffekt.Audity.AuditySampleSet) at level load) and use the handle overload. The component owns the loaded handle and releases it when the key is rebound or the component is destroyed.

Declaration

public void BindSource(string key, AuditySampleSet set)

Parameters

Type	Name
System.String	key
DarkEffekt.Audity.AuditySampleSet	set

BindSource(string, Object)

Convenience cold path: prepares (or re-adopts) the Set’s bank and binds it. Loads-if-cold - a documented slow path that warns once; for pooled/hot binding, warm the bank yourself (DarkEffekt.Audity.AudityBank.Load(DarkEffekt.Audity.AuditySampleSet) at level load) and use the handle overload. The component owns the loaded handle and releases it when the key is rebound or the component is destroyed.

Declaration

public void BindSource(string key, Object source)

Parameters

Type	Name
System.String	key
UnityEngine.Object	source

ClearSource(string)

Clears a source key back to the graph’s compile-baked default content.

Declaration

public void ClearSource(string key)

Parameters

Type	Name
System.String	key

Play(string, AudityBankHandle, AudityQuantize)

Per-call source argument (dialogue semantics): starts playback if needed, captures bank into the voices spawned by the resulting Play trigger - independent of the persistent DarkEffekt.Audity.AuditySource.BindSource(System.String%2cDarkEffekt.Audity.AudityBankHandle) slot, which stays the fallback for triggers without an argument - and fires. Unambiguous under overlap: voices from the previous call keep their bank. If the graph declares a Public Trigger named DarkEffekt.Audity.AudityParameterDef.DefaultPlayName it is fired; otherwise the anonymous trigger. Warm the bank first (DarkEffekt.Audity.AudityBank.Load(DarkEffekt.Audity.AuditySampleSet) + DarkEffekt.Audity.AudityBankHandle.IsReady) or accept first-call silence while it loads.

Declaration

public void Play(string sourceKey, AudityBankHandle bank, AudityQuantize quantize = AudityQuantize.Immediate)

Parameters

Type	Name
System.String	sourceKey
DarkEffekt.Audity.AudityBankHandle	bank
DarkEffekt.Audity.AudityQuantize	quantize

Events

Finished

Raised on the main thread when playback ends.

Declaration

public event Action Finished

Event Type

System.Action

TriggerFired

Raised on the main thread when a Trigger member marked Out fires inside this source’s graph - the graph telling the game something happened, rather than the game telling the graph. Wire a Trigger Out node to whatever should announce itself.

Declaration

public event Action<AudityParameterId> TriggerFired

Event Type

System.Action<DarkEffekt.Audity.AudityParameterId>