Music Libraries Reference

music.core

The shared substrate, re-exported by every dialect: the event and pitch types (music.event), tunings and scales (music.tuning), and a few random helpers (music.rand). Pure and RT-safe.

Events

An Event is one note (or rest) with an absolute onset in beats. Pitch stays symbolic — a Pitch value is only resolved to Hz at play time, through a Tuning and Scale, so the same events can be performed in 12ED2, a tritave tuning, or a just-intonation table. Note value and sounding time are distinct fields: dur is the time the note occupies in its line (it drives retrograde, stretching, and spacing); sustain is the time until release (it drives noteOff).

Tunings and scales

A Tuning maps real-valued steps to frequency; a Scale is a separate layer that selects steps per degree (the same split as Scala's .scl tuning files versus keyboard mappings). Equal tunings are a formula — the division count is a real number, so 8.5 divisions of the octave is legal — and unequal tunings are a cents table with linear interpolation at fractional positions. Degrees, ratios, and cents resolve relative to the tuning root; steps and Hz are absolute.

Random helpers

These sit alongside the built-ins urand/brand/rand/irand/xrand/pick/muss and their stream forms; randSeed(n) re-seeds the per-VM generator for reproducible streams and performances.

import music.core.*;

-- 13 equal divisions of the tritave, anchored at 220 Hz
let t = bp() root(220.0, 0.0);
stepHz(t, 13.0);                     -- 660.0 (one tritave up)

-- 8.5 equal divisions of the octave; fractional steps are ordinary
stepHz(edo(8.5), 4.25);             -- halfway up the octave

-- degrees resolve through a scale, wrapping below the root
degreeStep(major, 9);                -- 16.0 (a tenth: octave + third)
degreeStep(major, -1)                -- -1.0 (leading tone below)

music.pat

Pattern streams, inspired by SuperCollider's Patterns library and by Sound as Pure Form (SAPF). There is no separate pattern class: patterns are ordinary lazy List values, usually infinite, so the whole list vocabulary already applies (cyc, take, drop, stutter, zip, scan, the infinite random streams rands/irands/xrands/picks, …). This module adds the missing musical vocabulary plus bind, which zips per-field streams into events. Pure and RT-safe; seed with randSeed for reproducibility.

import music.pat.*;
randSeed(2026);

let melody = bind(
    wpicks([0, 1, 2, 4], [4.0, 2.0, 3.0, 1.0]) degree,  -- weighted degrees
    List(0.5, 0.25, 0.25) cyc,                              -- durations
    rands(0.2, 0.6),                                        -- amplitudes
    List(0.7) cyc,                                          -- legato
    [('cutoff, series(800.0, 50.0))]);                      -- a param stream

let bass = bind(List(-7, -5) cyc degree, List(2.0) cyc);
let tune = merge(melody, bass) takeDur(32.0);              -- two voices, 32 beats

music.score / music.play

The player, split so its logic stays testable. music.score is pure: it lowers an event stream to a time-ordered command stream — noteOn at each onset, noteOff at onset + sustain, note IDs allocated round-robin from the voice's pool, rests skipped. NoteCmd deliberately mirrors the note cases of bundles.x's EngineCmd, so the engine adapter is a one-line map per case. music.play (engine-coupled; re-exports bundles.*) turns each group of simultaneous commands into one first-class Bundle scheduled at an absolute beat on the engine's TempoClock — chords are atomic and timing is sample-accurate.

import music.pat.*;
import music.play.*;
import audio_engine.*;

engineStart();
let v = pitchVoice(101);
voiceBundle(v, "my_voicer") go(0);

let p = play(tune, v, et12, pentMinor);   -- sample-accurate Bundles on the beat
p replace(otherTune);                     -- swap what's playing
p stop;

-- or render offline, in any tuning:
let h = render(tune, v, "my_voicer", "/tmp/take1.wav", 20.0, bp() root(220.0, 0.0), chromatic(13));
await renderDone(h);

music.media

An algebra of notes and compositions, inspired by Paul Hudak's Haskore and the temporal-media work in The Haskell School of Music. Music<T> is a recursive value: a note (duration + payload), a rest, two Musics in sequence, two in parallel, or a control annotation over a subtree. Because a piece is a value, it can be analyzed and transformed before it is performed. Payloads are un-timed by design — time lives in the structure, and Event is the output of perform. Transformations take the Music first, so pipelines read left-to-right: theme dyn(0.7) trans(-4) tempo(2.0). Pure and RT-safe.

import music.media.*;

fn deg(d Int, dur Float) Music<Pitch> = note(dur, degree(d));
let theme = line([deg(0, 1.0), deg(1, 1.0), deg(2, 0.5), deg(4, 1.5)]);

-- the theme against itself: two beats late, a fifth down, quieter
let canon = theme | (mrest(2.0) $ (theme dyn(0.7) trans(-4)));

canon mdur;                      -- 6.0
canon retro perform showEvents;  -- reversed, as events
canon perform play(v);           -- or straight to the player

music.shape / music.job

Shapes, morphological operators, and hierarchical forms, inspired by HMSL (the Hierarchical Music Specification Language). A Shape is a sequence of frames over named dimensions — by default [dur, degree, amp], but any dimension you add ('cutoff, 'pan, …) is carried into events as a synth param of the same name, so melodies can run over any set of control dimensions, not just pitch. music.job arranges shapes into hierarchies whose selection decisions are made at realize time: realizing the same form twice gives two readings. Pure (RNG only).

import music.job.*;

let theme = shape([[0.5, 0.0, 0.5], [0.25, 1.0, 0.4], [0.5, 3.0, 0.5], [0.75, 4.0, 0.6]]);
let riffs = [
    Coll.leaf(theme),
    Coll.leaf(theme retrograde),
    Coll.leaf(theme invertDim('degree, 2.0)),
    Coll.leaf(theme transposeDim('degree, 4.0) scaleDim('dur, 0.5)),
];
let form = Coll.seqc([
    Coll.rpt((4, Coll.sel((Behavior.shuffled, riffs)))),   -- four shuffled riffs
    Coll.parc([Coll.leaf(theme), Coll.leaf(shape([[3.0, -7.0, 0.4]]))]),
]);

let p = play(realize(form), v);   -- one reading, realized up front
p enqueue(realize(form));         -- a different reading follows it

let big = Coll.rpt((10000, Coll.sel((Behavior.shuffled, riffs))));
play(realizeCo(big), v);          -- incremental: selects as it plays

music.spans

Patterns as functions of time, inspired by Tidal Cycles. A Pattern<T> is a callable value: query it with a Span (in cycles, half-open) and it returns the Haps — value fragments — active in that window. Structure is computed, never stored, so transformations compose freely and everything is repeatable. Time is Float cycles with an explicit edge policy: fragments shorter than kEps (10⁻⁹) are dropped, cycle iteration starts at floor(a + kEps), and onset tests compare within kEps. Combinators take the pattern first, so pipelines read left-to-right. Pure and RT-safe.

import music.spans.*;
import music.play.*;

fn d(x Int) Pattern<Pitch> = pure(degree(x));

let tune = stack([
    d(-14) euclid(3, 8) events(0.8, 0.6),                -- euclidean bass
    fastcat([d(0), d(4), d(5), d(7)])
        iterp(4)
        every(4, fn(p Pattern<Pitch>) Pattern<Pitch> { p rev })
        events(0.5, 0.9)
        withAmp(sinePat() slow(4.0) range(0.25, 0.6) segment(4)),
]);

play(patEvents(tune, 16.0, 2.0), v);   -- 16 cycles, 2 beats per cycle

Interop & examples

Because every dialect ends in the same List<Event>, the layers combine freely: merge a bind stream with a performed canon, enqueue rendered span-pattern cycles after a realized form, apply the event helpers (stretch, gain, takeDur) to any of them, and resolve all of it through one tuning at play time. The pure layers golden-test under plain tzpl (see lang/tests/music/).

Complete runnable examples, each with run instructions in its header: