Quick Start Guide

Conchordal v0.3.0 scripting API overview. For full details, see the API Reference.

Basic Concepts

• Species: Agent templates created with derive() from presets (sine, harmonic, saw, square, noise, modal).
• Groups: Collections of agents spawned from a species via create(species, count). Returns a GroupHandle.
• Timeline: wait(seconds) advances the clock. flush() forces immediate dispatch. scene() scopes groups with auto-release. parallel() runs branches concurrently.
• Strategies: Placement methods for multi-agent frequency assignment: consonance(), consonance_density_pmf(), random_log(), linear().

Minimal Example

// Single sine agent at 440 Hz for 2 seconds
create(sine, 1).freq(440.0);
wait(2.0);

Common Patterns

Custom Species Definition

let voice = derive(harmonic)
    .amp(0.5)
    .sustain()
    .brightness(0.7)
    .spread(0.2)
    .voices(4);

Body parameters are individual methods: brightness(v), spread(v), voices(n). Use energy(v) as an alias for amp(v).

Multiple Agents with Consonance Strategy

let base = derive(harmonic).energy(0.1).sustain();

// Place 4 agents using harmonic consonance relative to 220 Hz
create(base, 4)
    .place(consonance(220.0).range(1.0, 4.0).min_dist(1.0));
wait(2.0);

// Or use landscape-derived density placement
create(base, 4).place(consonance_density_pmf(110.0, 880.0));
wait(2.0);

Scene with Auto Cleanup

let drone = derive(sine).amp(0.3).sustain();
let seeker = derive(sine).amp(0.2).sustain();

scene("Introduction", || {
    let a = create(drone, 1).freq(110.0);
    let s = create(seeker, 1).freq(220.0);
    wait(3.0);
    // All groups auto-released when scene ends
});

Parallel Timelines

parallel([
    || {
        // Bass layer
        create(sine, 1).freq(110.0).sustain();
        wait(2.0);
    },
    || {
        // Melody layer
        create(harmonic, 1).freq(440.0).sustain();
        wait(1.0);
        create(harmonic, 1).freq(550.0).sustain();
        wait(1.0);
    }
]);

Modal Body with Custom Modes

The modal preset uses inharmonic mode patterns for bell/bar/glass timbres. Configure modes with modes(pattern) and control brightness.

let bell = derive(modal)
    .sustain()
    .pitch_mode("lock")
    .freq(220.0)
    .amp(0.11)
    .brightness(0.7)
    .modes(modal_table("vibraphone_1").count(5));

create(bell, 1);
wait(2.0);

Mode pattern constructors: harmonic_modes(), odd_modes(), power_modes(beta), stiff_string_modes(stiffness), custom_modes([ratios]), modal_table(name). Chain .count(n), .jitter(cents), .seed(n) to refine patterns.

Landscape-aware modes sample from the live perceptual field:

let adaptive = derive(modal)
    .sustain()
    .pitch_mode("free")
    .amp(0.05)
    .brightness(0.7)
    .modes(landscape_density_modes().count(16).range(1.0, 3.5).min_dist(0.9));

Phonation Control

Phonation follows a tiered system.

Tier 1 – Presets set sensible defaults for common use:

derive(sine).sustain();   // Sustained tone, tied to lifecycle
derive(sine).repeat();    // Interval-based retriggering

Tier 2 – Explicit when/duration for finer control:

derive(sine).once();              // Single trigger
derive(sine).pulse(2.0);         // Retrigger at 2 Hz
derive(sine).while_alive();      // Duration spans full lifecycle
derive(sine).gates(4);           // Hold for 4 gate cycles
derive(sine).field();            // Field-driven duration

These compose: derive(sine).pulse(3.0).gates(2) pulses at 3 Hz, each lasting 2 gates.

Pitch Control

// "lock" keeps initial frequency; "free" allows hill-climbing
derive(sine).pitch_mode("lock");
derive(sine).pitch_mode("free");

// "gate_snap" applies pitch on gate boundaries; "glide" interpolates
derive(sine).pitch_apply("gate_snap");
derive(sine).pitch_apply("glide").pitch_glide(0.05);

Live Parameter Patching

Groups support live updates on spawned agents:

let g = create(sine, 1).freq(220.0).sustain();
flush();
wait(1.0);

g.freq(440.0);   // Slide to new frequency
g.amp(0.3);      // Adjust amplitude
flush();
wait(1.0);

Global Parameter Modulation

// Overtone series emphasis (major quality)
set_harmonicity_mirror_weight(0.0);
create(sine, 4).place(consonance(261.63).range(1.0, 3.0));
wait(2.0);

// Shift toward undertone series (minor quality)
set_harmonicity_mirror_weight(1.0);
wait(2.0);

Preset Species

Next Steps

See the API Reference for the complete function list, type details, and advanced parameters.