Skip to content

TZPL v0.3.0

Latest

Choose a tag to compare

@lfnoise lfnoise released this 27 Oct 04:17
· 26 commits to main since this release

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 (defSynth does it; the engine refuses old plugins). process(synth, offset, n) runs a block over per-channel port buffers.
  • setControl and control descriptions are gone. A synth's parameters are inputs: control(name, spec) declares one with a range and default; set it with setInput / setInputAt / setInputBox (stepped or ramped), setInputX (crossfaded) or impulseInput, or connect another node's output to it. ui widgets attach with bindInput.
  • 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, and transpose(n) and mixTo are removed. A stereo mixdown is a sum along an axis.
  • The C++ synthdef-compiler is retired; synthc is the only synth compiler, and defSynth (with defSynthStrict and defSynthChecked) now compiles with it. defSynthX and 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: detachVM left the silo running its tasks and actors on the VM being deleted, so a stopped silo melody could play one more note after allNotesOff, which then hung (and the freed VM memory was written to, a likely cause of rare app crashes).
  • Engine, ui and synthdef errors (a note sent to a node that does not exist, newNode of 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 for voicer(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), so control("gains", spec, [4, 2]) and urand([3, 2]) work; constants of any shape are tensor([2, 3], values) or nested arrays.
  • Shape operations along any axis: take, drop, stride, slice, rotate, reverse, transpose, reshape, join, stack, reduce, scan, sum and kin, at and put.
  • 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; defSynthStrict keeps plain sample order for reference renders.
  • Fixed: mixing f32 and f64 signals widens to f64 instead 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 score uses) 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 let or var inside 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 var is 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.