Patcher object reference

Every patcher object that patcher::CreateObject knows about. Each entry shows the object’s description, inlet/outlet/parameter documentation pulled directly from the engine source via the ADD_DESCRIPTION / INLET_DOC / OUTLET_DOC / PARAM_DOC macros (see YseEngine/patcher/pObject.h).

The ~ prefix marks DSP / audio-rate objects; . marks control-rate objects.

Oscillators

~noise

White-noise generator. Emits a fresh DSP buffer of pseudo-random samples on every audio frame.

Kind:

DSP (audio-rate)

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	-1.0 to 1.0	White-noise audio output.

~saw

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

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	freq	BUFFER, FLOAT	0-20000 Hz	Oscillator frequency in Hz. Accepts a DSP buffer (FM) or a float.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	-1.0 to 1.0	Sawtooth wave audio output.

Parameters

Name	Default	Range	Description
frequency	440	0-20000 Hz	Initial frequency in Hz.

~sine

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

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	freq	BUFFER, FLOAT	0-20000 Hz	Oscillator frequency in Hz. Accepts a DSP buffer (FM) or a float.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	-1.0 to 1.0	Sine wave audio output.

Parameters

Name	Default	Range	Description
frequency	440	0-20000 Hz	Initial frequency in Hz.

Filters

~bp

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

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	in	BUFFER	-1.0 to 1.0	Audio input buffer.
1	freq	FLOAT	0-20000 Hz	Center frequency in Hz.
2	Q	FLOAT	0.1-100	Resonance / inverse bandwidth — higher narrows the band.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	-1.0 to 1.0	Filtered audio output.

Parameters

Name	Default	Range	Description
frequency	0	0-20000 Hz	Initial center frequency in Hz.
Q	0	0.1-100	Initial Q / resonance.

~hp

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

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	in	BUFFER	-1.0 to 1.0	Audio input buffer.
1	cutoff	FLOAT	0-20000 Hz	Cutoff frequency in Hz.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	-1.0 to 1.0	Filtered audio output.

Parameters

Name	Default	Range	Description
frequency	0	0-20000 Hz	Initial cutoff frequency in Hz.

~lp

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

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	in	BUFFER	-1.0 to 1.0	Audio input buffer.
1	cutoff	FLOAT	0-20000 Hz	Cutoff frequency in Hz.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	-1.0 to 1.0	Filtered audio output.

Parameters

Name	Default	Range	Description
frequency	0	0-20000 Hz	Initial cutoff frequency in Hz.

~vcf

Voltage-controlled (heterodyne) filter. Mixes the input with a center-frequency buffer; sharpness controls resonance. Emits real and imaginary components on two buffer outlets.

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	in	BUFFER	-1.0 to 1.0	Audio input buffer.
1	center	BUFFER	-1.0 to 1.0	Center-frequency buffer (typically a sine at the target frequency).
2	sharpness	FLOAT	0.0-1.0	Resonance / sharpness control.

Outlets

#	Label	Type	Range	Description
0	real	BUFFER	-1.0 to 1.0	Real component of the filtered signal.
1	imag	BUFFER	-1.0 to 1.0	Imaginary component of the filtered signal.

Parameters

Name	Default	Range	Description
sharpness	0	0.0-1.0	Initial resonance / sharpness.

Math

.*

Control-rate multiply. Emits left * right as a float whenever inlet 0 fires.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand — fires the multiplication.
1	right	FLOAT, INT	any float	Right operand — stored until next multiply.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	left * right.

Parameters

Name	Default	Range	Description
right	0	any float	Initial right-operand value.

.+

Control-rate add. Emits left + right as a float whenever inlet 0 fires.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand — fires the addition.
1	right	FLOAT, INT	any float	Right operand — stored until next add.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	left + right.

Parameters

Name	Default	Range	Description
right	0	any float	Initial right-operand value.

.-

Control-rate subtract. Emits left - right as a float whenever inlet 0 fires.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand — fires the subtraction.
1	right	FLOAT, INT	any float	Right operand — stored until next subtract.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	left - right.

Parameters

Name	Default	Range	Description
right	0	any float	Initial right-operand value.

./

Control-rate divide. Emits left / right as a float whenever inlet 0 fires; division by zero emits 0.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	left	FLOAT, INT	any float	Left operand — fires the division.
1	right	FLOAT, INT	any float	Right operand — stored until next divide. Zero forces output to 0.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	left / right (or 0 when right == 0).

Parameters

Name	Default	Range	Description
right	0	any float	Initial right-operand value.

.counter

Step counter. Bang increments the current value by ‘step’ and emits it. Send ‘reset’ as a list to return to startValue.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	control	INT, BANG, LIST	any int	Bang to step / int to set the value / list ‘reset’ to return to startValue.
1	step	INT	any int	Sets the increment used on each bang.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	Current counter value.

Parameters

Name	Default	Range	Description
startValue	0	any int	Initial counter value (and the value ‘reset’ returns to).
step	1	any int	Increment applied on each bang.

.ftom

Converts a frequency in Hz to its MIDI note number (with A4 == 69, fractional output).

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	freq	FLOAT, INT	0-20000 Hz	Frequency in Hz.

Outlets

#	Label	Type	Range	Description
0	midi	FLOAT	any float	MIDI note number — fractional.

.mtof

Converts a MIDI note number (with A4 == 69) to its frequency in Hz.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	midi	FLOAT, INT	0-127	MIDI note number — fractional values are supported.

Outlets

#	Label	Type	Range	Description
0	freq	FLOAT	8.18-12543 Hz	Frequency in Hz.

.random

Random integer generator. On bang, emits a uniformly distributed integer in [0, range).

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	bang	BANG	—	Trigger — emits a fresh random integer.
1	range	FLOAT, INT	1+	Sets the exclusive upper bound of the output range.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 to range-1	Random integer in [0, range).

Parameters

Name	Default	Range	Description
range	2	1+	Initial exclusive upper bound.

~*

Audio-rate multiply. Multiplies the left buffer by either the right buffer (audio-rate) or the right float (control-rate). The canonical ‘gain’ / ring-mod node.

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	left	BUFFER	any float	Left operand — audio buffer.
1	right	BUFFER, FLOAT	any float	Right operand — audio buffer or float (gain).

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	left * right.

Parameters

Name	Default	Range	Description
right	1.0	any float	Initial right-operand float (used until a buffer arrives on inlet 1).

~+

Audio-rate add. Sums the left buffer with either the right buffer (audio-rate) or the right float (control-rate).

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	left	BUFFER	any float	Left operand — audio buffer.
1	right	BUFFER, FLOAT	any float	Right operand — audio buffer or float.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	left + right.

Parameters

Name	Default	Range	Description
right	1.0	any float	Initial right-operand float (used until a buffer arrives on inlet 1).

~-

Audio-rate subtract. Subtracts either the right buffer (audio-rate) or the right float (control-rate) from the left buffer.

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	left	BUFFER	any float	Left operand — audio buffer.
1	right	BUFFER, FLOAT	any float	Right operand — audio buffer or float.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	left - right.

Parameters

Name	Default	Range	Description
right	1.0	any float	Initial right-operand float (used until a buffer arrives on inlet 1).

~/

Audio-rate divide. Divides the left buffer by either the right buffer (audio-rate) or the right float (control-rate). A right-float of 0 is silently treated as a no-op.

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	left	BUFFER	any float	Left operand — audio buffer.
1	right	BUFFER, FLOAT	any non-zero float	Right operand — audio buffer or float (non-zero).

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	left / right.

Parameters

Name	Default	Range	Description
right	1.0	any non-zero float	Initial right-operand float (used until a buffer arrives on inlet 1). 0 disables division.

Generic / routing

.gate

Demultiplexer. Routes a value inlet to one of N outlets, selected by inlet 0. activeOutlet=0 silences output; 1-based otherwise.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	select	INT	0+	1-based outlet index to forward to (0 = mute).
1	in	FLOAT, INT, BANG, LIST	—	Value inlet — accepts bang / int / float / list.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	—	Outlet 0 — emits the routed value when select == 1.
1	out1	ANY	—	Outlet 1 — emits the routed value when select == 2.

Parameters

Name	Default	Range	Description
numOutlets	2	1+	Number of value outlets (additional outlets are created by SetParams).

.r

Named receive endpoint. Forwards values arriving from any matching gSend (same dataName) in the patcher, and from any gSend in any patcher with the same name via the global bus (“<patcherName>.<dataName>”).

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	Wired inlet (rarely used — receives typically pair with gSend by name).

Outlets

#	Label	Type	Range	Description
0	out	ANY	—	Forwarded value from matching gSend nodes.

Parameters

Name	Default	Range	Description
dataName	—	any identifier	Name to listen for; must match the dataName of one or more gSend nodes.
globalOnly	0	0 or 1	Reserved for future receive-side filters; ignored today (the bus subscription is always active).

.route

Match-and-route. Compares the incoming value to each token in the list parameter and forwards to the matching outlet; unmatched values go to the final fall-through outlet. Outlets are created when the list parameter is set.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	Value inlet — accepts bang / int / float / list.

Parameters

Name	Default	Range	Description
list	—	any tokens	Space-separated list of match tokens; one outlet is created per token plus one fall-through outlet.

.s

Named send endpoint. Broadcasts incoming values to every gReceive in the patcher whose dataName matches, and publishes them on the global bus as “<patcherName>.<dataName>” so cross-patcher routing works without explicit wiring.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	Value inlet — accepts bang / int / float / list.

Parameters

Name	Default	Range	Description
dataName	—	any identifier	Name to broadcast on; matching gReceive nodes will emit the forwarded value.
globalOnly	0	0 or 1	When 1, skip in-patcher delivery and publish only to the global bus.

.switch

Selector switch. Routes one of N value inlets to a single outlet, chosen by the index on inlet 0. The number of value inlets is set by the numInlets parameter.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	select	INT	0+	Index (0-based) of the value inlet to forward.
1	in0	FLOAT, INT, BANG, LIST	—	Value inlet 0 — accepts bang / int / float / list.
2	in1	FLOAT, INT, BANG, LIST	—	Value inlet 1 — accepts bang / int / float / list.

Outlets

#	Label	Type	Range	Description
0	out	ANY	—	Forwarded value from the currently selected inlet.

Parameters

Name	Default	Range	Description
numInlets	2	1+	Number of value inlets (additional inlets are created by SetParams).

~adc

Audio input into a patcher graph. When the patcher runs as a channel or sound insert, each outlet carries one channel of the host’s incoming audio, so the graph can process external audio rather than only generating it.

Kind:

DSP (audio-rate)

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	-1.0 to 1.0	One channel of the host’s incoming audio, injected into the graph.
1	out	BUFFER	-1.0 to 1.0	One channel of the host’s incoming audio, injected into the graph.

~line

Linear-ramp generator. Ramps an audio-rate value toward a target over a given time in ms. The ‘stop’ message freezes the ramp at the current value.

Kind:

DSP (audio-rate)

Inlets

#	Label	Accepts	Range	Description
0	target	FLOAT	any float	Target value to ramp toward.
1	time	FLOAT	0+ ms	Ramp duration in milliseconds.

Outlets

#	Label	Type	Range	Description
0	out	BUFFER	any float	Audio-rate ramp output.

Parameters

Name	Default	Range	Description
target	0	any float	Initial target value.
time	0	0+ ms	Initial ramp time in milliseconds.

GUI controls

.b

Momentary button. Any input (bang/int/float) lights the button until the next GUI poll; emits a bang on every calculate tick.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	FLOAT, INT, BANG	—	Press — bang/int/float all light the button.

Outlets

#	Label	Type	Range	Description
0	out	BANG	—	Bang emitted on every calculate tick.

.f

Float number box. Stores a float; inlet 0 sets-and-fires (bang re-emits the current value), inlet 1 sets silently.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	set/bang	FLOAT, INT, BANG	any float	Sets the value and emits it; bang re-emits the current value.
1	silent set	FLOAT, INT	any float	Silently updates the stored value without emitting.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	any float	Current float value.

Parameters

Name	Default	Range	Description
value	0	any float	Initial value.

.i

Integer number box. Stores an int; inlet 0 sets-and-fires (bang re-emits the current value), inlet 1 sets silently.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	set/bang	FLOAT, INT, BANG	any int	Sets the value and emits it; bang re-emits the current value.
1	silent set	FLOAT, INT	any int	Silently updates the stored value without emitting.

Outlets

#	Label	Type	Range	Description
0	out	INT	any int	Current integer value.

Parameters

Name	Default	Range	Description
value	0	any int	Initial value.

.l

Static list. Bang re-sends the stored list; list updates the stored payload.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger/set	BANG, LIST	—	Bang re-sends the stored list; list replaces it.

Outlets

#	Label	Type	Range	Description
0	out	LIST	—	Stored list payload.

Parameters

Name	Default	Range	Description
message	—	any string	Initial list payload.

.m

Static message. Bang re-sends the stored message; list updates the stored payload.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger/set	BANG, LIST	—	Bang re-sends the stored message; list replaces it.

Outlets

#	Label	Type	Range	Description
0	out	LIST	—	Stored message broadcast as a SetMessage.

Parameters

Name	Default	Range	Description
message	—	any string	Initial message payload.

.slider

Slider control. Stores a normalized float in [0, 1]; ints/floats are clamped on input. Emits the stored value on every calculate tick.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	set/bang	FLOAT, INT, BANG	0.0-1.0	Sets the slider position; bang is a no-op trigger that still fires the output.

Outlets

#	Label	Type	Range	Description
0	out	FLOAT	0.0-1.0	Current slider value (clamped to [0, 1]).

.t

Latching on/off toggle. Int sets the state directly (0 = off, non-zero = on); bang flips it. Emits 0 or 1 every calculate tick.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	set/toggle	INT, BANG	0 or 1	Int sets state (0 = off, !=0 = on); bang flips the current state.

Outlets

#	Label	Type	Range	Description
0	out	INT	0 or 1	Current state — 0 or 1.

.text

Text label. Holds a string parameter for display; no inlets, no outlets — purely a visual annotation.

Kind:

Control-rate

Parameters

Name	Default	Range	Description
text	—	any string	Label text.

Time

.metro

Periodic bang generator. Once toggled on, emits a bang every ‘period’ milliseconds (and immediately on start). Toggle off to stop.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	on/off	INT	0 or 1	Non-zero int starts the metronome; 0 stops it.
1	period	FLOAT, INT	1+ ms	Sets the bang interval in milliseconds.

Outlets

#	Label	Type	Range	Description
0	out	BANG	—	Periodic bang.

Parameters

Name	Default	Range	Description
period	1000	1+ ms	Initial interval in milliseconds.

MIDI

.channelpressure

MIDI Channel Pressure (aftertouch) message generator. Emits a status/value MIDI packet on every value change.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	pressure	INT	0-127	Aftertouch pressure value (also fires the output).

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Encoded MIDI Channel Pressure message.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel offset (0-based).

.controlchange

MIDI Control Change message generator. Emits a 3-byte status/controller/value packet on every value change.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	value	INT	0-127	Controller value (also fires the output).

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Encoded MIDI Control Change message.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel offset (0-based).
controller	0	0-127	Controller number.

.midiout

MIDI device output. Sends raw MIDI byte lists to the selected hardware port; understands ‘allnotesoff’, ‘reset’, ‘omni on/off’, ‘poly on/off’, and ‘local control on/off’ as control messages.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	midi	LIST	—	Raw MIDI byte list to send to the device.

Parameters

Name	Default	Range	Description
port	0	device-dependent	Index of the output MIDI port.

.noteoff

MIDI Note-Off message generator. Inlet 0 fires the message; emits a 3-byte status/pitch/velocity packet as a list.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	pitch	INT	0-127	MIDI note number (also fires the output).
1	velocity	INT	0-127	Release velocity (stored until next pitch).

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Encoded MIDI Note-Off message (status, pitch, velocity).

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel offset (0-based).

.noteon

MIDI Note-On message generator. Inlet 0 fires the message; emits a 3-byte status/pitch/velocity packet as a list.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	pitch	INT	0-127	MIDI note number (also fires the output).
1	velocity	INT	0-127	Note velocity (stored until next pitch).

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Encoded MIDI Note-On message (status, pitch, velocity).

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel offset (0-based).

.polypressure

MIDI Polyphonic Key Pressure message generator. Inlet 0 fires the message with the stored pressure value.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	pitch	INT	0-127	MIDI note number (also fires the output).
1	pressure	INT	0-127	Pressure value for the note (stored until next pitch).

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Encoded MIDI Poly Key Pressure message.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel offset (0-based).

.programchange

MIDI Program Change message generator. Emits a status/program packet on every value change.

Kind:

Control-rate

Inlets

#	Label	Accepts	Range	Description
0	program	INT	0-127	Program number (also fires the output).

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Encoded MIDI Program Change message.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel offset (0-based).