API Reference

This page is generated from the engine’s registered scripting surface joined with the documentation registry (src/scripting/docs.rs). A CI test fails whenever this page drifts from the engine. Regenerate with:

cargo run --bin gen_rhai_defs

Builder methods return their receiver and are chainable. Integer and float literals are interchangeable wherever both overloads are registered; the generated LSP definitions (rhai-defs/conchordal.d.rhai) list the exact overloads.

The surface is split into three tiers. Core API is the curated composing surface — it is enough for every curated sample. Mechanism Tuning adjusts the mechanisms behind the core verbs when a piece needs a behavior the core surface does not express. Research Controls exist for studying the instrument, not composing with it.

Types

Built-in Constants

Core API

The curated composing surface. These verbs are enough for every curated sample.

Materials

Materials are voice templates. A constructor returns a Material; builder methods refine it; place() turns it into living voices.

sine

sine() -> Material

Material with a pure sine body.

harmonic

harmonic() -> Material

Material with a harmonic-series body.

modal

modal() -> Material

Material with a resonator-based modal body; shape it with modes().

saw

saw() -> Material

Harmonic-body preset with brightness 0.85.

square

square() -> Material

Harmonic-body preset with brightness 0.65.

noise

noise() -> Material

Harmonic-body preset with brightness 1.0 and motion 1.0.

variant

variant(material) -> Material

Clone a material so the copy can be modified independently.

Placement

Placements decide where voices enter the frequency field. Constructors return a Placement; modifiers refine it before it is passed to place().

at

at(freq_hz) -> Placement

Place at a fixed frequency in Hz.

consonance

consonance(root_hz) -> Placement
consonance(min_hz, max_hz) -> Placement

Target consonance maxima. Density cloud by default; .peak() for the extremum. consonance(root) takes a harmonic window around a root (default 1x-4x, set multiples with range()); consonance(min, max) takes an absolute range. Default spacing is 1.0 ERB.

dissonance

dissonance(min_hz, max_hz) -> Placement

Target consonance minima (tension, clusters). Density cloud by default; .peak() for the most dissonant point.

edge

edge(min_hz, max_hz) -> Placement

Target the consonance/dissonance boundary (C near its midpoint). The metastable region between fusion and beating. Density band by default; .peak() for the point closest to the boundary.

gap

gap(min_hz, max_hz) -> Placement

Target empty registers (low subjective intensity); fill the room. Density cloud by default; .peak() for the emptiest position.

peak

peak()

Applies to: Placement.

Realize a field target as its deterministic extremum.

density

density()

Applies to: Placement.

Realize a field target as a stochastic cloud (the default).

tension

tension(degree)

Applies to: Placement.

Place at a metastable consonance below the strongest (degree 0..1). Consonance placement only. 0 targets the strongest consonance (resolved); higher targets a weaker, more tense step (target = L_max - degree*(L_max - L_min) over the range, in field_score). Pairs with peak() (nearest step, sharp) or density (a broader cloud around it).

random

random(min_hz, max_hz) -> Placement

Log-uniform random placement inside a frequency range.

line

line(start_hz, end_hz) -> Placement

Linear interpolation of positions between two frequencies.

count

count(n)

Applies to: Placement.

Number of voices to place (default 1).

range

range(min_mul, max_mul)

Applies to: Placement.

Multiplier range relative to the root; only valid on consonance(root).

spacing

spacing(min_erb)

Applies to: Placement.

Minimum ERB distance between placed voices; valid on field placements.

Timeline & Staging

Staging verbs commit voices and move script time. place() stages a draft Participant; wait()/flush() commit drafts; scopes release groups automatically.

place

place(material, placement) -> Participant

Stage a Participant at the current script time. Committed by the next wait() or flush(). Until then, builder methods on the returned Participant shape the initial spawn; afterwards, live-patchable methods update running voices. Calling place(participant, placement) on a draft re-places it (sets frequency, count, and strategy).

wait

wait(seconds)

Commit pending drafts, then advance the timeline cursor.

flush

flush()

Commit pending drafts without advancing time.

release

release(participant)

Release a live group; its voices enter their release phase and fade out.

section

section(name, callback)

Named scope; groups placed inside are released when the callback returns.

play

play(callback)
play(callback, arg1)
play(callback, arg1, arg2)
play(callback, arg1, arg2, arg3)
play(callback, [args])

Scoped callback execution with automatic group release. Accepts 0-3 positional arguments, or an array of arguments.

parallel

parallel(callbacks)

Run an array of closures on parallel timelines from the current cursor. Each branch starts at the current cursor; the cursor advances to the latest branch end.

seed

seed(value)

Set the random seed for reproducible scenarios.

Body & Timbre

Sound body parameters of a voice: level, spectrum, detuning, and envelope.

amp

amp(value)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Amplitude in 0.0-1.0.

freq

freq(hz)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Frequency lock in Hz; implies an anchored pitch (see anchor()).

brightness

brightness(value)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Spectral brightness in 0.0-1.0 (harmonic/modal bodies).

spread

spread(value)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Detuning spread.

unison

unison(count)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Number of unison detuning copies.

modes

modes(pattern)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Set the mode pattern of a modal body. See the Mode Patterns section for constructors and modifiers.

adsr

adsr(attack_sec, decay_sec, sustain_level, release_sec)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

ADSR amplitude envelope.

Phonation & Rhythm

When and how long a voice sounds. Tier 1 picks a region on the rhythm coupling continuum (metric(), entrained(), flow()); Tier 2 sets explicit when/duration; Tier 3 is expert tuning. Calls on the same axis are last-write-wins, and modifiers are remembered and applied when their matching preset is selected.

brain

brain(name)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Articulation brain: "entrain" (default), "seq", or "drone". entrain synchronizes with detected rhythms in the field, seq does fixed-duration note sequencing, drone sustains with slow frequency sway.

sustain

sustain()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Sustain phonation mode (default).

repeat

repeat()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Repeated/pulsed phonation mode.

metric

metric()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

High coupling to the shared emergent meter: deep attractor, stable pulse. Takes no rate argument: the tempo region is director-level terrain (temporal_basin).

entrained

entrained()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Medium coupling: synchronization emerges over time, still drifts.

flow

flow()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Near-zero coupling: free renewal process, non-metric texture.

entrainment

entrainment(strength)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Override coupling strength in 0-1 (free .. locked). Order-independent with presets: entrainment(0.8).metric() and metric().entrainment(0.8) are equivalent.

rhythm_role

rhythm_role(name)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Metrical job: "beat", "subdivision", "accent", or "texture". accent emits a stronger onset that drives the shared meter harder, so a recurring downbeat can seed an emergent measure.

microtiming

microtiming(amount)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Signed beat-phase offset in -0.5..0.5; 0.5 reads as syncopation.

cycles

cycles(n)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Duration of n rhythm cycles.

Pitch Movement

How a voice moves through the consonance field. seek_consonance() plus glide() is the curated surface; the rest tunes the hill-climb and peak-sampler mechanisms.

anchor

anchor()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Hold the voice at its pitch: an anchored voice never moves. Voices placed with at() or given freq() are anchored implicitly; use anchor() to hold strategy-placed voices (consonance(), dissonance(), …) at their settled position, or to state the intent explicitly.

seek_consonance

seek_consonance()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Free hill-climb movement toward better field positions, with glide defaults. How pitch decisions land is resolved at commit unless pitch_apply_mode() was called: sustained voices glide, re-attacking voices (pulse(), metric(), entrained(), flow()) snap at onsets.

glide

glide(tau_sec)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Pitch glide time constant in seconds.

Neighbor Awareness

How a voice perceives other voices and its own spectral footprint when evaluating the field.

avoid_neighbors

avoid_neighbors(strength)
avoid_neighbors(strength, sigma_cents)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Crowding repulsion from neighboring voices. With one argument the repulsion width uses the default; the two-argument form sets it explicitly in cents.

Lifecycle & Viability

Energy budget and survival. Viability makes field fit matter over time: consonance_viability() defines the consonance window and viability_rate() controls continuous recharge, with environment-relative scoring by default.

metabolism

metabolism(rate)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Energy consumption rate.

initial_energy

initial_energy(value)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Starting energy.

energy_cap

energy_cap(value)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Maximum energy after recharge/reward.

recharge_rate

recharge_rate(rate)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Energy gained per attack.

action_cost

action_cost(cost)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Energy cost per attack.

sustain_drive

sustain_drive(value)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Continuous drive level for sustained voices.

viability_rate

viability_rate(rate)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Continuous consonance-driven energy recharge rate.

consonance_viability

consonance_viability(low, high)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Consonance window used for viability scoring. Enables environment-relative scoring by default: a voice is evaluated against the field with its own footprint approximately removed (see viability_scope()).

dissonance_cost

dissonance_cost(cost)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Extra energy cost at low consonance.

Respawn

Population turnover. A respawn policy decides where replacements appear when voices die; capacity and acceptance thresholds shape ecology-scale behavior.

respawn_random

respawn_random()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Respawn at random locations.

respawn_hereditary

respawn_hereditary(sigma_oct)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Hereditary respawn with frequency variance in octaves.

respawn_consonance

respawn_consonance()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Respawn from consonance-biased parental peaks.

respawn_capacity

respawn_capacity(count)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Maintain population up to a capacity.

respawn_settle

respawn_settle(placement)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Placement used for replacements. Requires a strategy-bearing placement: consonance(), dissonance(), edge(), gap(), random(), or line() (not at()).

respawn_min_c_level

respawn_min_c_level(level)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Minimum consonance level for respawn acceptance.

respawn_background_death_rate

respawn_background_death_rate(rate)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Background turnover rate per second.

Mode Patterns

Frequency relationships for modal() bodies. Constructors return a ModePattern; modifiers are chainable. Landscape-aware patterns sample the live field.

harmonic_modes

harmonic_modes() -> ModePattern

Harmonic series: f, 2f, 3f, …

odd_modes

odd_modes() -> ModePattern

Odd harmonics: f, 3f, 5f, …

power_modes

power_modes(beta) -> ModePattern

Power law: f * n^beta.

stiff_string_modes

stiff_string_modes(stiffness) -> ModePattern

Stiffness-adjusted harmonics.

custom_modes

custom_modes(ratios) -> ModePattern

Custom frequency ratios from an array.

modal_table

modal_table(name) -> ModePattern

Named mode table lookup. Falls back to harmonic_modes() with a warning if the name is unknown.

landscape_density_modes

landscape_density_modes() -> ModePattern

Modes sampled from the live landscape density.

landscape_peaks_modes

landscape_peaks_modes() -> ModePattern

Modes sampled from live landscape peaks.

count

count(n)

Applies to: ModePattern.

Number of modes.

range

range(min_mul, max_mul)

Applies to: ModePattern.

Frequency range; only valid on landscape_*_modes().

spacing

spacing(min_erb)

Applies to: ModePattern.

Minimum ERB distance between modes; only valid on landscape_*_modes().

gamma

gamma(g)

Applies to: ModePattern.

Density sharpening exponent; only valid on landscape_density_modes().

jitter

jitter(cents)

Applies to: ModePattern.

Randomize mode frequencies by up to the given cents.

seed

seed(value)

Applies to: ModePattern.

Random seed for jittered patterns (>= 0).

Routing

Each voice contributes to two independent mono buses: the presentation bus (the work as heard) and the habitat bus (what the ecology senses through NSGT analysis). By default a voice feeds both.

send

send(bus)

Applies to: Material only.

Route the voice to specific buses; accepts a Bus or a BusSet. Material only. send(habitat_bus) makes a voice sensed by the ecology but absent from the presented sound; send(presentation_bus) is heard without perturbing the ecology; send(habitat_bus | presentation_bus) feeds both (the default).

Director & Global Parameters

Scene-global terrain shaping and research controls. Director verbs are soft priors: they shape the terrain and never schedule a beat or force a measure.

meter_stability

meter_stability(value)

Attractor depth in 0-1: how readily a pulse forms. A soft prior: it only deepens the basin for a real periodicity; it never fabricates a beat from non-metric input.

temporal_basin

temporal_basin(min_hz, max_hz)

Tempo region the emergent beat gravitates toward. The time-axis analogue of consonance(min, max): it shapes the terrain, does not place a beat, and never forces a measure.

Experimental

Candidate core verbs under audition: composing surface by intent, but with research-grade stability until validated.

Empty right now.

Mechanism Tuning

Fine-grained control over the mechanisms behind the core verbs. Defaults are calibrated; reach for these when a piece needs a specific behavior the core surface does not express.

Placement

reject_targets

reject_targets(anchor_hz, targets_st, exclusion_st, max_tries)

Applies to: Placement.

Reject sampled positions near specified semitone targets. targets_st is an array of semitone offsets from anchor_hz, exclusion_st is the exclusion zone width in semitones, and max_tries is the retry limit. Wraps any strategy-bearing placement (consonance(), dissonance(), random(), line(), …).

Phonation & Rhythm

once

once()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Single trigger.

pulse

pulse(rate_hz)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Pulse at an explicit rate in Hz.

while_alive

while_alive()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Hold/sustain until release.

adaptive_duration

adaptive_duration()

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Duration follows field support.

pulse_lock

pulse_lock(depth)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Low-level pulse phase weighting in 0-1.

social

social(coupling)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Social coupling for entrained() or pulse(), in 0-1.

duration_range

duration_range(min_cycles, max_cycles)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Adaptive duration range in rhythm cycles.

duration_curve

duration_curve(k, x0)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Adaptive duration curve parameters.

shorten_on_drop

shorten_on_drop(gain)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Shorten adaptive duration when field support drops.

rhythm_freq

rhythm_freq(freq_hz)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Internal theta/rhythm oscillator frequency.

rhythm_coupling_vitality

rhythm_coupling_vitality(lambda_v, v_floor)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Vitality-modulated rhythm coupling.

rhythm_reward

rhythm_reward(rho_t, metric)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

Energy reward for timing fit; metric is "attack_phase_match" or "none".

Pitch Movement

pitch_smooth

pitch_smooth(tau_sec)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Pitch smoothing time constant in seconds.

pitch_apply_mode

pitch_apply_mode(name)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

"gate_snap" or "glide": override how pitch decisions are applied. Without an explicit call, moving voices resolve this at commit from their phonation: sustained voices glide, re-attacking voices snap at onsets.

landscape_weight

landscape_weight(value)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Weight of the landscape objective.

temperature

temperature(value)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Search temperature shared by both pitch cores: 0 settles greedily, higher is more exploratory. The single stochastic-search knob. At 0 the hill-climb is greedy (move only on a clear improvement, otherwise stay) and the peak sampler takes the argmax candidate. Higher values let the hill-climb accept downhill moves (Metropolis) and soften the peak sampler’s candidate choice.

neighbor_step_cents

neighbor_step_cents(value)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Step size for neighbor exploration in cents.

move_cost

move_cost(coeff)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Cost multiplier for pitch changes.

move_cost_exp

move_cost_exp(exp)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Exponent for the move cost.

proposal_interval

proposal_interval(seconds)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Proposal generation interval in seconds.

tessitura_gravity

tessitura_gravity(value)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Gravity toward the tessitura center.

window_cents

window_cents(width)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Peak-sampler search window width in cents.

top_k

top_k(count)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Number of top candidates kept by the peak sampler.

sigma_cents

sigma_cents(spread)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Gaussian spread of the peak sampler in cents.

random_candidates

random_candidates(count)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Number of random candidates considered.

global_peaks

global_peaks(count)
global_peaks(count, min_sep_cents)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Global field peaks as movement candidates, with optional minimum separation.

ratio_candidates

ratio_candidates(count)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Ratio-based movement candidates; 0 disables.

Neighbor Awareness

crowding_target

crowding_target(same_visible, other_visible)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Which voices are visible to crowding: own group, other groups (booleans).

leave_self_out

leave_self_out(enabled)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Subtract the voice’s own spectral contribution when evaluating the field.

leave_self_out_harmonics

leave_self_out_harmonics(count)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

Number of harmonics used for approximate self-subtraction.

Lifecycle & Viability

viability_scope

viability_scope(name)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

"environment" (default) or "total" viability scoring scope. Use "total" only when the selection question should include the voice’s own contribution.

Director & Global Parameters

set_roughness_k

set_roughness_k(value)

Roughness tolerance of the landscape.

set_global_coupling

set_global_coupling(value)

Voice interaction strength.

Research Controls

For studying the instrument, not composing with it. Normal composing never touches this tier, and it has the weakest stability guarantee: entries may change or disappear as their research questions settle.

Pitch Movement

pitch_core

pitch_core(name)

Applies to: Material and Participant. Draft-only: ignored with a warning on a live Participant.

"hill_climb" or "peak_sampler". Research control.

move_cost_time_scale

move_cost_time_scale(name)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

"legacy"/"integration_window" or "proposal"/"proposal_interval".

Neighbor Awareness

leave_self_out_mode

leave_self_out_mode(name)

Applies to: Material and Participant. Live-patchable: updates running voices on a live Participant.

"approx"/"approx_harmonics" or "exact"/"exact_scan".

Lifecycle & Viability

selection_approx_loo

selection_approx_loo(enabled)

Applies to: Material only.

Override environment-relative viability scoring; research/reference control. Material only. Use only for older reference assays that need the previous implementation-level control.

Director & Global Parameters

set_pitch_objective

set_pitch_objective(name)

"consonance"/"positive" or "dissonance"/"negative". Research control.

set_control_update_mode

set_control_update_mode(name)

"snapshot_phased"/"snapshot" (default) or "sequential_rotating"/"sequential". Research control.

set_scaffold_off

set_scaffold_off()

Disable the external rhythm scaffold. Scaffolds are external comparison controls for demos and assays, not the rhythm-composition abstraction.

set_scaffold_shared

set_scaffold_shared(freq_hz)

Shared external scaffold pulse.

set_scaffold_scrambled

set_scaffold_scrambled(freq_hz, seed)

Per-voice scrambled scaffold pulse.