Repository navigation
The block engine. The audio engine and the synth compiler were rebuilt to process audio in blocks (64 samples by default) instead of a sample at a time. Synths and effects use 1.3x to 3.5x less CPU (an echo 3.5x, a 12-voice plucked string 2.5x, a chorus 1.9x), and timing stays sample-accurate. This is a breaking release: synths must be recompiled, controls are now inputs, and shape operations take axes. Migrating to the Block Engine lists what changed with before-and-after code.
Highlights
Breaking
- Plugin ABI v3: plugins compiled before this release must be recompiled (
defSynthdoes it; the engine refuses old plugins).process(synth, offset, n)runs a block over per-channel port buffers. setControland control descriptions are gone. A synth's parameters are inputs:control(name, spec)declares one with a range and default; set it withsetInput/setInputAt/setInputBox(stepped or ramped),setInputX(crossfaded) orimpulseInput, or connect another node's output to it.uiwidgets attach withbindInput.- Signals are tensors with a shape, and every integer argument of a shape operation is an axis:
sum(n)no longer folds a row into n groups, andtranspose(n)andmixToare removed. A stereo mixdown is a sum along an axis. - The C++
synthdef-compileris retired; synthc is the only synth compiler, anddefSynth(withdefSynthStrictanddefSynthChecked) now compiles with it.defSynthXand its variants, synthc's former names, still work.
Engine & Control
- Feedback between nodes: a connection may close a cycle. The cycle runs a sample at a time with a one-sample delay, or a block at a time with
feedbackMode(silo, FeedbackMode.feedbackBlock). - Scheduled changes stay sample-accurate inside a block: value changes are rendered at their sample, and node starts and frees split the block there.
- Fixed:
detachVMleft the silo running its tasks and actors on the VM being deleted, so a stopped silo melody could play one more note afterallNotesOff, which then hung (and the freed VM memory was written to, a likely cause of rare app crashes). - Engine,
uiand synthdef errors (a note sent to a node that does not exist,newNodeof a def that is not loaded, silo compile errors) now appear in the app's output pane; they went only to the terminal before.
SynthDefs & UGens
- Voicers skip finished voices: a released voice stops costing CPU once
doneWhen(cond)holds or its output has been silent forvoicer(n, body, silence)seconds (default 0.2; 0 turns skipping off). - Shapes and tensor constants: anywhere a shape is expected you can write its dims (
AsShape), socontrol("gains", spec, [4, 2])andurand([3, 2])work; constants of any shape aretensor([2, 3], values)or nested arrays. - Shape operations along any axis:
take,drop,stride,slice,rotate,reverse,transpose,reshape,join,stack,reduce,scan,sumand kin,atandput. - Values computed from inputs (filter coefficients, pitches) are recomputed only when the inputs change, and recurrences such as filters and phasors run as block-wide forms;
defSynthStrictkeeps plain sample order for reference renders. - Fixed: mixing
f32andf64signals widens tof64instead of failing (#16);-2.0 * abs(x)came out positive (#13).
Language & VM
- Nested array literals without the inner brackets: a run of n semicolons closes n levels of nesting, so
[1, 2, 3; 4; 5, 6]is[[1, 2, 3], [4], [5, 6]]and[1, 2; 3, 4;; 5, 6; 7, 8]is[[[1, 2], [3, 4]], [[5, 6], [7, 8]]]. It works for tensor constants too:tensor([1.0, 2.0; 3.0, 4.0])is a 2x2. - Fixed: a crash in long renders and live sessions that play scores -- a list built from a coroutine (which
scoreuses) could be freed by the garbage collector before it was returned. Several other places where an incremental collection could free a value still in use were fixed too. - Fixed: a
letorvarinside a function whose name matched a global also overwrote that global, which could crash the app (for example running the cookbook chapters and then an example that reuses their names) or silently change the global. - A top-level
varis one variable everywhere: functions, lambdas and top-level code all see the same value. - Template functions are type-checked in their own scope, not the first caller's.
- Importing two modules that both define a type of the same name, then using the bare name, is an "ambiguous type" error.
- A file that shadows a library module it imports gets an error saying so (#15).
App & Notebooks
- Fixed: running a cell in a notebook you had not edited could mark it unsaved, so opening another file asked to save. Notebooks whose saved history lagged their cells now open with that recorded, and all the shipped notebooks were re-saved to match.
- The example notebooks are ported to the block engine, and each cookbook chapter now runs on its own: chapters 3 and 4 define the synths they play, and chapters 5 to 8 and 10 use their own nodes (501, 600, 701, 801, 1001, 1002), so they no longer collide with chapter 3's node (
errNodeIDAlreadyTaken) or stay silent when opened alone, and their stop cells free the nodes so a chapter can be run again.
Docs & Site
- Links in the body text of the migration guide, SynthDef guide, Builtin Functions, Music Libraries and Standard Library pages use the page's accent color instead of the browser's default dark blue, which was hard to read on the dark theme.
- New Migrating to the Block Engine guide; the SynthDef guide's chapters on shapes, axes and broadcasting are rewritten in more depth.
v0.2.7 marks the last main before the block engine, for anyone who needs to stay on the sample engine.
The DMG is Apple Silicon (arm64) only, as before.
See NEWS.md for the curated changelog.
Requirements: macOS 13.3 or later on Apple Silicon (CoreAudio), or Linux (ALSA/JACK/Pulse). Building from source needs Clang 19+, CMake 3.21+, C++23.