Generative & Random
Cycle callbacks, streams, Markov chains, and seeded randomness. Random and stream/markov helpers need use "std/random"; / use "std/generative";.
_Markov
Section titled “_Markov”fn new(num_states: Number, transitions: Array, initial: Number)fn query(cycle: Number)_Stream
Section titled “_Stream”Stateful generative pattern functions.
stream() and markov() use script patterns (classes with query methods) and rand() (std/random).
fn new(initial: Note or Number or Array or Pattern, next_fn: Function)fn query(cycle: Number)choose
Section titled “choose”fn choose(seed: Number, array: Array)Deterministic element selection from an array. The same seed and array always returns the same element.
Parameters:
seed(Number) — integer seed valuearray(Array) — non-empty array to choose from
Returns: Any — the selected element of array
choose_true
Section titled “choose_true”fn choose_true(array: Array)True random element selection from an array (uses the system clock). Different each call.
Parameters:
array(Array) — non-empty array to choose from
Returns: Any — the selected element of array
choose_weighted
Section titled “choose_weighted”fn choose_weighted(seed: Number, array: Array, weights: Array)Deterministic weighted element selection from an array. The same seed, array, and weights always returns the same element.
Parameters:
seed(Number) — integer seed valuearray(Array) — non-empty array to choose fromweights(Array) — non-negative weights, same length asarray
Returns: Any — the selected element of array, biased by weights
markov
Section titled “markov”fn markov(num_states: Number, transitions: Array, initial: Number) -> PatternCreates a Markov chain pattern with cycle-seeded transitions.
Parameters:
num_states(Number) — number of states (positive integer)transitions(Array) — transition matrix (array of rows, each summing to 1)initial(Number) — initial state index (0-based)
Returns: Pattern — a pattern emitting the chain’s state, advanced once per cycle
off_cycle
Section titled “off_cycle”fn off_cycle() -> NULClear all per-cycle callbacks registered via on_cycle().
Returns: NUL — nothing
on_cycle
Section titled “on_cycle”fn on_cycle(callback: Function) -> NULRegister a per-cycle callback that runs on the interpreter thread. The callback receives the cycle number being prepared (not the current playing cycle). Multiple callbacks can be registered; they fire in registration order. Changes to the callback list (via on_cycle/off_cycle) within a callback take effect on the next cycle, not the current one.
Parameters:
callback(Function) — takes (cycle) and is called once per cycle
Returns: NUL — nothing
prime_cycles
Section titled “prime_cycles”fn prime_cycles() -> NULFire cycle callbacks once (for cycle 0) to set initial patterns. Called automatically by PLAY for internal clock. Call manually before external MIDI clock playback to ensure patterns are ready when the first cycles play.
Returns: NUL — nothing
fn rand(seed: Number) -> NumberDeterministic random number from a seed. The same seed always returns the same value.
Parameters:
seed(Number) — integer seed value
Returns: Number — a pseudo-random value in [0.0, 1.0)
rand_true
Section titled “rand_true”fn rand_true() -> NumberTrue random number using the system clock. Different each call.
Returns: Number — a pseudo-random value in [0.0, 1.0)
stream
Section titled “stream”fn stream(initial: Note or Number or Array or Pattern, next_fn: Function) -> PatternCreates a stateful stream pattern from an initial value and a next function. Each cycle’s output depends on the previous cycle’s state, enabling “walking” patterns like melodic random walks.
Parameters:
initial(Note | Number | Array | Pattern) — initial valuenext_fn(Function) — takes (prev, cycle) and returns the next value
Returns: Pattern — a pattern that evolves its state once per cycle