Patcher

Modular Max/MSP-style DSP / event graphs. A Patcher owns a collection of PHandle-shaped objects wired together by inlets and outlets. The graph can be built programmatically, driven from Dart code, serialised to JSON, and replayed.

Upstream: YSE::patcher / pHandle, and the patcher guide (messages, time, data, files, subpatchers, host I/O).

For an end-to-end walk-through, see Patcher: modular synthesis in code. The list of object types createObject accepts is on the Patcher object reference reference page.

Patcher

Patcher

class Patcher implements Finalizable

Modular DSP/event graph (Max/MSP-style patcher).

Build a graph programmatically with [createObject] + [connect], or load one from a JSON dump via [parseJson]. Drive it directly with [passBang] / [passInt] / [passFloat] / [passString] into named .r (Obj.gReceive) objects, listen to what it sends back out on [messages], or hand it to a [Sound] via [Sound.fromPatcher] to use it as an audio source.

Constructors

factory Patcher({int mainOutputs = 2, String? name})

Construct a patcher with [mainOutputs] audio output channels.

Pass [name] to name the patcher from the start (see [name] for the rules); null or ‘’ keeps the auto-generated patcher_<N> name.

Throws [YseException] if the engine rejects the configuration (e.g. a negative [mainOutputs], or a [name] longer than [maxNameLength]).

Static accessors

static const int maxNameLength

The longest [name] the engine accepts, in characters.

Properties

Pointer<YsePatcher> get handle

Internal: native handle (used by Sound.fromPatcher).

String get name

set name(String? value)

The patcher’s name, which scopes every bus slot inside it.

Every patcher has one: an unnamed patcher gets an auto-generated patcher_<N>. A .s (Obj.gSend) object with slot x in a patcher named foo publishes to patcher.foo.x, and a .r (Obj.gReceive) with slot x hears a [Bus.publish] to patcher.foo.x. Note the patcher. prefix: host code addressing a patcher slot must add it.

Setting null or ‘’ restores the auto-generated name. Renaming re-anchors every slot under the new name. Names are not unique: two patchers with the same name share their slots and stores.

The name can be set before the engine is initialised; it is applied at init. It is saved by [dumpJson] and applied by [parseJson] unless a name was already set.

Throws [YseException] (invalidArgument) for a name longer than [maxNameLength] characters; the current name is kept.

int get objects

Number of objects in the patcher.

Stream<PatcherMessage> get messages

Broadcast stream of the messages this patcher sends to the host.

A message arrives here when it is sent to a name that no `.r` (`Obj.gReceive`) in this patcher receives: a .s (Obj.gSend) inside the patch, or a [passBang] / [passInt] / [passFloat] / [passString] call with nothing listening. [PatcherMessage.address] is that name — the .s argument or the pass* target — not the patcher.<name>.<slot> bus address (a .s also publishes there; see [name] and Bus).

The native send callback is installed when the first listener subscribes and cleared when the last one cancels. While it is installed, pass* returns true even for a name nothing receives (see [passBang]). Listening before the engine is initialised is fine: the callback takes effect at init.

## Threading

The engine calls the native callback synchronously on whichever thread emitted the message — the control thread for a pass* or a [PHandle] send* that drives a .s, but an engine worker thread for a timer-driven one (a millisecond .metro feeding a .s). Never the audio thread. Because it can run off the control thread, the bridge is a NativeCallable.listener: each call is posted to this isolate and delivered from its event loop, so listeners never run inside an engine callback and may call back into the patcher freely. Even a message from a pass* on this isolate is therefore delivered asynchronously, after the call returns. Each message’s native strings are copied and released exactly once, including messages still in flight when the stream is torn down.

## Lifecycle

[dispose] and System.close() clear the callback and close the stream (listeners get onDone). After System.close(), read [messages] again for a fresh stream. Reading it on a disposed patcher throws [StateError].

Methods

PHandle createObject(String type, {String args = ''})

Add an object of [type] to the patcher (see [Obj] for constants).

[args] is the creation argument string (object-specific format). The returned [PHandle] is owned by the patcher — release with [deleteObject], never directly.

void deleteObject(PHandle obj)

Remove [obj] from the patcher.

Deleting a subpatcher (an [Obj.patcher] object) also deletes everything inside it, transitively — nested subpatchers and their contents included. Any [PHandle] you still hold that pointed inside the deleted group is dangling afterwards: do not use it.

void clear()

Remove every object from the patcher.

void setContainer(PHandle obj, PHandle? container)

Put [obj] inside the subpatcher [container], or move it back to the top level when [container] is null.

A subpatcher is an object of type [Obj.patcher]. It is not a separate [Patcher]: create its contents with [createObject] on this patcher, then move them inside with this call. Its pins are the boundary objects among its direct contents — .inlet / ~inlet ([Obj.gInlet] / [Obj.dInlet]) and .outlet / ~outlet ([Obj.gOutlet] / [Obj.dOutlet]), whose one creation argument is the pin index. Message and signal boundaries share one index space per side. Subpatchers nest.

Containment is addressing, not storage: nested objects stay in this patcher’s one flat graph, so nesting costs the audio thread nothing. Moving an object changes no connection, so place objects before you [connect] to the subpatcher’s pins.

Throws [ArgumentError] when [obj] or [container] belongs to another patcher. Throws [YseException] when the engine refuses the move — [container] is not an [Obj.patcher] object, or the move would put a subpatcher inside itself or one of its own descendants. A refused move changes nothing.

void connect(PHandle from, {required int outlet, required PHandle to, required int inlet})

Connect [from]’s [outlet] to [to]’s [inlet].

Either end may be a subpatcher ([Obj.patcher] object): the pin number is resolved to the boundary object inside it that claims that index, and the connection is recorded straight to that boundary object (so walking the graph or [dumpJson] reports the boundary object’s ID). Connecting to a pin no boundary object claims is refused.

void disconnect(PHandle from, {required int outlet, required PHandle to, required int inlet})

Remove the connection from [from]’s [outlet] to [to]’s [inlet].

A subpatcher end resolves through its boundary objects as in [connect].

String dumpJson()

Serialise the current graph to JSON.

void parseJson(String content)

Load a JSON dump (as produced by [dumpJson]) into this patcher.

Loading adds to the current graph: objects already in the patcher are kept and the loaded ones are created next to them. Call [clear] first to replace the patch.

Throws [YseException] if [content] is malformed JSON or not a patch. A failed load is rolled back: the patcher is left exactly as it was.

PHandle getHandleAt(int index)

Object at position [index] in the list (0-indexed).

PHandle getHandleById(int id)

Object whose ID is [id].

bool passBang(String to)

Send a bang to the named .r receive object.

Returns true when a .r named [to] took it. While [messages] has a listener, a name nothing receives is handed to [messages] instead and this also returns `true`; it returns false only when neither takes it. The same holds for [passInt], [passFloat] and [passString].

bool passInt(int value, String to)

Send an integer to a named receiver. See [passBang] for the result.

bool passFloat(double value, String to)

Send a float to a named receiver. See [passBang] for the result.

bool passString(String value, String to)

Send a string to a named receiver. See [passBang] for the result.

void dispose()

Destroy the underlying native patcher and detach the finalizer.

Also clears the send callback and closes [messages].

PHandle

A PHandle is the wrapper’s view of one object inside a Patcher. The handle is owned by the patcher — destruction is through Patcher.deleteObject(), never by letting the handle go out of scope. Use PHandle to inspect an object’s structure (type, inlets, outlets), walk its outgoing connections, push messages straight to one of its inlets, and read or write its GUI metadata.

PHandle

class PHandle

Handle to one object inside a [Patcher].

Owned by the patcher — destruction is via [Patcher.deleteObject], not by the [PHandle] going out of scope.

Two [PHandle]s are equal when they refer to the same engine object, so a handle read back from [container] compares equal to the one returned by [Patcher.createObject].

Properties

int get hashCode

PHandle? get container

The subpatcher this object is directly inside, or null at the top level. Change it with [Patcher.setContainer].

int get subpatcherInlets

How many inlets this subpatcher presents to its parent: one past the highest index claimed by a .inlet or ~inlet among its direct contents (messages and signals share one numbering). A subpatcher whose only .inlet has index 2 reports 3. 0 when this object is not an [Obj.patcher].

Ask this, not [inputs]: a subpatcher owns no pins of its own, so [inputs] answers 0 for it.

int get subpatcherOutlets

How many outlets this subpatcher presents to its parent; the .outlet / ~outlet counterpart of [subpatcherInlets]. Ask this, not [outputs], which answers 0 for a subpatcher.

String get type

Type identifier of the underlying object (matches one of [Obj]).

String get name

Display name set in the patcher source.

String get params

Original creation argument string.

String get guiValue

The object’s whole live GUI state as one string — what a host polls to draw the control. For a scalar control (.slider, .i, .f, .dial, .incdec, .t) that is its value; for a structured one (.multislider, .rslider, .matrixctrl, …) it is every cell, space separated, in index order. Empty for an object with no GUI state.

This is the coherent read: one engine call, one snapshot. The per-cell reads ([guiValueCount], [guiValueAt]) are sampled one call at a time and may mix cells from before and after an edit.

A poll may be destructive: .b reports a pending press and clears it. Per object, poll either this getter or the per-cell reads once per frame — never both, or a consume-on-read object reports its event to one and not the other.

When [guiValueIsSettable] is true, [restoreGuiValue] with this string puts the state back. Not to be confused with [getGuiProperty], which is editor decoration persisted with the patch, not live state.

int get guiValueCount

How many cells the object’s GUI state has: 1 for a scalar control, the bank size for a .multislider, and so on. Objects without GUI state still answer 1 (their single cell is empty).

The count can change between this read and a following [guiValueAt] (a list on inlet 0 resizes a .multislider); a read past the end answers the empty string rather than failing.

bool get guiValueIsSettable

Whether this object accepts its own GUI state back on inlet 0: true when [restoreGuiValue] restores what [guiValue] read and [setGuiValueAt] writes one cell.

false for objects that predate the protocol, and deliberately for .b, whose value is a consume-on-read press — an event a restore could only replay.

int? get id

Patcher-assigned ID, or null when this handle refers to no object (the engine’s YSE_PATCHER_ID_NONE).

IDs start at 0 in every patcher, so 0 is a real ID. They are dense and reused: deleting an object frees its number for the next object created, so an ID identifies an object only while that object is alive. Keep the [PHandle] if you need a reference that outlives the number.

int get inputs

Number of inlets on this object.

0 for a subpatcher ([Obj.patcher]): its pins belong to the boundary objects inside it. Use [subpatcherInlets] instead.

int get outputs

Number of outlets on this object.

0 for a subpatcher ([Obj.patcher]); use [subpatcherOutlets].

Methods

bool ==(Object other)

String guiValueAt(int index)

One cell of the GUI state, or ‘’ for an [index] at or past [guiValueCount]. Cell 0 of a scalar control equals [guiValue].

The targeted read for repainting one cell without re-parsing the whole state. Reads of several cells are not atomic across cells; use [guiValue] when a coherent snapshot matters. See [guiValue] for the destructive-poll rule.

Throws [RangeError] for a negative [index].

void restoreGuiValue(String state)

Restore a GUI state previously read from [guiValue].

There is no GUI-value setter in the engine by design: this sends [state] as an ordinary list on inlet 0 (exactly sendList(0, state)), so it passes through the object’s own clamps and may emit on its outlets like any other message.

Throws [StateError] when [guiValueIsSettable] is false.

void setGuiValueAt(int index, String value)

Write one cell of the GUI state: sends set <index> <value> on inlet 0. On a .textedit — a one-cell control whose cell is free text and so has no set form — [value] is sent as the whole state instead.

The engine drops a cell write whose index is past its live count; this wrapper rejects one past the count it reads now.

Throws [StateError] when [guiValueIsSettable] is false, and [RangeError] when [index] is outside 0 <= index < guiValueCount.

bool isDspInput(int inlet)

Whether [inlet] accepts an audio signal.

OutType outputDataType(int pin)

Data type produced by [pin].

int connectionCount(int outlet)

Number of connections leaving [outlet].

int? connectionTargetId(int outlet, int connection)

ID of the target object of one [connection] from [outlet], or null when there is no such edge (the engine’s YSE_PATCHER_ID_NONE: an outlet or connection index out of range). See [id] for ID lifetime.

int? connectionTargetInlet(int outlet, int connection)

Inlet on the target reached by [connection] from [outlet], or null when there is no such edge (the engine’s YSE_PATCHER_INLET_NONE).

void sendBang(int inlet)

Send a bang to [inlet].

void sendInt(int inlet, int value)

Send an integer to [inlet].

void sendFloat(int inlet, double value)

Send a float to [inlet].

void sendList(int inlet, String value)

Send a string/list to [inlet].

void setParams(String args)

Reconfigure the object with a new argument string.

String getGuiProperty(String key)

Read a GUI property by [key].

GUI properties are editor decoration — geometry, colour, anything the host wants persisted with the patch (serialised under the “gui” key by [Patcher.dumpJson]). They are opaque to the engine and are not live control state; that is [guiValue].

void setGuiProperty(String key, String value)

Write a GUI property: editor decoration stored with the patch, not the object’s live state. To change what a control holds, use [restoreGuiValue] or [setGuiValueAt].

GUI controls

An editor draws a control by polling its GUI value, a list of string cells. Scalar controls (.slider, .i, .f, .dial, .incdec, .t) have one cell; structured ones (.multislider, .rslider, .matrixctrl, .kslider, .function, .xyslider, .umenu, …) have several.

• Read the whole state with PHandle.guiValue — one engine call, one coherent snapshot, cells space separated.

• Read one cell with PHandle.guiValueCount and PHandle.guiValueAt(). These are sampled one call at a time and are not atomic across cells (an edit can land between two reads, and the count can change), so use guiValue when coherence matters. A read past the count answers ''.

• Write — there is no setter, by design. State goes back in as an ordinary message on inlet 0, passing the object’s own clamps and outlet sends. PHandle.restoreGuiValue() sends a saved guiValue string back; PHandle.setGuiValueAt() sends set <index> <value> (on .textedit, whose one cell is free text, the value is sent as the whole state instead). Both require PHandle.guiValueIsSettable and are thin wrappers over sendList(0, ...).

Polls can be destructive: .b reports a pending press and clears it, which is also why .b is not settable. For a given object, poll either the whole-state read or the per-cell reads once per frame, never both. Cell strings are engine-formatted (zero reads 0.); parse them rather than comparing text.

GUI properties (PHandle.getGuiProperty() / PHandle.setGuiProperty()) are a different thing: editor decoration such as geometry or colour, opaque to the engine and persisted with the patch under the "gui" key of Patcher.dumpJson(). They are not live control state.

All of these are synchronous engine calls on the isolate that called System.init(); none involves a callback.

Host I/O

A patcher talks to the host three ways:

• In, by name — Patcher.passBang(), passInt, passFloat and passString deliver a value to every .r (Obj.gReceive) object with that name in the patcher.

• Out, by name — Patcher.messages is a broadcast stream of every message the patcher sends to a name no .r in it receives: a .s (Obj.gSend) in the patch, or a pass* call with nothing listening. Each PatcherMessage carries that name and a BusValue (lists arrive as a BusString). The native callback is installed on the first listen and cleared on the last cancel; while it is installed, pass* returns true even for a name nothing receives.

• The bus — in a patcher named foo, a .s x also publishes to patcher.foo.x and a .r x hears a Bus.publish() to that address. See Bus.

The engine calls the send callback on whichever thread emitted the message: the control thread for a pass* or a PHandle.send*, an engine worker thread for a timer-driven one (a millisecond .metro), never the audio thread. The wrapper therefore bridges it with a NativeCallable.listener: messages are queued to the isolate and delivered asynchronously from its event loop, so listeners may call back into the patcher. Every native message block is freed exactly once, including messages still in flight when Patcher.dispose() or System.close() tears the stream down.

PatcherMessage

class PatcherMessage

One message a [Patcher] sent to the host, delivered by [Patcher.messages].

[address] is the name the message was sent to (a .s argument or a pass* target). [value] reuses the bus value vocabulary: a bang is a [BusBang], an int a [BusInt], a float a [BusFloat], and a list or symbol arrives as a [BusString] holding the space-separated atoms.

Constructors

PatcherMessage(this.address, this.value)

Pair an [address] with its [value].

Properties

final String address

The name the message was sent to.

final BusValue value

The typed payload.

int get hashCode

Methods

bool ==(Object other)

String toString()

OutType

Outlet data-type enum returned by PHandle.outputDataType().

enum OutType

enum OutType

Data type produced by a patcher outlet ([PHandle.outputDataType]).

Values match YSE::OUT_TYPE.

Values

invalid

bang

float

integer

buffer

list

any

Constructors

OutType(this.native)

Static methods

static OutType fromNative(raw.YseOutType native)

Maps a raw C-side [raw.YseOutType] to its Dart enum, defaulting to [OutType.invalid] for unknown values.

Properties

final raw.YseOutType native

Registry introspection

Read-only access to the engine’s patcher object registry — the same in-code documentation that drives the Patcher object reference reference. Use PatcherRegistry to enumerate the registered object types and, per type, read the description, category, and inlet / outlet / parameter schema without hard-coding the catalogue.

PatcherRegistry

class PatcherRegistry

Read-only registry of every patcher object type the engine knows about.

The registry is the introspection surface behind the engine’s own patcher reference: it enumerates the object types [Patcher.createObject] accepts and, per type, the documentation metadata (description, category, and the inlet / outlet / parameter schema). Use it to build a node palette or generate documentation without hard-coding the catalogue.

All members are static; there is a single process-wide registry.

Threading: main-thread only, and not real-time safe — never call from the audio callback (CLAUDE.md Boundaries). The engine builds its metadata cache lazily on the first call and keeps it for the life of the process.

Static accessors

static int get typeCount

Number of registered object types.

Static methods

static String typeNameAt(int index)

Type identifier at [index] in the registry (0-based, lexicographic).

Returns the empty string when [index] is out of range.

static List<String> typeNames()

Every registered type identifier, in registry (lexicographic) order.

static PatcherObjectType? type(String typeName)

Metadata handle for [typeName], or null if the registry has no such type. Compare against [Obj] constants, e.g. PatcherRegistry.type(Obj.dSine).

static List<PatcherObjectType> types()

Every registered type as a metadata handle, in registry order.

static String metadataJson()

A fresh JSON snapshot of every registered object’s full metadata.

The result is one JSON object keyed by type name; each entry holds name, category (e.g. OSC, the YSE_PCAT_ suffix), is_dsp, requires_midi_device, description, inlets, outlets and params.

The engine allocates the buffer per call; this getter releases it through yse_free_string before returning, so no native memory leaks. Returns the empty string if the engine reports an allocation failure.

PatcherObjectType

class PatcherObjectType

Read-only metadata for one registered patcher object type.

Obtain one from [PatcherRegistry.type] / [PatcherRegistry.types]. Every accessor reads live from the engine registry; the strings returned are copied out of engine-owned storage (never freed by the caller).

Properties

final String name

The type identifier (matches one of the [Obj] constants).

String get description

Short human-readable summary of the object.

Since libYSE 3.0.1 this is a tooltip-length summary (at most 300 characters, usually one or two sentences), suited to a palette or a hover; the longer notes live in upstream’s object reference.

PCategory get category

Documentation category the object is filed under.

bool get isDsp

Whether this is a DSP / audio-rate object (the ~ prefix convention).

bool get requiresMidiDevice

Whether this object holds a MIDI port (.midiin, .midiout, .notein, …).

Such objects exist only in engine builds with MIDI device support (not macOS / Android), so a palette or a saved patch can mark them non-portable. Read from the registry’s metadata JSON (requires_midi_device); the engine has no dedicated getter.

int get inletCount

Number of inlets on this object type.

int get outletCount

Number of outlets on this object type.

int get paramCount

Number of creation parameters this object type documents.

Methods

PatcherInlet inletAt(int idx)

Metadata for the inlet at [idx] (0-based).

List<PatcherInlet> inlets()

Metadata for every inlet, in order.

PatcherOutlet outletAt(int idx)

Metadata for the outlet at [idx] (0-based).

List<PatcherOutlet> outlets()

Metadata for every outlet, in order.

PatcherParam paramAt(int idx)

Metadata for the creation parameter at [idx] (0-based).

List<PatcherParam> params()

Metadata for every creation parameter, in order.

String toString()

PatcherInlet

class PatcherInlet

Documentation for one inlet of a [PatcherObjectType].

Properties

final String label

Short inlet label (e.g. freq).

final String doc

Longer human-readable description.

final String range

Documented value range (free-form text, may be empty).

final Set<InletAccepts> accepts

The set of message kinds this inlet accepts.

Methods

String toString()

PatcherOutlet

class PatcherOutlet

Documentation for one outlet of a [PatcherObjectType].

Properties

final String label

Short outlet label (e.g. out).

final String doc

Longer human-readable description.

final String range

Documented value range (free-form text, may be empty).

final OutType type

The data type this outlet emits.

Methods

String toString()

PatcherParam

class PatcherParam

Documentation for one creation parameter of a [PatcherObjectType].

Properties

final String name

Parameter name (e.g. frequency).

final String doc

Longer human-readable description.

final String defaultValue

Documented default value (free-form text, may be empty).

final String range

Documented value range (free-form text, may be empty).

Methods

String toString()

Object type constants

The constants on Obj are the string identifiers that Patcher.createObject() accepts. There is one for every type in the engine registry, named after the upstream YSE::OBJ constant (D_SINE becomes dSine), and Obj.all lists them. Pass the constant or pass the raw string literal — they are interchangeable.

The class is generated by tool/gen_obj_constants.dart from the registry of the bound libyse and upstream pObjectList.hpp; rerun it after an engine update (--check reports a stale file).

Every constant on this class is the literal string the engine recognises, e.g. Obj.dSine == '~sine'. The ~ / . prefix convention is the same as upstream: ~ marks audio-rate (DSP) objects, . marks control-rate (event) objects.

Refer to Patcher object reference for the full per-object documentation (inlets, outlets, parameters, ranges).

Obj

class Obj

Compile-time string identifiers for patcher object types.

Pass any of these to [Patcher.createObject] instead of a raw string literal; the two are interchangeable. The ~ prefix marks DSP / audio-rate objects, . marks control-rate objects. Every type in the engine registry has a constant, named after its YSE::OBJ constant in upstream patcher/pObjectList.hpp (D_SINE becomes [dSine]).

[all] lists every constant. For the full per-object schema (inlets, outlets, parameters) use [PatcherRegistry].

Static accessors

static const String dLine

~line: Linear-ramp generator. Ramps an audio-rate value toward a target over a given time in ms.

static const String dNoise

~noise: White-noise generator. Sends a new block of random samples on every audio block.

static const String dSaw

~saw: Audio-rate sawtooth oscillator. Frequency can be set with a float or modulated with a DSP buffer.

static const String dSine

~sine: Audio-rate sine oscillator. Frequency can be set with a float or modulated with a DSP buffer.

static const String dBandpass

~bp: Bandpass filter. Passes a frequency band centered on ‘frequency’ with bandwidth shaped by ‘Q’ (resonance).

static const String dHighpass

~hp: Single-pole highpass filter. Attenuates content below the cutoff frequency.

static const String dLowpass

~lp: Single-pole lowpass filter. Attenuates content above the cutoff frequency.

static const String dVcf

~vcf: Resonant bandpass filter whose center frequency is a signal, so it can sweep at audio rate. Sharpness sets how narrow the band is.

static const String gReverseSubtract

.!-: Subtracts the left operand from the right one and sends right - left as a float: .- with the operands the other way round.

static const String gReverseDivide

.!/: Divides the right operand by the left one and sends right / left as a float: ./ with the operands the other way round. A left operand of 0 sends 0.

static const String gNotEqual

.!=: Sends 1 when the left operand differs from the right one, otherwise 0.

static const String gModulo

.%: Sends the remainder of dividing the left operand by the right one, as an int. The remainder has the sign of the left operand, and a divisor of 0 sends 0.

static const String gBitAnd

.&: Bitwise AND of two integers, sent as an int. Floats are truncated toward zero first.

static const String gLogicalAnd

.&&: Logical AND: sends 1 when both operands are non-zero, otherwise 0.

static const String gMultiply

.*: Multiplies two numbers and sends the product as a float.

static const String gAdd

.+: Adds two numbers. A number on the left inlet is added to the stored right operand, and the sum is sent as a float.

static const String gSubtract

.-: Subtracts the right operand from the left one and sends the difference as a float.

static const String gDivide

./: Divides the left operand by the right one and sends the quotient as a float. Dividing by 0 sends 0.

static const String gLess

.<: Sends 1 when the left operand is less than the right one, otherwise 0.

static const String gShiftLeft

.<<: Shifts the bits of the left operand left by the right operand. A count below 0 shifts nothing, and a count of 32 or more gives 0.

static const String gLessEqual

.<=: Sends 1 when the left operand is less than or equal to the right one, otherwise 0.

static const String gEqual

.==: Sends 1 when the left operand equals the right one, otherwise 0.

static const String gGreater

.>: Sends 1 when the left operand is greater than the right one, otherwise 0.

static const String gGreaterEqual

.>=: Sends 1 when the left operand is greater than or equal to the right one, otherwise 0.

static const String gShiftRight

.>>: Shifts the bits of the left operand right by the right operand, keeping the sign. A count below 0 shifts nothing; past 31, a negative number gives -1 and any other 0.

static const String gAbs

.abs: Sends the absolute value of a number, as a float.

static const String gAccum

.accum: Stores a number you can replace, add to and multiply. A number on the left inlet replaces it and sends it; the middle inlet adds to it and the right inlet multiplies it, without sending.

static const String gAcos

.acos: Sends the arc-cosine of a number, in radians. Numbers outside -1 to 1 send 0.

static const String gAcosh

.acosh: Sends the hyperbolic arc-cosine of a number. Numbers below 1 send 0.

static const String gAnal

.anal: Counts how often each number follows the one before it, and sends ‘<previous> <current> <count>’ for every pair it counts. Wire it into .prob to make .prob play in the style of what it heard.

static const String gAsin

.asin: Sends the arc-sine of a number, in radians. Numbers outside -1 to 1 send 0.

static const String gAsinh

.asinh: Sends the hyperbolic arc-sine of a number.

static const String gAtan

.atan: Sends the arc-tangent of a number, in radians. Use .atan2 for an angle around the full circle.

static const String gAtan2

.atan2: Sends the angle of the point (x, y) in radians, measured from the positive x axis, from -pi to pi. The left inlet takes y and the right inlet x.

static const String gAtanh

.atanh: Sends the hyperbolic arc-tangent of a number. Numbers at or beyond -1 and 1 send 0.

static const String gAtodb

.atodb: Converts a linear amplitude to decibels on the engine’s scale, where an amplitude of 1 is 100 dB and nothing goes below 0 dB. Subtract 100 for decibels relative to full scale.

static const String gCartopol

.cartopol: Converts the point (x, y) to polar form: its distance from the origin on the left outlet and its angle in radians on the right one.

static const String gChange

.change: Passes a number on only when it differs from the previous one. Two more outlets report when the value leaves 0 and when it returns to 0.

static const String gClip

.clip: Limits a number to the range low to high and sends it as a float. A number inside the range passes unchanged; any other becomes the nearest limit.

static const String gCos

.cos: Sends the cosine of an angle in radians, as a float.

static const String gCosh

.cosh: Sends the hyperbolic cosine of a number. Beyond about -89 and 89 the result is too large for a float, and 0 is sent.

static const String gCounter

.counter: Counts bangs. Each bang adds the step to the count and sends the new count as an int; an int on the left inlet sets the count and sends it.

static const String gDbtoa

.dbtoa: Converts decibels on the engine’s scale to a linear amplitude: 100 dB is an amplitude of 1, and 0 dB or less gives 0. The inverse of .atodb.

static const String gIntDivide

.div: Integer division: divides the left operand by the right one and sends the whole quotient as an int, truncated toward zero. A divisor of 0 sends 0.

static const String gExpr

.expr: Evaluates a C-style expression such as ‘$f1 * 2 + $f2’. The placeholders $i1-$i9 and $f1-$f9 create the inlets; the left inlet calculates and sends the result.

static const String frequencyToMidi

.ftom: Converts a frequency in Hz to a MIDI note number, with 440 Hz (A4) at note 69. The result is fractional, so a detuned pitch keeps its offset.

static const String gHisto

.histo: Counts how often each number arrives and sends ‘<number> <count>’ each time. The right inlet reports a number’s count without counting it.

static const String gLinedrive

.linedrive: Maps a number onto an exponential curve: inputMax gives outputMax, and each step below it divides the output by the curve. Lets a linear control, such as a MIDI controller, drive a frequency or a gain evenly.

static const String gMaximum

.maximum: Sends the larger of a number and a stored value. The right inlet sets the stored value; a list sends its largest item.

static const String gMean

.mean: Sends the average of every number received so far, and how many numbers that is. A list sends the average of its own items and starts the average over.

static const String gMinimum

.minimum: Sends the smaller of a number and a stored value. The right inlet sets the stored value; a list sends its smallest item.

static const String midiToFrequency

.mtof: Converts a MIDI note number to a frequency in Hz, with note 69 (A4) at 440 Hz. Fractional note numbers give the frequencies in between.

static const String gPast

.past: Sends a bang when a number rises to or above a threshold, then stays silent until the number drops below it again. With several thresholds, each item of a list must reach its own.

static const String gPeak

.peak: Keeps the largest number received so far and sends it only when a new number beats it. Two more outlets report whether each number set a new peak.

static const String gPoltocar

.poltocar: Converts a polar point, a distance from the origin and an angle in radians, to its x and y coordinates. The inverse of .cartopol.

static const String gPong

.pong: Keeps a number inside the range low to high by folding it back from the limits, the default, by wrapping it around to the other side, or by clipping it. Sends the result as a float.

static const String gPow

.pow: Raises the left operand to the power of the right one and sends the result as a float. Combinations with no finite real result, such as a negative base with a fractional exponent, send 0.

static const String gRound

.round: Rounds a number to the nearest multiple of the step and sends it as a float: a step of 1, the default, rounds to whole numbers and 0.5 to halves. Halfway values round away from zero; a step of 0 passes the number unchanged.

static const String gScale

.scale: Maps a number from the input range onto the output range and sends it as a float. An exponent other than 1 bends the mapping into a curve; numbers outside the input range map past the output range unless clip is 1.

static const String gSin

.sin: Sends the sine of an angle in radians, as a float.

static const String gSinh

.sinh: Sends the hyperbolic sine of a number. Beyond about -89 and 89 the result is too large for a float, and 0 is sent.

static const String gSlide

.slide: Smooths a stream of numbers. Each number moves the output part of the way towards it: 1/slideUp of the distance when rising, 1/slideDown when falling. A slide of 1 passes numbers straight through.

static const String gSqrt

.sqrt: Sends the square root of a number, as a float. A negative number sends 0.

static const String gSwap

.swap: Sends two numbers out in swapped order. A number on the left inlet leaves the right outlet, then the number stored on the right inlet leaves the left outlet.

static const String gTan

.tan: Sends the tangent of an angle in radians, as a float. Where the result would be infinite, it sends 0.

static const String gTanh

.tanh: Sends the hyperbolic tangent of a number: a smooth S-curve between -1 and 1, often used for soft saturation.

static const String gTogedge

.togedge: Bangs the left outlet when a value becomes non-zero and the right outlet when it returns to 0, and stays silent in between. A bang flips the value between zero and non-zero.

static const String gTrough

.trough: Keeps the smallest number received so far and sends it only when a new number goes below it. Two more outlets report whether each number set a new minimum.

static const String gVexpr

.vexpr: Evaluates an expression for every item of a list, as .expr does for single numbers, and sends the results as a list. A single number on an inlet is used for every item.

static const String gZmap

.zmap: Maps a number from the input range onto the output range, in a straight line, and sends it as a float. A number outside the input range gives the nearest output limit, so the result never leaves the output range.

static const String gBitOr

.|: Bitwise OR of two integers, sent as an int. Floats are truncated toward zero first.

static const String gLogicalOr

.||: Logical OR: sends 1 when either operand is non-zero, otherwise 0.

static const String dMultiply

~*: Multiplies an audio signal by another audio signal or by a float: a gain stage, or a ring modulator.

static const String dAdd

~+: Adds two audio signals, or adds a float to an audio signal.

static const String dSubtract

~-: Subtracts an audio signal, or a float, from an audio signal.

static const String dDivide

~/: Divides an audio signal by another audio signal or by a float. A float of 0 leaves the signal unchanged.

static const String dClip

~clip: Hard clipper: limits every sample of an audio signal to the range low to high. Use it to tame stray peaks, or as a distortion stage.

static const String gButton

.b: A button. Any bang or number sends a bang and lights the button until the host next reads it.

static const String gDial

.dial: A knob with its own output range. It takes a position from 0 to 1 and sends it mapped onto minimum-maximum, optionally bent into a curve by an exponent and rounded to an int.

static const String gFloat

.f: A float number box. A number on the left inlet stores it and sends it, a bang sends it again, and the right inlet stores a number without sending it.

static const String gFunction

.function: A breakpoint function, for drawing envelopes and curves. It stores sorted (x, y, curve) points, answers an x with the y between them, and on a bang sends the whole shape as a ramp for .line or .bline. Its points are saved with the patch.

static const String gInt

.i: An integer number box. A number on the left inlet stores it and sends it, a bang sends it again, and the right inlet stores a number without sending it. Floats are truncated.

static const String gIncdec

.incdec: A stepper over a whole number. ‘inc’ and ‘dec’, or a signed step count on the middle inlet, move the value inside a range that clamps or wraps; a number sets it without sending and a bang sends it.

static const String gKslider

.kslider: A piano keyboard. A pitch on the left inlet presses that key at the stored velocity and sends velocity and pitch; velocity 0 releases it. The state is the velocity held on each of the 128 keys.

static const String gList

.l: A list box. A bang sends the stored list; a list arriving on the inlet replaces it without sending it.

static const String gLed

.led: A labelled on/off indicator. It latches by default (a number sets it, a bang flips it) or registers presses with the ‘momentary’ keyword, and sends its state and its label.

static const String gMessage

.m: A message box. A bang sends the stored text as the message it spells: a number, a bang, a list or a command. A message arriving on the inlet replaces the text without sending it.

static const String gMatrixctrl

.matrixctrl: A grid of cells, columns by rows, such as a step pattern or a routing patchbay. ‘<column> <row> <value>’ sets a cell, and every change is sent in that same form, so the grid can drive .matrix or .router directly.

static const String gMultislider

.multislider: A bank of sliders, such as the steps of a sequencer or the bands of an equaliser. A list sets the cells and the bank size, ‘set <index> <value>’ sets one cell, and every message sends the whole bank as a list.

static const String gNodes

.nodes: Blends between circular nodes in a 2D field. Move a cursor with ‘x y’ and it sends each node’s distance and a weight that falls from 1 at the node’s centre to 0 at its edge, scaled so the weights add up to 1.

static const String gNslider

.nslider: A note on a staff: a pitch and how it is spelled. It sends the pitch and its accidental (1 sharp, -1 flat, 0 natural); a black key follows the ‘spelling’ argument unless a message chooses otherwise.

static const String gPreset

.preset: Stores and recalls snapshots of the patch’s controls. ‘store <n>’ captures every control whose value can be restored into slot n, and a number recalls that slot. The slots are saved with the patch.

static const String gRadiogroup

.radiogroup: Radio buttons, or check boxes with ‘multi’, over named items. It works exactly like .umenu; a host draws it as a group of buttons.

static const String gRslider

.rslider: A range control: two ends inside minimum-maximum, such as a key split or a velocity layer. It sends the lower end, the higher end and both as a list, whichever way round the ends were set.

static const String gSlider

.slider: A slider holding a position from 0 to 1. A number sets the position, clamped to that range, and sends it; a bang sends it again.

static const String gToggle

.t: An on/off toggle. An int sets it (0 is off, any other number on), a bang flips it, and every message sends the state as 0 or 1.

static const String gTab

.tab: A row of tabs over named items. It works exactly like .umenu; a host draws it as tabs.

static const String gText

.text: A comment in the patch. It holds its text for a host to display and has no inlets or outlets.

static const String gTextbutton

.textbutton: A button carrying a text label. It works exactly like .led; a host draws it as a labelled button instead of a lamp.

static const String gTextedit

.textedit: An editable text field. Text arriving on the inlet replaces the stored text and is sent on; a bang sends it again. It holds up to 256 characters.

static const String gUmenu

.umenu: A menu of named items. A number or an item name selects an item, and it sends the item number, its name and the whole selection. With ‘multi’, several items can be selected at once.

static const String gXyslider

.xyslider: A two-dimensional pad holding an x and a y, each inside its own bounds, so two parameters move as one gesture. It sends x, y and the pair as a list.

static const String gBline

.bline: Ramps a number to a target one step per bang, so whatever bangs it sets the pace. A list of target/count pairs makes a ramp of several segments; the right outlet bangs when the last target is reached.

static const String gClocker

.clocker: While running, sends the time since it was started, in milliseconds, every interval (5 ms by default). With a clock bound, a second outlet sends the beats that clock has moved in the same time.

static const String gDelay

.delay: Sends a bang a set time after it receives one: 5 ms by default, or a beat time on a domain clock. It holds one bang at a time; a new bang restarts the wait and ‘stop’ cancels it.

static const String gLine

.line: Ramps a number to a target over a given time, sending a value every grain (20 ms by default) and a bang from the right outlet on arrival. A list of target/time pairs makes a ramp of several segments.

static const String gMetro

.metro: Sends a bang at a regular interval while it runs, starting with one bang the moment it starts. The interval is in milliseconds (1000 by default) or a beat time on a domain clock.

static const String gPipe

.pipe: Delays ints, floats and lists by a set time (0 ms by default). It holds up to 64 values at once, and each one keeps the delay it arrived with.

static const String gQlim

.qlim: Limits how often messages pass. A message that arrives before the interval since the last output is up is held and sent when it is up; a newer message replaces it, or with ‘usurp 0’ joins a queue.

static const String gQuickthresh

.quickthresh: Collects values that arrive close together into one list, sent a fixed time (40 ms by default) after the first of them. Made for grouping the notes of a chord.

static const String gSetclock

.setclock: Creates a named domain clock that runs from the start, and sets its tempo: every number it receives is the new tempo in BPM. A bang sends the clock’s beat position.

static const String gSpeedlim

.speedlim: Limits how often messages pass. A message that arrives before the interval since the last output is up is dropped, so a burst comes out as its first message.

static const String gTempo

.tempo: Counts notes on a named domain clock: ‘.tempo main 120 1 16’ sends 0 to 15 in sixteenth notes, over and over. Starting it sets the clock’s tempo.

static const String gThresh

.thresh: Collects values that arrive close together into one list, and sends the list once no new value has arrived for the threshold (10 ms by default).

static const String gTimepoint

.timepoint: Sends a bang once when a named domain clock passes a beat position, as in ‘.timepoint main 128’.

static const String gTimer

.timer: Measures the time between a bang in the left inlet and a bang in the right inlet, in milliseconds and, with a clock name as argument, in beats.

static const String gTranslate

.translate: Converts a time value between milliseconds, hertz, samples, beats and ticks. Converting between real time and beats uses the current tempo of a named domain clock.

static const String gTransport

.transport: Starts, stops and sets the tempo of a named domain clock, creating the clock (stopped) if it does not exist yet. A bang sends the clock’s beat position and tempo.

static const String gWhen

.when: On any input, sends the beat position and tempo of a named domain clock. It only reads the clock and never creates one.

static const String mBendin

.bendin: MIDI pitch-bend input at 7-bit resolution: reports the pitch wheel as 0-127 with 64 at rest. .xbendin reports the full 14 bits.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mBendout

.bendout: Builds a 7-bit MIDI pitch-bend message for .midiout: 0-127 with 64 at rest. .xbendout sends the full 14 bits.

static const String mBorax

.borax: Reports statistics about a stream of notes: serial number, voice, how many notes are sounding, durations and the time between attacks.

static const String mChanPress

.channelpressure: Builds a MIDI channel-aftertouch message for .midiout. Each pressure value on the inlet sends one message.

static const String mControl

.controlchange: Builds a MIDI control-change message for .midiout. Each value on the inlet sends one message, on the controller and channel the arguments set.

static const String mCtlin

.ctlin: MIDI control-change input. Reports the value, controller number and channel of every control change received on a MIDI input port: knobs, faders, wheels and pedals.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mFlush

.flush: Passes pitch/velocity pairs through and remembers which notes are sounding. A bang releases them all with velocity 0.

static const String mMakenote

.makenote: Plays a note: sends a pitch and velocity now, and the same pitch with velocity 0 after a duration in milliseconds.

static const String mMidiflush

.midiflush: Passes a MIDI byte stream through and remembers which notes it left sounding. A bang sends a note-off for each of them.

static const String mFormat

.midiformat: Builds raw MIDI messages from notes, controllers, program changes, pressure and pitch bend. The inverse of .midiparse; each message leaves as a list of byte values.

static const String mIn

.midiin: Raw MIDI input. Every byte received on a MIDI input port leaves the outlet as an int, in arrival order and uninterpreted.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mMidiinfo

.midiinfo: Lists the machine’s MIDI ports. A bang sends the number of ports, then an index and a name for each, so a patch can find a device by name.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mOut

.midiout: Sends MIDI messages to an output port. Each list on the inlet is one message, as byte values or as built by the MIDI sender objects; a few words send common channel-mode messages.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mParse

.midiparse: Splits a raw MIDI byte stream into notes, controllers, program changes, pressure, pitch bend and channel. Messages it does not decode leave the rightmost outlet as bytes.

static const String mMpeconfig

.mpeconfig: Builds the MPE configuration message that tells a device how many member channels an MPE zone uses. A value on the inlet sends it.

static const String mMpeformat

.mpeformat: Builds MPE messages: notes, per-note pitch bend, pressure and slide, on the member channel set by the right inlet. The inverse of .mpeparse.

static const String mMpeparse

.mpeparse: Reads an MPE MIDI stream and reports notes, per-note pitch bend, pressure and slide, each with its channel and the channel’s role in the zone.

static const String mNotein

.notein: MIDI note input. Every note-on and note-off received on a MIDI input port leaves as pitch, velocity and channel; a release reports velocity 0.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mNoteOff

.noteoff: Builds a MIDI note-off message for .midiout. A pitch on the left inlet sends it, with the release velocity stored on the right inlet.

static const String mNoteOn

.noteon: Builds a MIDI note-on message for .midiout. A pitch on the left inlet sends it, with the velocity stored on the right inlet; velocity 0 is a release.

static const String mNrpnin

.nrpnin: Non-registered parameter (NRPN) input. Follows the control changes that select and write a device’s own parameter, and reports each value written with its parameter number and channel.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mNrpnout

.nrpnout: Writes a 14-bit value to a non-registered parameter (NRPN), a device’s own parameter, as four MIDI control-change messages for .midiout.

static const String mOffer

.offer: Stores x,y pairs of ints and hands each y back once: an x with no y waiting looks up its pair, sends the y and deletes the pair.

static const String mPgmin

.pgmin: MIDI program-change input. Reports each program change received on a MIDI input port as 1-128, the numbering most devices display.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mPoly

.poly: Assigns notes to a numbered pool of voices. Each note-on takes a free voice, and its release comes out with the same voice number.

static const String mPolyin

.polyin: MIDI polyphonic key-pressure input. Reports the pressure on each held key separately, as pitch, pressure and channel.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mPolyPress

.polypressure: Builds a MIDI polyphonic key-pressure message for .midiout. A pitch on the left inlet sends it, with the pressure stored on the right inlet.

static const String mProgChange

.programchange: Builds a MIDI program-change message for .midiout. Each program number on the inlet, 0-127 as on the wire, sends one message.

static const String mRpnin

.rpnin: Registered parameter (RPN) input. Follows the control changes that select and write a parameter, and reports each value written with its parameter number and channel.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mRpnout

.rpnout: Writes a 14-bit value to a registered parameter (RPN), such as pitch-bend range, as four MIDI control-change messages for .midiout.

static const String mRtin

.rtin: MIDI clock input. Reports the system real-time messages a sequencer or drum machine sends: timing clock, start, continue, stop and reset.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mStripnote

.stripnote: Passes note-ons and drops releases: a pitch goes through only when its velocity is not 0.

static const String mSustain

.sustain: A sustain pedal for pitch/velocity pairs. While the pedal is down, releases are held back; lifting it sends them all.

static const String mSxformat

.sxformat: Builds a system-exclusive message from a template of constant bytes, placeholders filled from the inlets, and an optional checksum.

static const String mSysexin

.sysexin: System-exclusive input. Every byte of every system-exclusive message received on a MIDI input port leaves as an int, from 240 to 247; other messages are filtered out.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mTouchin

.touchin: MIDI channel-aftertouch input. Reports the pressure on the keys after they are down, as one value for the whole channel.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mXbendin

.xbendin: MIDI pitch-bend input at full 14-bit resolution: reports the pitch wheel as 0-16383 with 8192 at rest.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mXbendin2

.xbendin2: MIDI pitch-bend input reported as its two bytes: the coarse byte, with 64 at rest, and the fine byte below it. Pairs with .xbendout2.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mXbendout

.xbendout: Builds a 14-bit MIDI pitch-bend message for .midiout: 0-16383 with 8192 at rest.

static const String mXbendout2

.xbendout2: Builds a 14-bit MIDI pitch-bend message for .midiout from its coarse and fine bytes, the form .xbendin2 reports.

static const String mXctlin

.xctlin: 14-bit MIDI control-change input. Combines controllers 0-31 with their fine partners 32-63 and reports each move as one value of 0-16383.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mXctlout

.xctlout: Sends a 14-bit controller value as two MIDI control-change messages for .midiout: the coarse half on controller 0-31, then the fine half on that number plus 32.

static const String mXmidiin

.xmidiin: Raw MIDI input framed into messages. Each complete message received on a MIDI input port leaves as one list of byte values, such as 144 60 100.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mXnotein

.xnotein: MIDI note input with release velocity. Reports pitch, velocity, release velocity and channel; a note-off reports velocity 0 and how fast the key came up.

Holds a MIDI port: only in builds with MIDI device support (not macOS / Android).

static const String mXnoteout

.xnoteout: Builds a MIDI note message with release velocity for .midiout. A velocity above 0 sends a note-on; 0 sends a note-off carrying the release velocity.

static const String gBucket

.bucket: A shift register for numbers. Each number pushes the stored values one outlet along and every outlet sends what it holds, each one a step older than the outlet to its left.

static const String gCycle

.cycle: Sends each message out the next outlet in turn, going back to outlet 0 after the last. Use it to deal notes across a bank of voices or to alternate between processing chains.

static const String gDecode

.decode: Sends 1 out the selected outlet and 0 out all the others, to switch a bank of which exactly one member is on. Two more inlets override the selection: one turns every outlet on, the other mutes them all.

static const String gFunnel

.funnel: Merges several inlets onto one outlet, putting the inlet’s number in front of each message so the receiver knows where it came from. The inverse of .spray.

static const String gGate

.gate: Passes messages from its right inlet out one of its outlets, chosen by a number in the left inlet. Outlets count from 1; 0 closes the gate.

static const String gMatrix

.matrix: Routes messages from its data inlets to its outlets as set by connection messages, like .router, but each connection has a gain that scales the numbers passing through. At a gain of 1 messages pass unchanged.

static const String gRoute

.route: Sends a message out the outlet whose selector matches its first item, with that item removed. A message that matches no selector leaves the rightmost outlet unchanged.

static const String gRoutepass

.routepass: Sends a whole message out the outlet whose selector matches its first item, keeping that item on. A message that matches no selector leaves the rightmost outlet unchanged.

static const String gRouter

.router: Routes messages from its data inlets to its outlets, unchanged, as set by connection messages. Any inlet can reach any number of outlets, and the routing can change while the patch runs.

static const String gSel

.sel: Bangs the outlet whose selector matches the input. Anything that matches no selector leaves the rightmost outlet unchanged.

static const String gSplit

.split: Sends a number out the left outlet when it lies between low and high, and out the right outlet when it does not. Both limits are inclusive, and the number is not changed.

static const String gSpray

.spray: Takes a list whose first number is an outlet index and sends the values after it out that outlet and the ones to its right. The inverse of .funnel.

static const String gSwitch

.switch: Passes messages from one of its right-hand inlets to the outlet, chosen by a number in the left inlet. Inlets count from 1; 0 closes the switch.

static const String gBangbang

.bangbang: Sends a bang out every outlet, right to left, whatever arrives. Each outlet’s branch finishes before the next outlet fires, so it orders ‘do this, then that’.

static const String gBondo

.bondo: Holds one value per inlet and sends all of them, right to left, whenever any inlet receives one. Keeps a set of related values together, so nothing downstream sees half an update.

static const String gBuddy

.buddy: Waits until every inlet has received a value, then sends them all at once, right to left, and starts waiting again. Use it to assemble one event from parts that arrive separately.

static const String gIf

.if: Tests a condition and sends one message when it is true and, optionally, another when it is false: ‘$i1 > 64 then bang else out2 $i1’. The condition and the message items use the .expr language.

static const String gLoadbang

.loadbang: Sends a bang when the patch it is in has finished loading, so a saved patch can set up its own starting state. A bang at the inlet sends one by hand.

static const String gLoadmess

.loadmess: Sends its arguments as a message when the patch it is in has finished loading, such as ‘.loadmess 0.5’ to set a gain. A bang at the inlet sends it by hand.

static const String gMatch

.match: Watches a stream of numbers and sends the last few as a list when they match the pattern in its arguments. The word ‘nn’ matches any number, so ‘.match 1 nn 3’ sends ‘1 5 3’ after 1, 5, 3.

static const String gNext

.next: Tells the first message of a burst from the rest: a bang leaves the left outlet when a message starts a new logical event, and the right outlet when it belongs to the same event as the message before it.

static const String gOnebang

.onebang: A one-shot: lets one message through as a bang from the left outlet, then sends every further message out the right outlet until the right inlet re-arms it.

static const String gTrigger

.trigger: Sends its input out every outlet, right to left, converted per outlet to an int, a float, a bang, a list or text, or replaced by a constant. Use it to make the order of two branches explicit.

static const String gUzi

.uzi: Sends a burst of bangs at once, each preceded by its index, then a carry bang when the run is done. The patcher’s loop: ‘.uzi 16’ runs sixteen iterations inside one message.

static const String gAppend

.append: Puts a stored message after every message that arrives and sends the result as one list. Use it to add fixed trailing arguments, such as a channel number, to a computed value.

static const String gIter

.iter: Sends the items of a list out one at a time, first to last, so objects that take single numbers can process each one. A bang sends the last list again.

static const String gJoin

.join: Joins the messages held by several inlets into one list, end to end. Unlike .pack, each inlet holds a whole message of any length. .unjoin splits a list the other way.

static const String gListfunnel

.listfunnel: Sends each item of a list out as a two-item list: its index, then the item. Use it to address items by position with .route, .sel or .spray.

static const String gPack

.pack: Combines values arriving at separate inlets into one list, one element per inlet. Each creation argument sets an element’s type and starting value. Only the leftmost inlet sends the list; .pak sends from every inlet.

static const String gPak

.pak: Combines values arriving at separate inlets into one list, and sends the list whenever any inlet receives a value. Otherwise the same as .pack.

static const String gPrepend

.prepend: Puts a stored message in front of every message that arrives and sends the result as one list. Use it to put a selector word such as ‘note’ or ‘set’ in front of a computed value.

static const String gSubstitute

.substitute: Replaces every item of a message that equals the match with the replacement, anywhere in the message. A message with a replacement leaves the left outlet; one with no match leaves the right outlet unchanged.

static const String gUnjoin

.unjoin: Splits a list into groups of equal size, one group per outlet, and sends whatever is left over out the rightmost outlet. Nothing is dropped. The reverse of .join.

static const String gUnpack

.unpack: Splits a list into its items and sends each one out its own outlet, right to left. Each creation argument sets an outlet’s type and starting value. The reverse of .pack.

static const String gZl

.zl: A list processor with 31 modes: measure, reorder, pick from, search, compare, combine, accumulate or sum a list. The mode word is the first argument and can be changed with ‘mode <name>’.

static const String gAtoi

.atoi: Converts a message into the character codes of its text and holds them: ‘hi’ gives 104 105. A bang sends the held codes again, and the other two inlets add to them or replace them without sending.

static const String gCombine

.combine: Joins the items held in its inlets into one symbol, with nothing between them. Each creation argument is an item and the starting value of its own inlet. By default inlet 0 sends and the other inlets only store.

static const String gFromsymbol

.fromsymbol: Splits a symbol on its separator into a message: with separator /, voice/3/freq becomes ‘voice 3 freq’. A result that is one number or the word bang leaves as an int, a float or a bang. The inverse of .tosymbol.

static const String gItoa

.itoa: Converts character codes into the text they spell and holds it: 104 105 gives ‘hi’. A bang sends the held text again, and the other two inlets add to it or replace it without sending. The inverse of .atoi.

static const String gRegexp

.regexp: Matches messages against a regular expression. Each match leaves with its capture groups, an optional substitution rewrites every match, and a message that does not match leaves the rightmost outlet unchanged.

static const String gSpell

.spell: Spells a message out as the character codes of its text, sent as one list: ‘hi’ gives 104 105. Optional arguments pad a short result to a minimum length with a fill code.

static const String gSprintf

.sprintf: Builds a message from a format with printf-style placeholders: ‘.sprintf /voice/%d/freq’ sends /voice/3/freq for a 3. Each placeholder has its own inlet; inlet 0 formats and sends, the others only store.

static const String gTolower

.tolower: Converts the letters A-Z in a message to lower case and leaves everything else as it was: other characters, spacing and tokens. Put it in front of a .route or .sel to make the match ignore case.

static const String gTosymbol

.tosymbol: Joins the tokens of a message into one symbol, with the separator between them: with separator /, ‘voice 3 freq’ becomes voice/3/freq. A number or a bang becomes the text that spells it.

static const String gToupper

.toupper: Converts the letters a-z in a message to upper case and leaves everything else as it was: other characters, spacing and tokens. The mirror of .tolower.

static const String gBag

.bag: Holds a collection of numbers that a patch adds to and removes from, such as the notes currently held down. A bang sends every number, newest first.

static const String gCapture

.capture: Records every value that reaches it, in arrival order, so a patch can be run and then asked what went past. When full, the oldest item makes room for the newest.

static const String gColl

.coll: Stores messages at number or symbol addresses and sends them back on request: presets, note tables, cue lists. All .coll objects with the same name share one collection.

static const String gFunbuff

.funbuff: Stores (x, y) pairs of ints sorted by x, and sends the y for any x: the stored y, or the one at the nearest lower x. ‘interp’ interpolates between points; ‘next’ steps through them in order.

static const String gTable

.table: A fixed-size array of ints addressed by index, for wavetables, curves and step sequences. It can also be read as a probability distribution: a bang picks a weighted random address.

static const String gTextfile

.textfile: Collects incoming messages as lines of text: each message is added to the current line and ‘cr’ ends it. Lines can be sent back one at a time or all at once, and read from or written to a text file.

static const String gDict

.dict: A key/value store shared by name. Keys nest with ‘::’ (voice::1::freq), a value is any message, and the contents are saved with the patch. A bang sends the reference ‘dictionary <name>’ that the other .dict objects take.

static const String gDictCompare

.dict.compare: Compares two named dictionaries and sends 1 when they hold the same entries, 0 when they do not. On a difference, the key paths that differ follow from the right outlet.

static const String gDictDeserialize

.dict.deserialize: Fills a named dictionary from JSON text, replacing its contents, and sends its reference. Takes a JSON object as a message, or ‘read <file>’ for a larger document.

static const String gDictGroup

.dict.group: Groups a named dictionary’s entries by value into a target dictionary, as ‘<group>::<original path>’. With a key argument, each record is grouped by the value it holds at that key.

static const String gDictIter

.dict.iter: Walks a named dictionary, sending one ‘<path> <value>’ list per entry, then a bang from the right outlet when it is done.

static const String gDictJoin

.dict.join: Merges two named dictionaries into a target dictionary: the left one’s entries, overlaid with the right one’s. Where both hold a key path, the right value wins.

static const String gDictPack

.dict.pack: Builds a named dictionary from its inlets, one inlet per key path: ‘.dict.pack synth freq gain’. The left inlet stores its value, writes the dictionary and sends its reference; the other inlets only store.

static const String gDictPrint

.dict.print: Prints a named dictionary to the engine log as indented JSON, one line per row, each line labelled with the dictionary’s name. A debugging aid with no outlets.

static const String gDictRoute

.dict.route: Sends a named dictionary’s reference out of the outlet of the first key argument it holds, or out of the rightmost outlet when it holds none. Use it to send dictionaries of different shapes to different parts of a patch.

static const String gDictSerialize

.dict.serialize: Sends a named dictionary as one line of JSON text. ‘write <file>’ saves the same JSON to a file instead, for a dictionary too large to send as a message.

static const String gDictSlice

.dict.slice: Splits a named dictionary at a key path. Entries under the path go into the slice dictionary with the path removed from their keys; all other entries go into the remainder dictionary.

static const String gDictStrip

.dict.strip: Removes every entry under a key path from a named dictionary, in place, then sends its reference. An entry stored at exactly the path is kept.

static const String gDictUnpack

.dict.unpack: Sends the values at a named dictionary’s key paths out of separate outlets, one outlet per key path argument, right to left. The inverse of .dict.pack.

static const String gArray

.array: An ordered list of values, shared by every .array with the same name in a patcher. Messages add, change, fetch and remove elements by zero-based index; a bang sends the array’s reference, which the other .array objects accept.

static const String gArrayAt

.array.at: Outputs the element at a position in a named array. Send a position to fetch it, or a list of positions to fetch several at once; a bang fetches the last position again. A position the array does not have bangs the miss outlet.

static const String gArrayChange

.array.change: Reports whether a named array has changed since it was last polled. Each bang sends 1 or 0, and on a change also sends the array’s reference, so work further down only runs when something moved.

static const String gArrayCompare

.array.compare: Compares two named arrays. A bang sends 1 when they hold the same elements in the same order, and 0 when they do not.

static const String gArrayConcat

.array.concat: Outputs the elements of two named arrays as one list: the left array followed by the right. Neither array is changed.

static const String gArrayDeserialize

.array.deserialize: Fills a named array from a JSON array such as [60,62.5,”kick”], replacing its contents. The text is parsed in the background, and the array’s reference is sent once the new contents are in place.

static const String gArrayEvery

.array.every: Tests every number in a named array with an expression. A bang sends 1 when the expression is true (non-zero) for all of them, and 0 when it is false for any.

static const String gArrayExpr

.array.expr: Evaluates an expression for each element of a named array and sends the results as one list, for example $i1 + 12 to transpose. The array itself is not changed.

static const String gArrayFill

.array.fill: Fills a named array with a number of copies of one value, replacing its contents. Use it to clear an array, or to give it a size before writing to it by position.

static const String gArrayFilter

.array.filter: Removes from a named array every element for which an expression is false (zero), keeping the rest in order. Words are removed too, because the expression only sees numbers.

static const String gArrayFlatten

.array.flatten: Outputs the elements of several named arrays as one list, in the order the arrays are named, up to 16 arrays. None of the arrays is changed.

static const String gArrayForeach

.array.foreach: Evaluates an expression for each element of a named array and sends the results one at a time, first to last, then bangs its done outlet.

static const String gArrayGroup

.array.group: Groups the equal elements of a named array. A bang sends one list per distinct value, holding that value as many times as it occurs, then bangs the done outlet.

static const String gArrayIndex

.array.index: Looks up a value in a named array. The position of the first matching element leaves the left outlet; when no element matches, the right outlet bangs.

static const String gArrayIndexmap

.array.indexmap: Reorders a named array by a list of positions: the new array holds the elements at those positions, in that order. Positions may repeat or be left out.

static const String gArrayIndexof

.array.indexof: Outputs the position of the first element of a named array that matches a value, or -1 when no element matches.

static const String gArrayInsert

.array.insert: Inserts a value or a list into a named array at a stored position, moving later elements up. Set the position on the middle inlet, then send what to insert to the left inlet.

static const String gArrayIter

.array.iter: Sends the elements of a named array one at a time, first to last, then bangs its done outlet. Use it to do something for each element.

static const String gArrayJoin

.array.join: Joins the elements of a named array into a single word, with an optional separator between them: c4 e4 g4 joined with - gives c4-e4-g4.

static const String gArrayLength

.array.length: Outputs the number of elements in a named array when it receives a bang.

static const String gArrayMap

.array.map: Applies an expression to every numeric element of a named array and writes the results back, for example $i1 + 12 to transpose. Words stay where they are.

static const String gArrayMax

.array.max: Outputs the largest number in a named array. Words are skipped.

static const String gArrayMean

.array.mean: Outputs the average of the numbers in a named array, as a float. Words are skipped.

static const String gArrayMedian

.array.median: Outputs the median of the numbers in a named array, as a float. Words are skipped, and the array itself is not reordered.

static const String gArrayMin

.array.min: Outputs the smallest number in a named array. Words are skipped.

static const String gArrayMode

.array.mode: Outputs the element that occurs most often in a named array. Words count too, and elements are compared by spelling, so 7 and 7. are different elements.

static const String gArrayPop

.array.pop: Removes the last element of a named array and outputs it. On an empty array, the empty outlet bangs instead.

static const String gArrayPush

.array.push: Appends a value or a list to the end of a named array, then sends the array’s reference. With .array.pop it makes a stack, with .array.shift a queue.

static const String gArrayRandom

.array.random: Outputs a randomly chosen element of a named array. A seed makes the sequence of picks repeat on every run.

static const String gArrayReduce

.array.reduce: Combines the numbers in a named array into one value with an expression, such as $f1 + $f2 for a sum. $f1 is the result so far and $f2 the next element.

static const String gArrayRegexp

.array.regexp: Outputs the elements of a named array that match a regular expression, as one list. When nothing matches, the right outlet bangs. The array itself is not changed.

static const String gArrayRemove

.array.remove: Removes the element at a position from a named array and outputs it; later elements move down. A position the array does not have bangs the miss outlet.

static const String gArrayReplace

.array.replace: Replaces every occurrence of a value in a named array with another value. Sends how many elements were replaced, then the array’s reference.

static const String gArrayReverse

.array.reverse: Reverses the order of the elements of a named array, then sends the array’s reference.

static const String gArrayRotate

.array.rotate: Rotates the elements of a named array by a number of positions, wrapping around the ends. Positive amounts move elements toward the end, negative toward the start.

static const String gArrayRoutepass

.array.routepass: Routes a named array by what it contains: its reference leaves the outlet of the first listed value the array holds, or the rightmost outlet when it holds none of them.

static const String gArrayScramble

.array.scramble: Shuffles the elements of a named array into a random order, and sends the order it applied so another array can be put in the same order. The same object as .array.shuffle.

static const String gArraySect

.array.sect: Outputs the elements two named arrays have in common, each once, as one list in the left array’s order. Neither array is changed.

static const String gArrayShift

.array.shift: Removes the first element of a named array and outputs it; the other elements move down one position. On an empty array, the empty outlet bangs instead.

static const String gArrayShuffle

.array.shuffle: Shuffles the elements of a named array into a random order, and sends the order it applied so another array can be put in the same order. The same object as .array.scramble.

static const String gArraySlice

.array.slice: Outputs a range of elements of a named array, from a start position up to but not including an end position. The array itself is not changed.

static const String gArraySome

.array.some: Tests the numbers in a named array with an expression. A bang sends 1 when the expression is true (non-zero) for at least one of them, and 0 when it is true for none.

static const String gArraySort

.array.sort: Sorts the elements of a named array, ascending or descending, with numbers before words. Also sends the order it applied, so another array can be put in the same order.

static const String gArraySplit

.array.split: Splits a named array in two at a position: the elements before it leave the left outlet and the rest leave the right outlet, right first. The array itself is not changed.

static const String gArrayStddev

.array.stddev: Outputs the standard deviation of the numbers in a named array, as a float. Words are skipped.

static const String gArrayStream

.array.stream: Appends incoming values to a named array and keeps only the most recent ones: a sliding window of a set size. Sends the array’s reference each time the window is full.

static const String gArraySub

.array.sub: Outputs a range of elements of a named array, both ends included; with the end before the start, the range is sent in reverse. The same object as .array.subarray.

static const String gArraySubarray

.array.subarray: Outputs a range of elements of a named array, both ends included; with the end before the start, the range is sent in reverse. The same object as .array.sub.

static const String gArrayThin

.array.thin: Removes elements of a named array that repeat the element kept before them. With a tolerance, numbers that close to it count as repeats too, which thins out a stream of values that barely change.

static const String gArrayTolist

.array.tolist: Outputs all elements of a named array as one list. An array of one element sends that element as a single int, float or symbol.

static const String gArrayTostring

.array.tostring: Outputs all elements of a named array as one text message, separated by spaces. Unlike .array.tolist, a single number is sent as text, ready for objects that work on text.

static const String gArrayTosymbol

.array.tosymbol: Joins all elements of a named array, without spaces, into one symbol: kick and .wav become kick.wav. The result is always a symbol, even when it looks like a number.

static const String gArrayTuplewise

.array.tuplewise: Combines two named arrays position by position with an expression, such as $f1 + $f2, and outputs the results as one list. The result is as long as the shorter array.

static const String gArrayUnion

.array.union: Outputs the elements held by either of two named arrays, each once, as one list. Neither array is changed.

static const String gArrayUnique

.array.unique: Outputs the elements of a named array with repeats removed, each at its first occurrence. The array itself is not changed.

static const String gArrayUnshift

.array.unshift: Inserts a value or a list at the front of a named array, moving the other elements up, then sends the array’s reference.

static const String gArrayWrap

.array.wrap: Outputs the element at a position in a named array, wrapping around: positions past the end start again at the beginning, and -1 is the last element.

static const String gDecide

.decide: A coin flip: each bang sends 0 or 1 with equal chance. Use it for random branching, fills and gating.

static const String gDrunk

.drunk: A random walk: each bang moves the value up or down by a small random step and sends it, kept within 0 to range-1. Successive values drift rather than jump.

static const String gProb

.prob: A Markov chain of weighted transitions between numbered states. Each bang jumps from the current state to a next one, chosen by weight, and sends it.

static const String gRandom

.random: Sends a random integer from 0 to range-1 on each bang, every value equally likely.

static const String gUrn

.urn: Random numbers without repeats: each bang sends a number from 0 to limit-1 that has not come out yet, like dealing from a shuffled deck. When all have been sent, the right outlet bangs.

static const String gForward

.forward: Sends what arrives to every .r with a given name, like .s, but the name can be changed with a message to the right inlet. Sends nothing until it has a destination.

static const String gPrint

.print: Writes every message that arrives to the engine log, one line each, with a name in front. Use it to watch values pass through a patch.

static const String gReceive

.r: Sends out whatever is sent to its name: by a .s or .forward in this patcher or in a patcher with the same name, by the host’s PassData, or on the named bus.

static const String gSend

.s: Sends what arrives to every .r with the same name, without a cord. It also publishes on the named bus as ‘patcher.<patcherName>.<name>’, so other patchers and the host can listen.

static const String gValue

.value: Holds a value shared by every .value with the same name. A value at the inlet is stored for all of them without being sent; a bang sends out what is stored.

static const String dAdc

~adc: The patch’s audio input. When the patcher runs as an insert effect, each outlet carries one channel of the audio it processes.

static const String dDac

~dac: The patch’s audio output. Each inlet is one output channel, passed on to the sound or insert that hosts the patcher. A patch is silent until a signal reaches this object.

static const String gInlet

.inlet: A message inlet of the subpatcher it is in. With index N, whatever the parent sends to the subpatcher’s inlet N comes out of this object, inside the subpatcher.

static const String gOutlet

.outlet: A message outlet of the subpatcher it is in. With index N, whatever arrives here leaves the subpatcher through its outlet N.

static const String patcher

patcher: A subpatcher: groups part of a patch into one object that the parent connects to by pin number. Its pins are the .inlet, .outlet, ~inlet and ~outlet objects placed inside it.

static const String dInlet

~inlet: A signal inlet of the subpatcher it is in. With index N, the signal the parent connects to the subpatcher’s inlet N comes out of this object, inside the subpatcher.

static const String dOutlet

~outlet: A signal outlet of the subpatcher it is in. With index N, the signal that arrives here leaves the subpatcher through its outlet N.

static const String gMtr

.mtr: A multi-track recorder for messages: records what arrives on each track inlet with its timing, and plays it back out of the matching outlet in the same rhythm. Each track can be recorded, played, muted and stepped on its own.

static const String gQlist

.qlist: A cue list: lines of numbers and messages played back in time. A line of numbers is sent out and its first number is the wait before the next line; a line starting with a word is sent to the receivers of that name.

static const String gSeq

.seq: Records a stream of raw MIDI bytes with its timing and plays it back. Reads and writes standard MIDI files; playback can follow its own clock, incoming ticks or a YSE domain clock.

static const List<String> all

Every constant above, in registry (type-name) order.

Static methods

static bool isValid(String type)

Whether [type] is a known object type identifier.