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.

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.

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

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.

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

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