Steparp Core¶
Stl.Steparp.Core - Step Arpeggiator core logic.
Import¶
import "_IVLS/std-library/nodes/components/steparp/steparp-core.ksp"Node: Stl.Steparp.Core¶
Uses: Init
Overview¶
Stl.Steparp.Core - Step Arpeggiator core logic. LIBRARY
Implements the step arpeggiator engine: timing calculations, voice scheduling, and per-step modulation processing (volume, pan, tune, length). Provides the internal function set shared by all steparp dispatch nodes, plus the notify-relay nodes that forward NoteOn/NoteOff callbacks into the sequencer and arpeggiator step callbacks.
API¶
Nodes¶
| Name | Description |
|---|---|
node Stl.Steparp.Core |
Core step arpeggiator node declaring shared constants and timing/modulation help... |
node Stl.Steparp.Sys.NotifyArpStep |
Relay node that forwards NoteOn/NoteOff into the arpeggiator step callbacks. |
node Stl.Steparp.Sys.NotifySeqStep |
Relay node that forwards NoteOn/NoteOff into the sequencer step callbacks. |
Defines¶
| Name | Description |
|---|---|
define FLOWS += steparp.seq_step_notify |
Register the seq_step_notify flow used by the sequencer step relay. |
define FLOWS += steparp.arp_step_notify |
Register the arp_step_notify flow used by the arpeggiator step relay. |
define Stl.Steparp.Bundle += Stl.Steparp.Core |
Register Stl.Steparp.Core into the steparp bundle. |
define Stl.Steparp.Bundle += Stl.Steparp.Sys.NotifySeqStep, Stl.Steparp.Sys.NotifyArpStep |
Register NotifySeqStep and NotifyArpStep relay nodes into the steparp bundle. |
Const Blocks¶
| Name | Description |
|---|---|
const Arp_Mode |
Arpeggiator/sequencer mode selector constants. |
const Loop_End |
Loop end behavior constants: loop, stop on last step, or hold last note. |
const Note_Order |
Note ordering constants controlling the pitch sequence of arpeggiated notes. |
const trigger_mode |
Trigger mode constants for per-step trigger behavior. |
Functions¶
| Name | Description |
|---|---|
steparp.apply_voice_duration(vo, thread, idx, parity) -> dur |
Apply the step duration to a voice, optionally scaling by the length table facto... |
steparp.calculate_step_length(thread) -> len |
Return the base step length for a thread, choosing between sync-speed (ticks) an... |
steparp.calculate_swing_adjust(thread, parity) -> return |
Calculate the swing timing offset for a step, alternating sign by parity. |
steparp.get_length_table_factor(thread, idx) -> factor |
Map a length table value for a step to a normalized factor in 0.01 to 1.0. |
steparp.get_real_step_length(thread, parity) -> len |
Return the real step length for a thread including swing adjustment. |
steparp.get_step_length_micros(thread, idx, parity) -> us |
Convert the raw step length for a given thread/step into microseconds, applying ... |
steparp.ignore_length(thread, idx) -> bool |
Determine whether the voice duration should be ignored for a step. |
steparp.next_step(thread, idx) -> next |
Return the index of the step following idx, wrapping around seq_steps. |
steparp.process_pan_modbit(step_idx, thread) -> rtrn |
Return the pan modbit value for a step. |
steparp.process_tune_modbit(step_idx, thread, note_num, init_note_num) -> rtrn |
Return the tuning modbit offset for a step in cents * 1000, based on the pitch o... |
steparp.process_vol_modbit(step_idx, thread) -> rtrn |
Return the volume modbit value for a step in millibels (-30000 to 0). |
steparp.spawn_notify(src_vo, flow, thread, idx, parity) -> out_vo |
Spawn a notify voice routed through the given flow, initializing its duration an... |
Nodes¶
node Stl.Steparp.Core¶
Callbacks: Init
Init voice fields:
| Field | Default | Condition |
|---|---|---|
step_arp.table_idx |
-1 |
(step_arp.table_idx >= -1) |
step_arp.event_duration |
0 |
(step_arp.event_duration >= 0) |
Core step arpeggiator node declaring shared constants and timing/modulation helper functions.
node Stl.Steparp.Sys.NotifyArpStep¶
Callbacks: NoteOn, NoteOff, Flows
Relay node that forwards NoteOn/NoteOff into the arpeggiator step callbacks.
node Stl.Steparp.Sys.NotifySeqStep¶
Callbacks: NoteOn, NoteOff, Flows
Relay node that forwards NoteOn/NoteOff into the sequencer step callbacks.
Defines¶
define FLOWS += steparp.seq_step_notify¶
Register the seq_step_notify flow used by the sequencer step relay.
define FLOWS += steparp.arp_step_notify¶
Register the arp_step_notify flow used by the arpeggiator step relay.
define Stl.Steparp.Bundle += Stl.Steparp.Core¶
Register Stl.Steparp.Core into the steparp bundle.
define Stl.Steparp.Bundle += Stl.Steparp.Sys.NotifySeqStep, Stl.Steparp.Sys.NotifyArpStep¶
Register NotifySeqStep and NotifyArpStep relay nodes into the steparp bundle.
Const Blocks¶
const Arp_Mode¶
Arpeggiator/sequencer mode selector constants.
const Loop_End¶
Loop end behavior constants: loop, stop on last step, or hold last note.
const Note_Order¶
Note ordering constants controlling the pitch sequence of arpeggiated notes.
const trigger_mode¶
Trigger mode constants for per-step trigger behavior.
Functions¶
steparp.apply_voice_duration(vo, thread, idx, parity) -> dur¶
Apply the step duration to a voice, optionally scaling by the length table factor. Skips duration assignment when the current step is tied to the next.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | voice index to modify |
thread |
integer | steparp thread index |
idx |
integer | current step index |
parity |
integer | swing parity (0 or 1) |
Returns: dur — unused return variable; duration is written directly to Voice[vo].duration
Side effects:
| Name | Type | Purpose |
|---|---|---|
| $length_us | integer | raw step duration before length scaling |
| $ignore_length | integer | flag suppressing duration when step is tied |
| ~length_factor | real | normalized length table value (0.0 to 1.0) |
steparp.calculate_step_length(thread) -> len¶
Return the base step length for a thread, choosing between sync-speed (ticks) and free-speed (ms) based on the sync parameter.
| Parameter | Type | Description |
|---|---|---|
thread |
integer | steparp thread index |
Returns: len — base step duration (ticks when synced, milliseconds * 1000 when free)
steparp.calculate_swing_adjust(thread, parity) -> return¶
Calculate the swing timing offset for a step, alternating sign by parity. Even-parity steps receive a positive offset; odd-parity steps receive a negative offset.
| Parameter | Type | Description |
|---|---|---|
thread |
integer | steparp thread index |
parity |
integer | swing parity (0 or 1) |
Returns: return — swing adjustment in ticks or milliseconds (signed)
steparp.get_length_table_factor(thread, idx) -> factor¶
Map a length table value for a step to a normalized factor in 0.01 to 1.0.
| Parameter | Type | Description |
|---|---|---|
thread |
integer | steparp thread index |
idx |
integer | step index |
Returns: factor — normalized length factor (0.01 to 1.0)
steparp.get_real_step_length(thread, parity) -> len¶
Return the real step length for a thread including swing adjustment.
| Parameter | Type | Description |
|---|---|---|
thread |
integer | steparp thread index |
parity |
integer | swing parity (0 or 1) |
Returns: len — step duration in raw ticks or milliseconds
steparp.get_step_length_micros(thread, idx, parity) -> us¶
Convert the raw step length for a given thread/step into microseconds, applying ticks-to-ms conversion when tempo sync is active.
| Parameter | Type | Description |
|---|---|---|
thread |
integer | steparp thread index |
idx |
integer | current step index |
parity |
integer | swing parity (0 or 1) |
Returns: us — step duration in microseconds
steparp.ignore_length(thread, idx) -> bool¶
Determine whether the voice duration should be ignored for a step. Returns TRUE when the next step has TIE trigger mode or when the arpeggiator is in HOLD mode and idx is the last step.
| Parameter | Type | Description |
|---|---|---|
thread |
integer | steparp thread index |
idx |
integer | current step index |
Returns: bool — TRUE if duration should not be applied to the voice
steparp.next_step(thread, idx) -> next¶
Return the index of the step following idx, wrapping around seq_steps.
| Parameter | Type | Description |
|---|---|---|
thread |
integer | steparp thread index |
idx |
integer | current step index |
Returns: next — next step index (wrapped)
steparp.process_pan_modbit(step_idx, thread) -> rtrn¶
Return the pan modbit value for a step. Returns 0 (center) when pan table is disabled.
| Parameter | Type | Description |
|---|---|---|
step_idx |
integer | step index within the table |
thread |
integer | steparp thread index |
Returns: rtrn — pan value from the table, or 0 when disabled
steparp.process_tune_modbit(step_idx, thread, note_num, init_note_num) -> rtrn¶
Return the tuning modbit offset for a step in cents * 1000, based on the pitch offset from the initial note number.
| Parameter | Type | Description |
|---|---|---|
step_idx |
integer | step index (present for interface uniformity; pitch derives from note tracking) |
thread |
integer | steparp thread index (present for interface uniformity; unused in body) |
note_num |
integer | current MIDI note number |
init_note_num |
integer | note number at the time the arpeggio started |
Returns: rtrn — tuning offset in millicents (semitone steps * 100000)
steparp.process_vol_modbit(step_idx, thread) -> rtrn¶
Return the volume modbit value for a step in millibels (-30000 to 0). Returns 0 (unity) when volume table is disabled.
| Parameter | Type | Description |
|---|---|---|
step_idx |
integer | step index within the table |
thread |
integer | steparp thread index |
Returns: rtrn — volume in millibels (0 = unity, -30000 = minimum)
steparp.spawn_notify(src_vo, flow, thread, idx, parity) -> out_vo¶
Spawn a notify voice routed through the given flow, initializing its duration and step index, then return the new voice index.
| Parameter | Type | Description |
|---|---|---|
src_vo |
integer | source voice to clone |
flow |
integer | flow ID to route the new voice through |
thread |
integer | steparp thread index |
idx |
integer | step index to stamp on the voice |
parity |
integer | swing parity for duration calculation |
Returns: out_vo — the newly spawned voice index
Side effects:
| Name | Type | Purpose |
|---|---|---|
| $vo | integer | new voice index before assignment to out_vo |
| $duration | integer | computed step duration stamped onto the voice |
Example¶
// TODO: Add usage example