defSynth calls
again. The engine refuses plugins built for the old engine. defSynth
now runs synthc; the old C++ compiler it used to run is gone. Scripts that
call defSynthX, synthc's former name, still work.setControl with setInput
(§4.1), and bindControl with
bindInput.sum(2), sum(n),
transpose(n) or mixTo: a number given to a shape operation
is now an axis (§4.2).Rate.event to Rate.block.| Before | Now | |
|---|---|---|
| Processing | Every synth computed one sample per call. | Every synth computes a block per call (64 samples by default; settable
with --block-size or blockSize in the config). |
| Timing | Commands took effect at their sample. | The same. A value change is written into the input at its sample; starting or freeing a node, or a new note, splits that node's block there. |
| Synth parameters | Controls: a separate list, set by number or name
with setControl, recomputed through event-rate code. |
Inputs. control(name, spec) declares an input with a range and
default. Set it (stepped, ramped or crossfaded) or connect a signal to it. Values
that depend only on inputs are recomputed only when those inputs change. |
| Channels | A count, rounded up to a power of two. Widths combined to the larger. | A shape of up to 4 dimensions, exact. Widths combine to the least common multiple, per dimension (§5). |
| Recurrences (filters, phasors, envelopes) | Run sample by sample. | Recognised by the compiler and run as block-wide scans or state-space forms
where they can be, with the same results to within rounding.
defSynthStrict keeps the sample-by-sample order. |
| Voices | Allocated inside each compiled synth. | Allocated by the engine, which writes each note's row of the synth's
notes input. A released voice that has finished is skipped. |
| Feedback between nodes | A loop of connections had a one-sample delay. | The same by default: the loop's nodes run a sample at a time. Or a
one-block delay, cheaper, with feedbackMode. |
| Synth compiler | Two: a C++ compiler (defSynth) and
synthc (defSynthX). |
synthc only, written in Tzopilotl (lang/modules/synthc/),
run by defSynth. defSynthX still works and does the
same. |
| Plugin interface | ABI v2: per-sample calls. | ABI v3 (§7). |
| Before | Now |
|---|---|
setControl(node, id, value)setControl(node, "name", value) |
setInput(node, port, value) with a port number or an input name;
setInput(node, port, value, rampTime) to glide;
setInputX(node, port, value, xfadeTime) to crossfade a connected
input to a value. Inside begin() … go(0) like
other commands. |
setInput(node, port, value) (one value) |
The same name, now for any input and any number of values:
setInput(node, port, [v0, v1, …]), plus
setInputAt and setInputBox for part of an input. |
bindControl(w, node, "name") | bindInput(w, node, "name"), optionally one element: bindInput(w, node, "name", element). |
defSynth(f, "name") (C++ compiler), defSynthX(f, "name") (synthc) | defSynth(f, "name"), which runs synthc. Rerun it so the synth is rebuilt for the block engine. |
Rate.event | Rate.block. Usually you need neither: a value
computed from controls is recomputed only when they change. |
sum(n), product(n), minOf(n), maxOf(n) folding to n channels |
sum(axis) reduces along an axis. Fold a flat row with
reshape first: x reshape([-1, 2]) sum(0). |
transpose(n) | x reshape([-1, n]) transpose;
transpose with no argument reverses the axes. |
mixTo(n) | reshape and sum(axis), as above. |
take(n), stride(n), … rounding up to a power of two |
Exact, along an axis (the last by default): take(n, axis). |
join(signals) | join(signals, axis = -1); stack(signals, axis = 0)
makes a new axis. |
rotate(a, amount) | rotate(a, amount, axis = -1): element
i of the result is element i + amount. |
tzpl_errCyclicConnection on a connection loop | Loops are accepted
(feedbackMode). |
| What | Where |
|---|---|
Shapes and tensor constants: shape, row, matrix,
cuboid, the AsShape constraint, tensor(shape, values),
tensor([[…], […]]) | §5 |
Shape operations along an axis: reshape, stack, scan,
at/put along an axis; axis names cols, rows,
planes | §5.5 |
Setting part of an input: setInputAt, setInputBox; one-sample
values: impulseInput | §4.1 |
Gliding a sounding note's parameters: noteSetParams(…, rampTime) | §4.3 |
Skipping finished voices: voicer(n, body, silence), doneWhen | §4.3 |
feedbackMode(silo, mode), defSynthStrict, --block-size | §6 |
The examples below use these imports:
import synthdef.*;
import synthc.compile.*;
import common_ugens.*;
import filters.*;
import audio_engine.*;
Controls are declared as before, and they are now inputs: a control is
an input with a range and a default, numbered with the synth's other inputs in the order
the graph declares them. Set them with setInput, by name or number, inside a
bundle.
-- Before
begin(); setControl(100, "cutoff", 800.0); go(0);
begin(); setControl(100, 1, 0.3); go(0); -- by control number
-- Now
fn filtered() S {
let cutoff = control("cutoff", ControlSpec { lo: 50.0, hi: 8000.0, init: 1200.0, warp: ControlWarp.exponential });
let amp = control("amp", ControlSpec { lo: 0.0, hi: 1.0, init: 0.1, warp: ControlWarp.linear });
110.0 lfsaw rlpf(cutoff, 0.3) * amp |> outlet
}
filtered defSynth("filtered") await;
begin(); newNode("filtered", 100); connect(100, 0, 0, 0); go(0);
begin(); setInput(100, "cutoff", 800.0); go(0); -- a step
begin(); setInput(100, "cutoff", 3000.0, 2.0); go(0); -- a 2-second glide
begin(); setInput(100, 1, 0.3); go(0); -- by input number
A multichannel control takes several values, and part of it can be set on its own:
fn chord() S {
let freqs = control("freqs", ControlSpec { lo: 50.0, hi: 2000.0, init: 220.0, warp: ControlWarp.exponential }, 3);
freqs sinosc sum * 0.05 |> outlet
}
chord defSynth("chord") await;
begin(); newNode("chord", 101); connect(101, 0, 0, 0); go(0);
begin(); setInput(101, "freqs", [220.0, 277.2, 329.6]); go(0);
begin(); setInputAt(101, "freqs", 2, 392.0, 0.5); go(0); -- element 2 only, gliding
Any input can instead be connected to another node's output with
connect; while it is connected, setInput sets the value it
returns to when disconnected. In the app, bindControl(w, node, "cutoff")
becomes bindInput(w, node, "cutoff").
Every integer argument of a shape operation is now an axis (which
dimension to work along), never a channel count. sum(2) used to fold a row
into 2 channels; now it means "sum along axis 2", and on a row of 16 it is an error,
because a row has only one axis. To fold, first give the signal the dimensions you mean
with reshape, then sum along the one to remove.
-- Before: 16 sines, folded to stereo (even channels left, odd right)
exprand(200, 2000, 16, Rate.init) sinosc sum(2) * 0.05 |> outlet
-- Now: 8 rows of (left, right), summed over the rows
fn shimmer() S {
exprand(200, 2000, 16, Rate.init) reshape([8, 2]) sinosc sum(0) * 0.05 |> outlet
}
shimmer defSynth("shimmer") await;
reshape([8, 2]) keeps the channels in order and reads them as 8 rows of
2, so channel 0 goes left, 1 right, 2 left, and so on: exactly the old fold. One
dimension may be -1, meaning whatever is left: reshape([-1, 2]).
sum with no argument still mixes everything to one channel.
The old transpose(n) (read a row as n columns and transpose) is a reshape
and a transpose; flatten the result if you need a row again:
-- Before
x transpose(4)
-- Now
x reshape([-1, 4]) transpose reshape([-1])
A voicer's output has a leading voice axis: voicer(8, body) with a mono
body is 8 channels, and with a stereo body it is an 8×2 matrix. Mix voices
together with sum(0) (over the voices), or sum for mono.
-- Before: stereo voices mixed with a fold
voicer(8, stereoVoice) sum(2) |> outlet
-- Now
fn stereoPad() S {
voicer(8, fn() S {
let f = noteParam("freq", ControlSpec { lo: 20.0, hi: 8000.0, init: 440.0, warp: ControlWarp.exponential });
let env = gate() asr(0.05, 1.0, 0.5);
[f, f * 1.003] stack sinosc * env * 0.1 -- 2 channels per voice
}) sum(0) |> outlet -- 8x2 summed over the voices
}
stereoPad defSynth("stereoPad") await;
begin(); newNode("stereoPad", 102); connect(102, 0, 0, 0); go(0);
begin(); noteOn(102, 1, [220.0]); go(0);
begin(); noteSetParams(102, 1, 0, [330.0], 1.0); go(0); -- new: glide the note's freq over 1 s
begin(); noteOff(102, 1); go(0);
Mono voices that the old code spread across left and right with sum(2)
(voice 0 left, voice 1 right, …) keep that with a reshape:
voicer(8, monoVoice) reshape([-1, 2]) sum(0).
Note functions (noteOn, noteOff,
noteSetParams) are unchanged except that noteSetParams can now
ramp. Voices are allocated by the engine: a new note takes the voice released longest
ago, else steals the one started longest ago. A released voice stops costing CPU once it
is finished: once its body's doneWhen(cond) holds, or once its output has
been below −120 dB for the voicer's third argument, silence, in
seconds (default 0.2; voicer(n, body, 0.0) turns this off).
Rate.event is now Rate.block. The compiler places work at the
slowest rate it can (constant, once at start, per note, when inputs change, per sample)
without being told, so most code never names a rate.
Channel counts used to round up to a power of two, and two widths combined to the larger. Now a 3-element array is exactly 3 channels, and widths combine to their least common multiple, each side repeating:
[1.0, 2.0, 3.0] vec -- before: 4 channels; now: 3
[1.0, 2.0, 3.0] vec * [1.0, 2.0, 3.0, 4.0] vec
-- before: 4 channels; now: 12 (3 and 4 each repeated)
If a synth suddenly has many more channels than you expected, look for two widths that do not divide each other.
↑ Back to topEvery signal is a tensor: per sample, a block of numbers with a shape of up to 4 dimensions. A mono signal is a scalar (rank 0), a stereo signal a row of 2 (rank 1), a bank of 8 stereo oscillators an 8×2 matrix (rank 2). Channels are numbered in row-major order: the last dimension varies fastest, so in an 8×2 matrix, channel 0 is row 0 left, channel 1 row 0 right, channel 2 row 1 left.
A shape is a Shape value, or anywhere a shape is expected, simply its
dimensions as an array, outermost first. The AsShape constraint accepts
both:
| Written | Shape | Rank |
|---|---|---|
scalarShape() | one value | 0 |
[4] or row(4) | a row of 4 | 1 |
[2, 3] or matrix(2, 3) | 2 rows of 3 | 2 |
[2, 3, 4] or cuboid(2, 3, 4) | 2 planes of 3 rows of 4 | 3 |
[2, 2, 3, 4] or shape([2, 2, 3, 4]) | rank 4, the most | 4 |
The rank is part of the shape: [1, 4] (one row of 4) is a different
shape from [4], though both have 4 channels. Functions that create signals
take an AsShape; the ones that took a channel count still do, and a count of
1 is a scalar:
fn shapes() S {
let spec = ControlSpec { lo: 0.0, hi: 1.0, init: 0.5, warp: ControlWarp.linear };
let gains = control("gains", spec, [4, 2]); -- a 4x2 control (8 values)
let noise = urand([4, 2]) * 2 - 1; -- 4x2 independent noise
let half = fill([4, 2], 0.5); -- a 4x2 constant
noise * gains * half * 0.1 |> sum(0) outlet -- mixed to 2 channels
}
shapes defSynth("shapes") await;
(The music libraries have an unrelated Shape type for note shapes; the
one meant here is synthdef's.)
A number is a scalar constant and an array is a row: 0.5,
[220.0, 330.0] (or [220.0, 330.0] vec). For more dimensions,
nest arrays, or give a shape and the values in row-major order:
tensor([[1.0, 2.0, 3.0],
[4.0, 5.0, 6.0]]) -- 2x3, rows as written
tensor([2, 3], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]) -- the same tensor
tensor([4, 4], [1.0, 0.0]) -- values repeat to fill: 1 0 1 0 ...
A gain matrix that pans three tones, one row per output side:
fn panned() S {
let gains = tensor([[1.0, 0.5, 0.0], -- left: tone 0 full, 1 half, 2 off
[0.0, 0.5, 1.0]]); -- right: tone 0 off, 1 half, 2 full
let tones = [220.0, 277.2, 329.6] sinosc; -- a row of 3
tones * gains * 0.05 |> sum(cols) outlet -- 2x3, each row summed: stereo
}
panned defSynth("panned") await;
Nested arrays may be up to 4 deep, and every row at a level must be the same length. Integer values make integer constants that take the type of whatever they combine with.
When an operation combines two signals of different shapes, the shapes are lined up
from their last dimensions, and each dimension of the result is the
least common multiple of the two sizes. Each side repeats along a
dimension to fill it: index i of the result reads index
i mod size of the input.
| a | b | a op b | How |
|---|---|---|---|
| scalar | row of 2 | row of 2 | the scalar applies to both |
| row of 2 | row of 8 | row of 8 | a repeats 4 times: a0 a1 a0 a1 … |
| row of 2 | row of 3 | row of 6 | a repeats 3 times, b twice |
| row of 3 | 2×3 matrix | 2×3 | the row applies to each row |
| 2×1 matrix | row of 3 | 2×3 | a column against a row: an outer product |
| 2×3 | 4×3 | 4×3 | the 2 rows repeat twice |
This differs from NumPy, which requires each dimension to be equal or 1; here any
sizes combine, cycling. Broadcasting only widens; mix down with the reductions below.
Ugens are built from these operations, so they broadcast too: a 2×3 frequency into
sinosc is 6 oscillators with a 2×3 output.
-- 3 pitches x 2 detunes: a column of 3 against a row of 2 makes 3x2
fn detunedChord() S {
let pitches = tensor([[220.0], [277.2], [329.6]]); -- 3x1
let detune = [1.0, 1.004]; -- row of 2
(pitches * detune) sinosc sum(0) * 0.05 |> outlet -- 3x2, summed over the pitches: stereo
}
detunedChord defSynth("detunedChord") await;
The dimensions of a signal are its axes. They are numbered from the
outermost, starting at 0, as in NumPy; negative numbers count from the
last, so -1 is always the last axis whatever the rank. The constants
cols (−1), rows (−2) and planes
(−3) name them. For a 2×3×4 signal:
| Axis | Also | Size | Moves between |
|---|---|---|---|
0 | -3, planes | 2 | planes |
1 | -2, rows | 3 | rows in a plane |
2 | -1, cols | 4 | elements in a row |
A shape operation works along one axis, the last by default, so on a row it simply works on the channels in order. An axis the signal does not have is a compile error.
| Operation | Result, for x of shape 2×3×4 |
|---|---|
x take(2, rows) | 2×2×4: the first 2 rows of each plane (also drop, stride, stutter, ncyc, slice) |
x reverse(0) | 2×3×4, the planes swapped (also rotate) |
x sum(cols) | 2×3: each row summed; the axis goes away (also product, minOf, maxOf, reduce) |
x sum | scalar: everything summed |
x scan(BinaryOp.add, cols) | 2×3×4: running sums along each row |
x transpose | 4×3×2: axes reversed (transpose(perm) permutes them) |
x reshape([6, -1]) | 6×4: the same 24 channels in a new shape |
[x, y] join(cols) | 2×3×8 when y is 2×3×4: concatenated along an axis |
[x, y] stack | 2×2×3×4: a new outer axis |
x at(1, rows) | 2×4: row 1 of each plane (an index row picks several) |
x put(0, z, rows) | 2×3×4 with row 0 of each plane replaced by z |
The rearranging operations compute nothing: the compiler reads the source in the new order. Result shapes and shape errors are found when the synth is compiled. The SynthDef guide §5 has every operation and its arguments.
↑ Back to topfeedbackMode(0, FeedbackMode.feedbackBlock) makes silo 0 run loops a
block at a time instead, with a one-block delay, which costs much less.f32). For a reference render, compile with
defSynthStrict(f, "name"), or set TZPL_STRICT_RECURRENCES=1
for every synth.--block-size n or
blockSize = n in the project config (4 to 1024). Timing is sample-accurate at
any size./engine/setInput,
/engine/setInputAt, /engine/setInputRamp,
/engine/setInputX, /engine/impulseInput and their NATS
engine.* forms (FFI guide).
/engine/setControl is gone.Plugins built by hand against shared/tzpl_plugin_abi.h must be ported to
ABI v3 and export tzpl_abi_version = 3; the engine refuses older ones.
process(synth, offset, n) computes samples offset to
offset + n - 1 of the block. n may be anything from 1 to the
block size: the engine splits a block at events, and a feedback loop calls one sample
at a time.ins[k].chans[c],
outs[k].chans[c]). Each input channel also has an
isConst flag (one value for the whole block) and a version
that changes when its value or connection does, so work that depends only on inputs
can be skipped.tzpl_Shape (dims and rank) and an element type.
Controls are inputs with a spec; there is no control table.notes input of shape
{maxVoices, 1 + params} (column 0 is the gate) and a
resetVoice(synth, voice, offset) function; the engine allocates voices.engine/Architecture.md describes the engine in full.