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 four tiers. Core API is the curated composing surface — it is enough for every curated sample. Experimental contains candidate Core verbs under audition. 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.

Population Specs

A PopulationSpec defines founder voice traits and population-level lifecycle rules. Constructors return a PopulationSpec; builder methods refine it; place() creates a Population.

sine

sine() -> PopulationSpec

PopulationSpec whose founder voices use a pure sine body.

harmonic

harmonic() -> PopulationSpec

PopulationSpec whose founder voices use a harmonic-series body.

modal

modal() -> PopulationSpec

PopulationSpec whose founder voices use a resonator-based modal body; shape it with modes().

saw

saw() -> PopulationSpec

Harmonic-body preset with brightness 0.85.

square

square() -> PopulationSpec

Harmonic-body preset with brightness 0.65.

noise

noise() -> PopulationSpec

Harmonic-body preset with full brightness and maximal spectral motion (jitter).

variant

variant(population_spec) -> PopulationSpec

Clone a PopulationSpec 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, or start an explicitly moving voice here. With explicit seek_consonance() intent and a final free pitch mode, at(hz) sets only the initial position, using the same placement as line(hz, hz) and preserving the founder count. Otherwise it locks pitch as before. A later freq() or anchor() restores the lock; a later seek_consonance() restores movement. This specifies the initial body pitch, not a guaranteed first audible pitch or a promise that movement will occur.

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.

Bias Consonance placement toward a field-score step below the in-range maximum (degree 0..1). Consonance placement only. 0 leaves ordinary Consonance placement unchanged: peak() selects the strongest peak, while the default density remains the ordinary Consonance cloud. Higher values target 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.

Positive number of founder 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 & Populations

place() creates a Population at the current script time. wait() advances the cursor; flush() emits pending live patches without advancing it; scopes release their populations automatically.

place

place(population_spec, placement) -> Population

Create a Population at the current script time. place() is the sole Population boundary. Configure initial-only properties on the PopulationSpec first; the returned Population exposes only live patches and release.

wait

wait(seconds)

Emit pending live patches, then advance the timeline cursor.

flush

flush()

Emit pending live patches without advancing time.

release

release(population)

Close a live Population; its voices enter their release phase and fade out. Release is terminal at the scripting surface: later live patches on the same Population are ignored.

section

section(name, callback)

Named scope; populations 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 population 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.

temporal_mode

temporal_mode(name)

Select off or observe for new temporal cognition before playback. Declare once at top level before events or time advance. Default off preserves existing behavior. Observe currently tracks ordered NSGT evidence on both buses; relation inference remains unknown and no new action pressure is applied. Participate is rejected until implemented and calibrated. Run a new scenario to change mode.

Body & Timbre

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

amp

amp(value)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Amplitude in 0.0-1.0.

freq

freq(hz)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

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

brightness

brightness(value)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

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

spread

spread(value)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Detuning spread.

unison

unison(count)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Number of unison detuning copies.

modes

modes(pattern)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

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: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

ADSR amplitude envelope.

Phonation & Rhythm

When and how long a voice sounds. Tier 1 picks a region on the rhythm timing presets (metric(), entrained(), steady(), 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: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Articulation life: "entrain" (default), "seq", or "drone". Selects how the voice lives while sounding; orthogonal to the rhythm timing presets (metric/entrained/steady/flow). entrain is a living articulation whose vitality responds to consonance and rhythm fit, subject to the metabolism economy. seq holds for a fixed lifetime, ignoring the field and metabolism. drone is undying, sustaining forever with a slow sway – useful as terrain material.

sustain

sustain()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Sustain phonation mode (default). Explicit sustain() plus entrained(), steady() or flow(), in either order, retains a Tone while the Voice considers participation. With glide (the omitted mode), clock attacks use current body pitch; entrained/flow can offer one legal adoption-time candidate with unchanged costs, otherwise it glides. Steady evaluates only its own due time and never adds an adoption-time candidate. Explicit gate_snap on free pitch holds the latest adopted target until a sounded clock opportunity, then jumps and attacks; wait/skip retains pitch and pending target, and no adoption-time candidate is offered. Rearticulate with a positive rearticulate_above boundary glides small adoptions, cancelling older pending pitch, and defers large ones to a sounded opportunity. Zero or omission matches gate_snap; clock attacks are not filtered by the boundary. Implicit WhileAlive and while_alive() alone do not enable the combination. Pulse and repeat retain their last-write-wins rule. Explicit sustain() plus metric(), in either order, keeps a live Tone and uses the existing coupling-clock integer crossings as opportunities. For free-pitch gate_snap/rearticulate, omitted tie means tie(1): beats with a pending adopted target attack, while other beats extend the living Tone. Explicit tie(0) re-attacks every legal crossing; explicit intermediate values are unchanged. Fixed pitch and glide still re-attack at each crossing. Omitted tie for sustained entrained/steady/flow remains zero, where participation can skip opportunities by cost. No adoption-time opportunity or participation cost policy is added. The shared beat is confirmed from sound; before confirmation the clock free-runs from its existing basin-centered rate and independent phase. It does not place an external beat. Fixed pitch is supported as in sustained participation; tie and persistence remain free-pitch controls. With rest(), finite duration and sustained participation are retained independently of builder order; every sounded note releases at that duration and waits for its tails before the rest. tie(p) can extend a living Tone at pending-free gate_snap/rearticulate opportunities; it leaves pending-target attacks intact.

rest

rest()
rest(periods)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Release each finite participation note, then leave a rest after all its tails finish. Requires explicit sustain() plus metric(), entrained(), steady() or flow(), and an explicit finite duration from cycles() or adaptive_duration(). These choices are retained independently of builder order. The normal Off releases the note without cutting its tails. After every Tone of the same source ID and generation has actually finished, wait periods times the intrinsic bodily period measured at that completion; rest() uses one period. For entrained/steady/flow, intrinsic_rate(hz) changes this period and therefore the rest in seconds, independently of cadence adaptation; metric retains its existing basin-centered intrinsic rate and ignores intrinsic_rate. With a known period, rest(0) waits only for tail completion. Unknown periods and unfinished tails keep waiting, without a fallback or timeout. Finite nonnegative periods have no upper cap; negative or nonfinite values sanitize to zero. Expiry permits sounding again but never forces an onset. Participation costs/candidates/skip are unchanged; metric keeps advancing its crossings during the gap and never replays suppressed ones. GateSnap retains the latest adopted target through sounding, tails and rest, consuming it at the next sounded opportunity. Glide does not update released tails. Rearticulate processes adoptions during tails and rest: small ones cancel pending pitch and glide the body, large ones defer the latest target, using the last actual onset as reference until the next sounded opportunity. Released tails never move. Missing finite duration and other timing forms fail at final placement before writes; all three pitch application modes are available; explicit while_alive() clears finite intent. Initial-only, like cycles() and duration_range(). Replacement Voices inherit controls, starting with fresh performance state. Without rest(), existing behavior is unchanged. Every note in this form has a finite end; it does not select sustain versus release per note. tie(p) cannot block a legal onset without a Tone after the gap, and never delays finite Off or tail completion.

repeat

repeat()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Repeated/pulsed phonation mode.

metric

metric()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Confidence-weighted rate and phase attraction to the acoustically confirmed beat. Takes no rate argument. With temporal_basin, its intrinsic starting rate is the sanitized band center; without a basin it is 2 Hz. This initial rate is independent of meter_stability. Every metric Population created by place or create reads the scene’s final basin, including calls after wait; repeated basin declarations use the last value, not timed changes. Initial phases remain independent. The omitted entrainment is 0.95. Beat confidence weights attraction of both effective rate and phase, with microtiming setting the beat-phase offset. Beat confirmation itself, exact phase coincidence and independent noninteger tempo relations are not guaranteed. Each clock crossing is an onset opportunity; lifecycle, phonation gates, rest and articulation determine whether an On is emitted. Attraction follows positive confidence in a beat confirmed from sound; the starting rate is not a confirmed beat. Respawn uses the Population template, not the parent’s current clock rate. entrained, steady, flow, and explicit pulse(rate_hz) are outside this initialization rule. Explicit sustain() plus metric(), in either builder order, retains a Tone and uses every coupling-clock integer crossing as an onset opportunity. For free-pitch gate_snap/rearticulate, omitted tie means tie(1): beats with a pending adopted target attack, while other beats extend the living Tone. Explicit tie(0) re-attacks every legal crossing; explicit intermediate values are unchanged. Fixed pitch and glide still re-attack at each legal crossing. Omitted tie for sustained entrained/steady/flow remains zero, where participation can skip opportunities by cost. Glide, deferred pitch, movement boundary, persistence and finite-duration rest share the sustained articulation resolver. Synchronization has no participation cost skip or planned waiting. Before acoustic beat confirmation it free-runs; this preset does not place a beat from outside.

entrained

entrained()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Adaptive acoustic participation with a lifetime-fixed bodily scale. Uses past habitat audio and its own rendered sound. Keeps the intrinsic bodily rate fixed during a Voice’s lifetime; it defaults to 2 Hz and intrinsic_rate(hz) sets its creation value. The participation period can adapt to supported recurrence weighted by proximity to that scale. Its omitted entrainment is 0.5 and controls period adaptation and acoustic timing costs. Costs compare sounding near due, waiting up to one participation period and skipping the event. Adaptation preserves the remaining fraction of a future uncommitted cycle; new acoustic context does not move a committed onset time. Only emitted onsets create pending context-memory updates, applied when their matching actual audio is observed. Waiting, skipping and unexecuted plans do not create an onset experience. Equal onset intervals, permanently different onset rates between Voices and alignment with a shared beat phase are not guaranteed. With explicit sustain(), in either builder order, sounding re-attacks the current body pitch by default; explicit gate_snap/rearticulate may use tie(p) to extend a living Tone without pending pitch. Waiting or skipping retains the ongoing Tone. Omitted pitch application resolves to glide. With rest(), an explicit finite duration ends each note before the tail-completion rest. Without explicit sustain(), finite gated phonation is unchanged.

steady

steady()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Fixed private due times; acoustic context selects sound or skip. A separate non-flow participation preset. It keeps its intrinsic period fixed and evaluates only its own due time, without adapting or moving that time toward another Voice or a shared beat. Heard acoustic context and executed-onset memory affect only whether an opportunity sounds or is skipped; pitch and the number of onsets are not guaranteed. The omitted coupling is 0.5, as for entrained(); entrainment(strength) keeps the same acoustic-context meaning. intrinsic_rate(hz) sets the creation pace, otherwise 2 Hz. Later sounded onsets occupy the private due-time grid, subject to sample rounding, omissions and execution constraints. Missed or illegal opportunities advance by whole intrinsic periods without shifting that grid. No cost term or weight is changed. The current arrival cost is excluded from the skip test, so with one candidate it cannot change sound versus skip. Timing presets follow the existing last-preset-wins rule. With sustain(), in either builder order, the first legal Hold On remains immediate and a skipped opportunity keeps the ongoing Tone. GateSnap, Glide, Rearticulate, rearticulate_above, tie (omitted 0), articulation_persistence, finite duration and rest retain the participation contracts. Replacement Voices inherit the Population template’s policy and start with fresh phase, due, plans and memory.

flow

flow()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Irregular bodily renewal with acoustic timing choices. Keeps its intrinsic renewal scale fixed during a Voice’s lifetime. Renewal draws produce irregular intervals; acoustic costs let the policy choose another time, wait or skip. The omitted entrainment is 0.05; it weights those acoustic costs without adapting the renewal scale. A regular onset sequence, a beat and an exact mean onset interval equal to the intrinsic period are not guaranteed. This is a separate irregular preset, not steady() with renewal added. Unlike entrained(), it does not adapt that scale to an observed recurrence. intrinsic_rate(hz) sets its creation value, otherwise 2 Hz. Hold lengths also use the intrinsic period. Renewal intervals retain their existing 0.035..=4 second limits, so extreme rates do not produce proportionally scaled intervals. With explicit sustain(), in either builder order, sounding re-attacks the current body pitch by default; explicit gate_snap/rearticulate may use tie(p) to extend a living Tone without pending pitch. Waiting or skipping retains the ongoing Tone. Omitted pitch application resolves to glide. With rest(), an explicit finite duration ends each note before the tail-completion rest. Without explicit sustain(), finite gated phonation is unchanged.

intrinsic_rate

intrinsic_rate(hz)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Set the intrinsic bodily rate at creation for entrained()/steady()/flow(), in Hz. Sets the Population’s founder Voices’ bodily scale, not an onset-interval command or a shared beat. The intrinsic period is 1/hz and remains fixed during life; entrained() adapts its participation period to heard recurrence, steady() keeps fixed private opportunities, and flow() retains an irregular renewal scale. Sounding, waiting and omission still use the existing policy. This same bodily period sets cycles(), duration_range(), rest(periods) and the representative hold used for overlap prediction, so note lengths and rests in seconds change together; flow retains its threefold hold multiplier. Omission preserves the existing 2 Hz path. Initial-only: put it before place() or create(), in either order with entrained()/steady()/flow(). Replacements read the Population template and start with fresh phase, due, plan and policy state; they do not inherit a parent’s adapted period. On the final entrained()/steady()/flow() specification, nonfinite values or values outside 0.01..=200 Hz are script errors before placement. These are execution protection limits, not a musically recommended range. Other final timing forms, including metric(), pulse(), repeat() and once(), warn and ignore the modifier even if its value is invalid. Flow renewal intervals separately retain their existing 0.035..=4 second limits, so extreme rates do not imply proportionally scaled onset intervals. Distinct from rhythm_freq(), the Entrain articulation core oscillator, and proposal_interval(), the pitch proposal interval.

entrainment

entrainment(strength)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Preset-specific acoustic timing influence or beat-rate and phase attraction. Order-independent with presets: entrainment(0.8).metric() and metric().entrainment(0.8) are equivalent. Within a selected preset it changes the timing influence, not the preset. For entrained(), it weights acoustic period adaptation and timing costs; for flow(), acoustic timing costs while the renewal scale stays fixed; for steady(), sound-or-skip costs without adapting the period or moving due. For metric(), beat confidence weights its attraction of both effective rate and phase toward the confirmed beat. Omitted values are 0.95 for metric(), 0.5 for entrained()/steady() and 0.05 for flow(). Zero removes these acoustic timing influences; flow still draws irregular renewal intervals. Without an already coupled timing specification, a bare call initializes Coupled timing with its existing defaults.

rhythm_role

rhythm_role(name)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

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.

measure_accent

measure_accent(amount)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Weak onset emphasis following the emergent measure, amount 0-1 (default 0). Scales onset strength by 1 + 0.35 * amount * measure confidence * cos(measure phase). Zero phase follows observed accents. With no detected measure, strength stays unchanged. Does not schedule onsets or impose a grouping. Order-independent with metric/entrained/steady/flow presets.

microtiming

microtiming(amount)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Signed beat-phase offset for metric timing, in -0.5..0.5. A value of 0.5 offsets the synchronized target by half a beat. Does not place entrained/steady/flow participants at fixed offsets.

cycles

cycles(n)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Duration of n rhythm cycles. For entrained/steady/flow, duration uses the intrinsic bodily period set by intrinsic_rate(hz), or 2 Hz when omitted, independently of acoustic cadence adaptation. Metric timing uses its effective beat period. Flow retains its threefold hold multiplier. With rest(), this finite duration is retained independently of sustain() and the participation preset, and each sounded note releases at its scheduled end.

tie

tie(p)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Extend a living Tone with probability p at an opportunity without pending pitch. The sustained metric combination uses shared-beat crossings, including crossings without adoptions; before acoustic confirmation it free-runs. Unlike participation, synchronization has no cost skip or committed plan. Initial-only composer parameter for free-pitch sustain() plus metric()/entrained()/steady()/flow() with gate_snap or rearticulate, including a zero boundary. At execution of a selected legal opportunity, pending pitch attacks as before; without pending pitch, a living Tone extends with probability p and re-attacks current body pitch with 1-p. No living Tone means a legal initial or post-rest onset is never withheld. Omission resolves before placement to one for free-pitch sustained metric and zero for sustained entrained/steady/flow, independent of builder order at place/create. Explicit zero bypasses tie state and random draws; one always extends eligible Tones without drawing. Fixed pitch and glide still re-attack at each metric crossing. The omitted metric probability is retained while glide suspends its use, so entering gate_snap/rearticulate live applies the same default without a new setter. Intermediate values use a dedicated individual random stream, once per eligible executed opportunity, not waiting hops; existing pitch, participation, body and articulation_persistence streams are untouched. Extension creates no new Tone, onset metabolism or onset-context learning, and consumes the opportunity without cost-skip learning or later replay. Small boundary-limited glides are eligible too: pending-free does not mean exactly equal pitch. GateSnap retains small and zero-distance adoptions as pending, so those still attack. This is not an overall legato amount: attacks become a thinned opportunity sequence; choices are per opportunity, not phrases or heard boundaries. With articulation_persistence, Connect vetoes first without a tie draw, while Base applies tie only without pending pitch; extension does not change the policy or its proposals. Finite Off, rest, tails/gaps, release, death and removal take priority. Live glide suspends tie; returning to an applicable mode resumes it, without an attack from switching alone. Finite inputs clamp to 0..1; positive infinity becomes one, negative infinity and NaN become zero. Unsupported explicit tie settings warn and ignore the modifier; omission emits no ignored-tie warning. Resolution is independent of builder order at place/create. Replacements inherit the template probability, not the parent’s RNG position, pending target or actual-onset memory. There is no live tie setter or alias. Example intermediate values illustrate composition, not recommended settings.

articulation_persistence

articulation_persistence(p)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Retain a Voice’s private articulation policy across pitch adoptions and sustained clock opportunities. The sustained metric combination uses shared-beat crossings, including crossings without adoptions; before acoustic confirmation it free-runs. Unlike participation, synchronization has no cost skip or committed plan. Initial-only, for free-pitch sustain() plus metric()/entrained()/steady()/flow(), rearticulate and a positive rearticulate_above boundary. The private policy starts in Base (the existing boundary and participation behavior); Connect glides all adoptions while a Tone lives and intentionally withholds sounded opportunities to extend it. Small adoptions and participation cost skips propose Connect; large adoptions and newly selected sounded opportunities propose Base. For 0 < p < 1, only an opposing proposal draws from a dedicated individual random stream: retain with probability p, switch with 1-p. A planned opportunity freezes its decision until execution; waiting hops do not draw again. Entering Connect cancels pending pitch but retains the last actual onset; cancelled adoptions never replay. Intentional withholding is distinct from cost skip and creates no Tone, onset metabolism or onset-context learning. Rest, finite Off, tails/gaps and lifecycle constraints take priority; Connect cannot block a legal onset when no Tone lives. Zero (the default) and one bypass the private state and RNG and retain the existing path. Finite values clamp to 0..1, positive infinity becomes one, negative infinity and NaN become zero. Unsupported final specs warn and ignore the value, independent of builder order. Replacements inherit the template parameter, not policy, RNG, pending decisions or last-onset memory, and start in Base. Live mode changes reset Base; the same mode and boundary-only changes retain the policy. A zero boundary suspends the private path. This is policy inertia, not a legato proportion: increasing p need not monotonically increase Connect time or reduce attacks. Retention is measured in existing events, not seconds or beats, and is not tied to heard cadence, contour, rests or phrase boundaries. Example values are comparisons, not recommendations. With tie(p), Connect vetoes first without a tie trial; Base uses tie only without pending pitch. Tie never changes policy proposals or retention.

Pitch Movement

How a voice moves through the consonance field. seek_consonance(), glide(), and temperature() (movement tension) form the curated surface; the rest tunes the hill-climb and peak-sampler mechanisms.

anchor

anchor()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Hold the voice at its pitch: an anchored voice never moves. at() anchors implicitly unless the final spec explicitly seeks consonance and remains free; in that case it sets only the initial position. freq() still sets an anchored pitch. A later anchor() or freq() overrides movement, while a later seek_consonance() restores it. 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: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Free hill-climb movement toward better field positions, with glide defaults. With this explicit intent and a final free pitch mode, at(hz) sets only the initial position. A later freq() or anchor() restores the lock; calling seek_consonance() after either restores movement. How pitch decisions land is resolved at placement unless pitch_apply_mode() was called: sustained voices glide, re-attacking voices (pulse(), metric(), entrained(), steady(), flow()) snap at onsets.

glide

glide(tau_sec)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Pitch glide time constant in seconds. Sets the sliding time constant, without changing pitch apply mode. It controls glide mode and movement at or below a positive rearticulate_above boundary; gate_snap does not slide.

rearticulate_above

rearticulate_above(cents)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Choose sliding or rearticulation by distance from the last sounded onset pitch. For free-pitch Hold without coupled opportunities, a positive boundary measures net displacement from the last actual ToneSpec onset to the adopted target: strictly above attacks, at or below glides with glide(tau). Selection persists until the next adoption. Earlier legal onsets in the same output hop provide the reference; cancelled requests do not replace the last actual onset. Exact Log2Space centers use bin-distance in cents, otherwise continuous log2 distance is used without rounding or epsilon. Without sustained coupled timing, zero retains every-adoption rearticulation. With explicit sustain plus metric/entrained/steady/flow, a small adoption cancels older pending pitch and glides immediately; a large adoption stops the glide, holds body pitch and defers one latest target to the next sounded opportunity. At a sounded opportunity without pending pitch, explicit tie(0) attacks at current body pitch; omission extends in free-pitch sustained metric and retains attacks in entrained/steady/flow. Other tie(p) values may extend its living Tone; either attack updates the reference. Waiting/skipping retain sound and pending pitch while existing glides continue. Zero or omission matches GateSnap, including zero-distance adoptions. The boundary does not suppress clock attacks and adds no adoption-time candidate. Negative or nonfinite values become zero; no upper limit is imposed. A live boundary change emits no attack and applies at the next adoption. Outside rearticulate, a call warns and is ignored. Builder order is independent at placement; replacement Voices inherit the boundary but not the onset-pitch memory. The composer chooses the boundary; 50 or 100 cents are examples, not recommendations. Initial-only articulation_persistence(p) can retain a private Base/Connect policy within the positive-boundary sustained-participation form; the boundary alone never suppresses clock attacks.

temperature

temperature(value)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

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. Musically the movement-tension dial; its placement twin is tension().

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: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

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

Time-domain survival and recovery. endurance() states nominal zero-fit lifetime; recovery() states full-scale continuous recovery time. consonance_viability() defines the recovery window, with environment-relative scoring by default.

endurance

endurance(seconds)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Nominal survival time at zero field fit, excluding the release tail. Energy is normalized to 0-1. The runtime drain rate is derived at spawn; actual lifetime varies with field fit, attacks, recovery, and release time.

recovery

recovery(seconds)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Time to refill normalized energy from empty at full viability. Optional. If omitted, continuous recovery is disabled. This does not govern the separate per-attack economy.

attack_cost_fraction

attack_cost_fraction(value)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Fraction of normalized energy spent by a full-strength attack.

attack_recharge_fraction

attack_recharge_fraction(value)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Maximum normalized energy restored by a fully consonant attack.

sustain_drive

sustain_drive(value)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Continuous drive level for sustained voices.

consonance_viability

consonance_viability(low, high)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

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_penalty

dissonance_penalty(value)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

How strongly good field fit extends life beyond zero-fit endurance. The zero-fit endurance remains fixed; the penalty changes how much longer a well-fit voice survives.

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: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Respawn without parent inheritance. Candidates come from the Population’s original Placement and, when set, respawn_settle() adds alternative candidates. The current scene score weights the final choice, so this is not uniform random placement.

respawn_hereditary

respawn_hereditary(sigma_oct)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Respawn near an energy-weighted living parent, with frequency variance in octaves. Candidates share one selected parent. The candidate with the highest current Consonance Field level is used.

respawn_consonance

respawn_consonance()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Respawn from high field-score peaks, biased around an energy-weighted living parent. When living members exist, one parent is selected by energy. Candidate peaks come from the current Consonance Field and are weighted by scene score and their relation to the parent; without a usable peak, the policy falls back to the parent or original Placement.

respawn_capacity

respawn_capacity(count)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Maximum number of living members in the Population. Defaults to the number of founder Voices created by place() and cannot be lower than that founder count.

respawn_settle

respawn_settle(placement)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Add a Placement source to the replacement candidate pool. The policy’s own baseline still supplies one candidate; this Placement supplies the remaining alternatives. 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: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Minimum consonance level for respawn acceptance.

respawn_background_death_rate

respawn_background_death_rate(rate)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Background turnover rate per second.

Mode Patterns

Frequency relationships for modal() bodies. Constructors return a ModePattern; modifiers are chainable. Landscape-aware patterns deterministically select supported positions from 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 selected from the strongest live landscape density-mass positions. Selection is deterministic: after each strongest position is chosen, nearby weights are suppressed according to spacing(). Falls back to harmonic modes when live landscape data yields no usable position.

landscape_peaks_modes

landscape_peaks_modes() -> ModePattern

Modes selected from the strongest local peaks of the live Consonance Field level. Selection is deterministic and enforces the ERB separation from spacing(). Falls back to harmonic modes when live landscape data yields no usable peak.

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: PopulationSpec only.

Route the voice to specific buses; accepts a Bus or a BusSet. PopulationSpec 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. Default 0 (neutral). A soft prior: it only deepens the basin for a real periodicity; it never fabricates a beat from non-metric input. It also weights the tempo preference toward the center of temporal_basin, or 2 Hz in the default beat band. The preference weight equals the depth, clamped to [0,1]; it is part of the modeled listener’s enculturation. Higher depth favors an in-band tactus nearer that center, including an integer subdivision reading of faster input.

temporal_basin

temporal_basin(min_hz, max_hz)

Set the beat’s tempo band and metric Voices’ initial rate. The time-axis analogue of consonance(min, max): it seeds the beat at the band center and confines tempo adaptation to the band. At meter_stability(0), the band adds no center preference or restoring pull; with higher stability, candidate preference and confidence-weighted center restoring grow with the depth. The same sanitized center sets the intrinsic starting rate of metric() Voices, even at stability 0; without a basin that rate is 2 Hz. entrained()/steady()/flow() retain their separate bodily rate, 2 Hz unless intrinsic_rate(hz) is supplied, and explicit pulse(rate_hz) retains its rate. This is one scene initial condition: the last basin declaration applies to every metric Population, regardless of its position before or after place, create, or wait. It is not an in-performance change. Independent Voice phases and acoustic confirmation remain required; this does not place a beat or force a measure.

Experimental

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

Phonation & Rhythm

phonate_when_viable

phonate_when_viable()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Withhold the first onset until perceived consonance is viable. Silently settles into the field until consonance reaches the low bound of the voice’s consonance-viability window (consonance_viability(), or always-viable if that window was never set), then phonates normally and never re-gates. A voice that never settles dies unheard and the respawn policy replaces it – there is no timeout parameter, the energy economy is the timeout.

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.

Phonation & Rhythm

once

once()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Single trigger.

pulse

pulse(rate_hz)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Pulse at an explicit rate in Hz.

while_alive

while_alive()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Hold/sustain until release. Explicit while_alive() clears any finite duration retained for rest(); placement with rest() then fails unless a later finite duration is supplied.

adaptive_duration

adaptive_duration()

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Duration follows field support. With rest(), retain this finite duration independently of sustain() and entrained()/steady()/flow(), in any builder order. duration_range(), duration_curve() and shorten_on_drop() tune the retained rule.

pulse_lock

pulse_lock(depth)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Low-level pulse phase weighting in 0-1.

social

social(coupling)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

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

duration_range

duration_range(min_cycles, max_cycles)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Adaptive duration range in rhythm cycles. Also tunes the finite adaptive duration retained for rest(). For entrained()/steady()/flow(), cycles use the bodily period set by intrinsic_rate(hz), independently of cadence adaptation; changing the bodily rate changes this duration in seconds. Initial-only, like cycles() and rest().

duration_curve

duration_curve(k, x0)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Adaptive duration curve parameters.

shorten_on_drop

shorten_on_drop(gain)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Shorten adaptive duration when field support drops.

rhythm_freq

rhythm_freq(freq_hz)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Internal theta/rhythm oscillator frequency. Sets the Entrain articulation core oscillator; it does not set the entrained()/steady()/flow() participation scale. Use intrinsic_rate(hz) for that bodily rate. This control’s existing meaning is unchanged.

rhythm_coupling_vitality

rhythm_coupling_vitality(lambda_v, v_floor)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

Vitality-modulated rhythm coupling.

rhythm_reward

rhythm_reward(rho_t, metric)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

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

Pitch Movement

pitch_smooth

pitch_smooth(tau_sec)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Pitch smoothing time constant in seconds.

pitch_apply_mode

pitch_apply_mode(name)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

"gate_snap", "glide" or "rearticulate": choose how adopted pitch targets are applied. The sustained metric combination uses shared-beat crossings, including crossings without adoptions; before acoustic confirmation it free-runs. Unlike participation, synchronization has no cost skip or committed plan. Choose gate_snap, glide or rearticulate. Without an explicit call, moving sustained voices resolve to glide and Gated voices to gate_snap. Free-pitch Hold without coupled opportunities rearticulate couples each changed adopted target to an attack at its sample, releasing the old Tone; a positive rearticulate_above(cents) instead glides at or below the distance boundary from the last actual onset. Rejected or unchanged targets and proposal-free updates cause no attack. Glide(tau) controls sliding, including below that boundary. With explicit sustain() plus metric()/entrained()/steady()/flow(), the omitted mode is glide: clock attacks use current body pitch and unselected movement glides. Explicit gate_snap on free pitch holds one latest adopted target for the next sounded opportunity, jumps there and attacks; wait/skip retains pitch and pending state, and no extra adoption-time candidate is offered. Without a pending target the clock re-attacks the current pitch unless tie(p) extends the living Tone. With explicit sustained participation, rearticulate measures each adopted target from the last actual onset using the current Log2Space: at or below a positive boundary it cancels old pending pitch and glides immediately; above it, it stops the glide and holds one latest target for the next sounded opportunity. Without pending pitch, omitted tie extends the living Tone in sustained metric; sustained entrained/steady/flow keeps omission at zero. Explicit tie(0) re-attacks current body pitch, while other explicit values retain their probability. Fixed pitch and glide still re-attack each metric crossing, and the omission default applies whenever a live mode switch enters the eligible range. Every actual attack updates onset memory. Same-sample adoption precedes opportunity; no adoption-time candidate is added. Zero or omission matches gate_snap. Hold without coupled opportunities attacks at adoption; sustained participation attacks only at sounded opportunities. Rest retains this adoption policy through tails and gaps without retuning released tails. Live three-mode changes preserve the Tone, emit no attack and cancel unrendered requests, pending attacks and selected glides. Boundary changes preserve the selected behavior until the next adoption. Returning to glide follows the controller’s retained target at the next control update; gate_snap and rearticulate wait for later adoptions. Repeating the same mode retains pending state. Replacement Voices inherit controls, not performance state. Initial-only articulation_persistence(p) adds initial-only policy retention within positive-boundary sustained participation; actual live mode changes reset it to Base, while the same mode and boundary-only updates retain it. Anchored Voices remain locked. Free-pitch Gated rearticulate remains a script error at final placement and before live writes, independent of builder order; use Hold with sustain(), including explicit sustain plus metric/entrained/steady/flow, or choose glide/gate_snap for Gated phonation.

landscape_weight

landscape_weight(value)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Weight of the landscape objective.

neighbor_step_cents

neighbor_step_cents(value)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Step size for neighbor exploration in cents.

move_cost

move_cost(coeff)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Cost multiplier for pitch changes.

move_cost_exp

move_cost_exp(exp)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Exponent for the move cost.

proposal_interval

proposal_interval(seconds)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Proposal generation interval in seconds. Controls opportunities to propose a pitch target, not the bodily participation rate set by intrinsic_rate(hz). A proposal or adoption is not necessarily a sounded onset.

tessitura_gravity

tessitura_gravity(value)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Gravity toward the tessitura center.

window_cents

window_cents(width)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Peak-sampler search window width in cents.

top_k

top_k(count)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Number of top candidates kept by the peak sampler.

sigma_cents

sigma_cents(spread)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Gaussian spread of the peak sampler in cents.

random_candidates

random_candidates(count)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Number of random candidates considered.

global_peaks

global_peaks(count)
global_peaks(count, min_sep_cents)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

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

ratio_candidates

ratio_candidates(count)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Ratio-based movement candidates; 0 disables.

Neighbor Awareness

crowding_target

crowding_target(same_visible, other_visible)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Which voices are visible to crowding: own population, other populations (booleans).

leave_self_out

leave_self_out(enabled)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

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

leave_self_out_harmonics

leave_self_out_harmonics(count)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

Number of harmonics used for approximate self-subtraction.

Lifecycle & Viability

viability_scope

viability_scope(name)

Applies to: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

"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_aversion

set_roughness_aversion(weight)

How much the modeled listener minds roughness (default 1.0). Scales the configured roughness terms of consonance valuation (field and density), clamped to [0, 100]; non-finite values are ignored. 0 ignores roughness in valuation. It acts as aversion, with larger values penalizing roughness more, when the configured kernel penalizes roughness at every harmonicity (b <= 0 and b + c <= 0, true for the defaults). Roughness itself, as sensed and displayed, does not change.

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: PopulationSpec only. Initial-only: configure the PopulationSpec before place().

"hill_climb" or "peak_sampler". Research control.

move_cost_time_scale

move_cost_time_scale(name)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

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

Neighbor Awareness

leave_self_out_mode

leave_self_out_mode(name)

Applies to: PopulationSpec and Population. Live-patchable: updates running voices in a Population.

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

Lifecycle & Viability

selection_approx_loo

selection_approx_loo(enabled)

Applies to: PopulationSpec only.

Override environment-relative viability scoring; research/reference control. PopulationSpec 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.