Cluster Voice¶
Cluster - Voice
Import¶
import "_IVLS/source/cluster - Voice.ksp"Overview¶
Cluster - Voice
LIBRARY MODULE
Voice ADT definition, lifecycle macros, play/pass sugar, and the core Voice processing loop for IVLS.
- Voice struct member layout and initialisation data
- Lifecycle macros: Constructor, CopyConstructor, Destructor
- User-facing play/pass commands
- Per-stage dispatch loop (Voice.CB) and node trigger handler (Voice.ProcessNewTrigger)
- Time-wait helpers
API¶
Defines¶
| Name | Description |
|---|---|
define Voice.BASE_MEMBERS |
Comma-separated list of all base Voice field names in declaration order. |
define Voice.INIT_LIST |
Ordered concatenation of the base and additional Voice initialisation arrays. |
define Voice.MEMBERS |
Ordered list of all Voice member field names. |
define Voice.validate.auto_release(#v#) |
Validates the auto_release field: must be 0 or 1. |
define Voice.validate.config(#v#) |
Validates the config field: must be a non-negative config index. |
define Voice.validate.delay(#v#) |
Validates the delay field: must be a non-negative microsecond duration. |
define Voice.validate.delay_type(#v#) |
Validates the delay_type field: must be a valid ivls.duration_type index. |
define Voice.validate.duration(#v#) |
Validates the duration field: must be a non-negative duration value. |
define Voice.validate.duration_type(#v#) |
Validates the duration_type field: must be a valid ivls.duration_type index. |
define Voice.validate.dyn_layer(#v#) |
Validates the dyn_layer field: must be a positive layer index. |
define Voice.validate.emc(#v#) |
Validates the emc field: must be -1 or a valid EMC reference. |
define Voice.validate.event(#v#) |
Validates the event field: always returns TRUE (no constraint). |
define Voice.validate.flow(#v#) |
Validates the flow field: must be a valid flow index. |
define Voice.validate.input(#v#) |
Validates the input field: must be a valid ivls.input_type index. |
define Voice.validate.midi_ch(#v#) |
Validates the midi_ch field: must be a MIDI channel number in 0-127. |
define Voice.validate.midi_duration(#v#) |
Validates the midi_duration field: must be -1 or a non-negative tick duration. |
define Voice.validate.note(#v#) |
Validates the note field: must be a MIDI note number in 0-127. |
define Voice.validate.note_on_time(#v#) |
Validates the note_on_time field: must be a non-negative engine uptime value. |
define Voice.validate.offset(#v#) |
Validates the offset field: must be a non-negative sample offset. |
define Voice.validate.pan(#v#) |
Validates the pan field: always returns TRUE (no constraint). |
define Voice.validate.release_fired(#v#) |
Validates the release_fired field: must be -1 or any non-negative integer. |
define Voice.validate.rr(#v#) |
Validates the rr (round-robin) field: must be a non-negative index. |
define Voice.validate.runtime(#v#) |
Validates the runtime field: must be -1 or a valid Runtime reference. |
define Voice.validate.runtimeEntry(#v#) |
Validates the runtimeEntry field: must be -1 or a valid Entry reference. |
define Voice.validate.stage(#v#) |
Validates the stage field: must be -1 or within the flow's stage range. |
define Voice.validate.thread(#v#) |
Validates the thread field: must be a non-negative thread index. |
define Voice.validate.tune(#v#) |
Validates the tune field: always returns TRUE (no constraint). |
define Voice.validate.vel(#v#) |
Validates the vel field: must be a MIDI velocity in 1-127. |
define Voice.validate.vmc(#v#) |
Validates the vmc field: must be -1 or a valid VMC reference. |
define Voice.validate.vo_child(#v#) |
Validates the vo_child field: must be -1 or a valid Voice reference. |
define Voice.validate.vo_left(#v#) |
Validates the vo_left field: must be -1 or a valid Voice reference. |
define Voice.validate.vo_parent(#v#) |
Validates the vo_parent field: must be -1 or a valid Voice reference. |
define Voice.validate.vo_right(#v#) |
Validates the vo_right field: must be -1 or a valid Voice reference. |
define Voice.validate.volume(#v#) |
Validates the volume field: must be less than 10000. |
Macros¶
| Name | Description |
|---|---|
ivls.pass |
Advances self to the next flow stage. |
ivls.pass_formal |
Advances self to the next flow stage as a formal (modulable) voice. |
ivls.play(#vo#) |
Sends voice #vo# to the next stage if it has remaining stages in its flow. |
ivls.play.oneshot(#vo#, #us#) |
Sends voice #vo# as a one-shot with a fixed microsecond duration. |
ivls.stop |
Stops the current voice path. |
ivls.wait_ms(#ms#) |
Waits for #ms# milliseconds. |
ivls.wait_ms.unsafe(#ms#) |
Waits for #ms# milliseconds with no cancellation check. |
ivls.wait_ticks(#ticks#) |
Waits for #ticks# MIDI ticks; fires PathCancellation if the voice is destroyed d... |
ivls.wait_ticks.unsafe(#ticks#) |
Waits for #ticks# MIDI ticks with no cancellation check. |
ivls.wait_us(#micros#) |
Waits for #micros# microseconds; fires PathCancellation if the voice is destroye... |
ivls.wait_us.unsafe(#micros#) |
Waits for #micros# microseconds with no cancellation check. |
Voice.CB |
Main per-voice dispatch loop; iterates through flow stages until the path is exh... |
Voice.CB.Cancelled |
Logs a cancellation message naming the node where the path was halted. |
Voice.Constructor(#ref#) |
Constructs a new Voice instance. |
Voice.CopyConstructor(#ref#) |
Copy-constructs a Voice instance, resetting per-note fields on the new copy. |
Voice.def |
Defines all base Voice struct members, their initial values, the RESET_ON_NEW su... |
Voice.Destructor(#ref#) |
Destroys a Voice instance. |
Voice.Functions |
Declares all Voice-related functions and generated voice logic and pass-dispatch... |
Voice.ProcessNewTrigger |
Dispatches VOICE_ON and VOICE_OFF node logic for the current stage and performs ... |
Voice.WriteInitList(#array#) |
Appends all elements of #array# into Voice.INIT at the current write cursor. |
Functions¶
| Name | Description |
|---|---|
ivls.new_formal_voice(tpl) -> return |
Allocates a new formal (modulable) Voice by copying tpl and returns its referenc... |
ivls.new_voice(tpl) -> return |
Allocates a new Voice by copying tpl and returns its reference. |
Task Functions¶
| Name | Description |
|---|---|
ivls.send_voice() |
Fires vo_input as a new child voice, resolving the parent from self or the omni ... |
Defines¶
define Voice.BASE_MEMBERS¶
Comma-separated list of all base Voice field names in declaration order.
define Voice.INIT_LIST¶
Ordered concatenation of the base and additional Voice initialisation arrays.
define Voice.MEMBERS¶
Ordered list of all Voice member field names.
define Voice.validate.auto_release(#v#)¶
Validates the auto_release field: must be 0 or 1.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.config(#v#)¶
Validates the config field: must be a non-negative config index.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.delay(#v#)¶
Validates the delay field: must be a non-negative microsecond duration.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.delay_type(#v#)¶
Validates the delay_type field: must be a valid ivls.duration_type index.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.duration(#v#)¶
Validates the duration field: must be a non-negative duration value.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.duration_type(#v#)¶
Validates the duration_type field: must be a valid ivls.duration_type index.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.dyn_layer(#v#)¶
Validates the dyn_layer field: must be a positive layer index.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.emc(#v#)¶
Validates the emc field: must be -1 or a valid EMC reference.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.event(#v#)¶
Validates the event field: always returns TRUE (no constraint).
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.flow(#v#)¶
Validates the flow field: must be a valid flow index.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.input(#v#)¶
Validates the input field: must be a valid ivls.input_type index.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.midi_ch(#v#)¶
Validates the midi_ch field: must be a MIDI channel number in 0-127.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.midi_duration(#v#)¶
Validates the midi_duration field: must be -1 or a non-negative tick duration.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.note(#v#)¶
Validates the note field: must be a MIDI note number in 0-127.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.note_on_time(#v#)¶
Validates the note_on_time field: must be a non-negative engine uptime value.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.offset(#v#)¶
Validates the offset field: must be a non-negative sample offset.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.pan(#v#)¶
Validates the pan field: always returns TRUE (no constraint).
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.release_fired(#v#)¶
Validates the release_fired field: must be -1 or any non-negative integer.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.rr(#v#)¶
Validates the rr (round-robin) field: must be a non-negative index.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.runtime(#v#)¶
Validates the runtime field: must be -1 or a valid Runtime reference.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.runtimeEntry(#v#)¶
Validates the runtimeEntry field: must be -1 or a valid Entry reference.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.stage(#v#)¶
Validates the stage field: must be -1 or within the flow's stage range.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.thread(#v#)¶
Validates the thread field: must be a non-negative thread index.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.tune(#v#)¶
Validates the tune field: always returns TRUE (no constraint).
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.vel(#v#)¶
Validates the vel field: must be a MIDI velocity in 1-127.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.vmc(#v#)¶
Validates the vmc field: must be -1 or a valid VMC reference.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.vo_child(#v#)¶
Validates the vo_child field: must be -1 or a valid Voice reference.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.vo_left(#v#)¶
Validates the vo_left field: must be -1 or a valid Voice reference.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.vo_parent(#v#)¶
Validates the vo_parent field: must be -1 or a valid Voice reference.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.vo_right(#v#)¶
Validates the vo_right field: must be -1 or a valid Voice reference.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
define Voice.validate.volume(#v#)¶
Validates the volume field: must be less than 10000.
| Parameter | Description |
|---|---|
#v# |
Value to validate |
Macros¶
ivls.pass¶
Advances self to the next flow stage. Guards against duplicate calls; does nothing if path_on is FALSE.
ivls.pass_formal¶
Advances self to the next flow stage as a formal (modulable) voice. Guards against duplicate calls; does nothing if path_on is FALSE.
ivls.play(#vo#)¶
Sends voice #vo# to the next stage if it has remaining stages in its flow.
| Parameter | Description |
|---|---|
#vo# |
Voice reference to play |
ivls.play.oneshot(#vo#, #us#)¶
Sends voice #vo# as a one-shot with a fixed microsecond duration. The voice will auto-release after #us# microseconds. Requires a positive duration.
| Parameter | Description |
|---|---|
#vo# |
Voice reference to play |
#us# |
Duration in microseconds (must be > 0) |
ivls.stop¶
Stops the current voice path.
ivls.wait_ms(#ms#)¶
Waits for #ms# milliseconds.
| Parameter | Description |
|---|---|
#ms# |
Duration in milliseconds |
ivls.wait_ms.unsafe(#ms#)¶
Waits for #ms# milliseconds with no cancellation check.
| Parameter | Description |
|---|---|
#ms# |
Duration in milliseconds |
ivls.wait_ticks(#ticks#)¶
Waits for #ticks# MIDI ticks; fires PathCancellation if the voice is destroyed during the wait.
| Parameter | Description |
|---|---|
#ticks# |
Duration in MIDI ticks |
ivls.wait_ticks.unsafe(#ticks#)¶
Waits for #ticks# MIDI ticks with no cancellation check.
| Parameter | Description |
|---|---|
#ticks# |
Duration in MIDI ticks (skipped if <= 0) |
ivls.wait_us(#micros#)¶
Waits for #micros# microseconds; fires PathCancellation if the voice is destroyed during the wait.
| Parameter | Description |
|---|---|
#micros# |
Duration in microseconds |
ivls.wait_us.unsafe(#micros#)¶
Waits for #micros# microseconds with no cancellation check.
| Parameter | Description |
|---|---|
#micros# |
Duration in microseconds (skipped if <= 0) |
Voice.CB¶
Main per-voice dispatch loop; iterates through flow stages until the path is exhausted, stopped, or the voice becomes invalid.
Side effects:
| Name | Type | Purpose |
|---|---|---|
| nenv | integer | NodeEnv reference allocated for this voice pass |
| input_type | integer | Snapshot of Voice[self].input at loop entry |
| passed_vo | integer | Holds a promoted child voice when ivls.pass() is called |
| path_exhausted | boolean | Loop terminator: TRUE when no more stages remain |
| user_continue | boolean | Loop terminator: FALSE when user stops the path |
| current_entry_type | integer | Entry type for the current flow stage |
| current_entry | integer | Node or flow index for the current flow stage |
Voice.CB.Cancelled¶
Logs a cancellation message naming the node where the path was halted.
Voice.Constructor(#ref#)¶
Constructs a new Voice instance.
| Parameter | Description |
|---|---|
#ref# |
Voice reference slot being initialised |
Side effects: | Name | Type | Purpose | |------|------|---------| | ref | integer | Local alias for #ref# passed to the constructor callback |
Voice.CopyConstructor(#ref#)¶
Copy-constructs a Voice instance, resetting per-note fields on the new copy.
| Parameter | Description |
|---|---|
#ref# |
Voice reference to copy-construct |
Side effects: | Name | Type | Purpose | |------|------|---------| | ref | integer | Local alias for #ref# passed to the copy-constructor callback |
Voice.def¶
Defines all base Voice struct members, their initial values, the RESET_ON_NEW subset, per-field validators, and the INIT scratch array.
Side effects:
| Name | Type | Purpose |
|---|---|---|
| Voice.BASE_MEMBERS | integer_array | Compile-time member name list |
| Voice.BASE_INIT | integer_array | Per-member reset values |
| Voice.RESET_ON_NEW | integer_array | Field indices to reset when a voice is recycled |
| Voice.INIT | integer_array | 256-slot scratch array written by WriteInitList |
| Voice.write_idx | integer | Write cursor for Voice.INIT population |
Voice.Destructor(#ref#)¶
Destroys a Voice instance.
| Parameter | Description |
|---|---|
#ref# |
Voice reference to destroy |
Side effects: | Name | Type | Purpose | |------|------|---------| | ref | integer | Local alias for #ref# passed to the destructor callback |
Voice.Functions¶
Declares all Voice-related functions and generated voice logic and pass-dispatch select blocks.
Voice.ProcessNewTrigger¶
Dispatches VOICE_ON and VOICE_OFF node logic for the current stage and performs release-time cleanup.
Voice.WriteInitList(#array#)¶
Appends all elements of #array# into Voice.INIT at the current write cursor.
| Parameter | Description |
|---|---|
#array# |
Source array to copy into Voice.INIT |
Side effects:
| Name | Type | Purpose |
|---|---|---|
| Voice.INIT | integer_array | Destination array written at Voice.write_idx..+len |
| Voice.write_idx | integer | Advanced by the number of elements written |
Functions¶
ivls.new_formal_voice(tpl) -> return¶
Allocates a new formal (modulable) Voice by copying tpl and returns its reference.
| Parameter | Type | Description |
|---|---|---|
tpl |
integer | Template Voice reference to copy |
Returns: return — Reference to the newly allocated modulable Voice
ivls.new_voice(tpl) -> return¶
Allocates a new Voice by copying tpl and returns its reference.
| Parameter | Type | Description |
|---|---|---|
tpl |
integer | Template Voice reference to copy |
Returns: return — Reference to the newly allocated Voice
Side effects: | Name | Type | Purpose | |------|------|---------| | new_vo | integer | Holds the result of Voice.copy before assigning to return |
Task Functions¶
ivls.send_voice()¶
Fires vo_input as a new child voice, resolving the parent from self or the omni voice.
Side effects:
| Name | Type | Purpose |
|---|---|---|
| vo_to_send | integer | Resolved voice to fire (may be a copy of self) |
| vo_as_parent | integer | Resolved parent voice (self or omni) |
Example¶
// TODO: Add usage example