Tzopilotl
Docs
GitHub

Migrating to the Block Engine

The audio engine and the synth compiler have been rebuilt. The engine now processes audio in blocks (64 samples by default) instead of one sample at a time, signals are tensors with a shape, and a synth's parameters are ordinary inputs. Synths run 1.3 to 3.5 times faster, and timing is still exact to the sample. This is a breaking change: most scripts that set controls, mix multichannel signals down, or use the shape operations with a number need small edits, and every compiled synth must be recompiled. This page lists what changed and shows the code to change. The SynthDef guide covers everything here in more depth.

Contents

1. Checklist

  1. Recompile every synth. Run your 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.
  2. Replace setControl with setInput (§4.1), and bindControl with bindInput.
  3. Fix mixdowns written sum(2), sum(n), transpose(n) or mixTo: a number given to a shape operation is now an axis (§4.2).
  4. Check channel counts. They are exact now (3 is 3, not 4), and signals of different widths combine to the least common multiple (§4.5).
  5. Rename Rate.event to Rate.block.
↑ Back to top

2. What changed underneath

BeforeNow
ProcessingEvery 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).
TimingCommands 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 parametersControls: 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.
ChannelsA 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.
VoicesAllocated 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 nodesA 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 compilerTwo: 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 interfaceABI v2: per-sample calls. ABI v3 (§7).
↑ Back to top

3. API changes at a glance

Removed or renamed

BeforeNow
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.eventRate.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 loopLoops are accepted (feedbackMode).

Added

WhatWhere
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
↑ Back to top

4. Code that needs to change

The examples below use these imports:

import synthdef.*;
import synthc.compile.*;
import common_ugens.*;
import filters.*;
import audio_engine.*;

4.1 Setting controls

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").

4.2 Mixing down: numbers are now axes

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])

4.3 Voicers

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).

4.4 Rates

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.

4.5 Channel counts are exact

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 top

5. Tensors: constants, shapes, broadcasting, axes

Every 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.

5.1 Shapes

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:

WrittenShapeRank
scalarShape()one value0
[4] or row(4)a row of 41
[2, 3] or matrix(2, 3)2 rows of 32
[2, 3, 4] or cuboid(2, 3, 4)2 planes of 3 rows of 43
[2, 2, 3, 4] or shape([2, 2, 3, 4])rank 4, the most4

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.)

5.2 Tensor constants

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.

5.3 Broadcasting

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.

aba op bHow
scalarrow of 2row of 2the scalar applies to both
row of 2row of 8row of 8a repeats 4 times: a0 a1 a0 a1 …
row of 2row of 3row of 6a repeats 3 times, b twice
row of 32×3 matrix2×3the row applies to each row
2×1 matrixrow of 32×3a column against a row: an outer product
2×34×34×3the 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;

5.4 Axes

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:

AxisAlsoSizeMoves between
0-3, planes2planes
1-2, rows3rows in a plane
2-1, cols4elements 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.

5.5 Shape operations

OperationResult, 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 sumscalar: everything summed
x scan(BinaryOp.add, cols)2×3×4: running sums along each row
x transpose4×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] stack2×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 top

6. New things to know about

↑ Back to top

7. For authors of C plugins

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.

engine/Architecture.md describes the engine in full.

↑ Back to top