Input and output

Audio in and out of the graph, named send/receive, and host-facing I/O.

7 objects. Every entry is pulled directly from the engine registry, which reads the ADD_DESCRIPTION / INLET_DOC / OUTLET_DOC / PARAM_DOC macros in the libYSE source; the longer notes under each summary are ported from the libYSE documentation. The ~ prefix marks DSP / audio-rate objects; . marks control-rate objects. Links into the patcher guide (messages, time, data, files, …) lead to the libYSE documentation, which also has this category’s page.

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

Dart:

Obj.gForward

Kind:

Control-rate

Values go out exactly as from a .s with the current destination as its name (see .s).

The right inlet sets the destination. A list sets it to its first word; an int sets it to the number spelled out, so 7 reaches a .r 7. A float or a bang there is ignored, as is a name longer than 63 characters or an empty one; the old destination stays. Without a destination, nothing is sent.

[.forward]   right <- left       then   left <- 3   =>   .r left: 3
             right <- right      then   left <- 4   =>   .r right: 4

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	Bang, int, float or list, sent unchanged to the current destination. No word is reserved.
1	destination	INT, LIST	any name, at most 63 characters	Sets the destination name: the first word of a list, or the digits of an int. A name longer than 63 characters is ignored.

Parameters

Name	Default	Range	Description
destination	—	any name, at most 63 characters	The starting destination. Empty sends nothing until one is set.
globalOnly	0	0 or 1	1 sends only on the named bus, not inside the patcher.

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

Dart:

Obj.gPrint

Kind:

Control-rate

Each message becomes one log line: the name, a colon, then the message.

• A bang prints bang. An int prints its digits.

• A float always has a decimal point, so 440. stays visibly a float.

• A list or a message box’s text prints as it is.

The line reaches the log on the next System.instance.update() tick, tagged (App Message). Catch it with Log.instance.messages.

Limits

• A line longer than about 240 characters is cut and ends in ....

• Each object prints at most 16 lines per update tick, or the number given as its second argument (1-256). The first line over the limit in a tick logs a notice.

• The queue is shared by every .print. Lines that do not fit are counted, and the next update logs how many were lost.

Nothing is dropped silently. .print has no outlet. See Talking to the host.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	Any message. Each one is written to the engine log as one line, after this object’s name.

Parameters

Name	Default	Range	Description
name lines	print 16	name: any symbol, up to 32 characters; optional lines 1-256	The name printed before each line (default ‘print’, cut at 32 characters), then the most lines this object prints per update tick (default 16, clamped to 1-256).

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

Dart:

Obj.gReceive

Kind:

Control-rate

.r <name> sends out everything sent to that name: by a .s or .forward in the same patcher, by one in another patcher with the same name, by the host’s Patcher.passInt / passFloat / passString and Patcher.passBang, or by a publish on the bus address patcher.<patcherName>.<name>. A cord into its inlet is passed straight through.

Values that come from the bus are sent out on the control thread. The bus subscription only exists while the engine is running, so create patchers after System.instance.init(). Talking to the host covers when each route delivers.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	Bang, int, float or list, passed straight to the outlet.

Outlets

#	Label	Type	Range	Description
0	out	ANY	—	Every value sent to this name.

Parameters

Name	Default	Range	Description
dataName	—	any name, at most 63 characters	The name to listen to. A name longer than 63 characters is refused and logged, and the object receives nothing.
globalOnly	0	0 or 1	Accepted for symmetry with .s, and ignored.

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

Dart:

Obj.gSend

Kind:

Control-rate

.s <name> delivers each value in two ways:

• Inside the patcher, to every .r <name>, including those in subpatchers. A value sent while the patch renders arrives in the same block; one sent from the control thread arrives at the start of the next.

• On the named bus, at patcher.<patcherName>.<name>. A .r <name> in another patcher with the same name, a bus subscriber in the host and a Python script all receive it there. The patcher’s own .r objects ignore this copy, so each gets every value once.

With globalOnly set to 1 (.s <name> 1) the value only goes out on the bus, and the patcher’s own .r objects get it from there too.

The audio thread can only put ints and floats on the bus. A bang or list sent while the patch renders reaches the patcher’s own .r objects and nothing else, and with globalOnly set it reaches nothing at all. When nothing in the patcher listens to the name, the host’s send callback gets the value instead, unless it was sent while the patch renders.

Talking to the host covers the bus, the send callback, the scope rules and the length limits.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	Bang, int, float or list to send.

Parameters

Name	Default	Range	Description
dataName	—	any name, at most 63 characters	The name to send to. A name longer than 63 characters is refused and logged, and the object sends nowhere.
globalOnly	0	0 or 1	1 sends only on the named bus, not inside the patcher.

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

Dart:

Obj.gValue

Kind:

Control-rate

Every .value with the same name in a patcher, and in patchers with the same name, shares one value. Storing sends nothing and publishes nothing; to react to changes as well, send the value to a .value and a .s from the same outlet.

The starting value comes from the arguments after the name (.value tempo 120, .value pos 0 0). A single number is an int or a float as written, so 120 and 120. differ. Only the .value that creates the shared value applies its starting value; a later one adopts what is stored, so adding a reader never resets it.

See Talking to the host for reading and writing a .value from the host.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	An int, float or list stores a new value. A bang sends out the stored value. A list longer than 256 characters is refused.

Outlets

#	Label	Type	Range	Description
0	out	ANY	—	The stored value, on a bang. Nothing until a value has been stored.

Parameters

Name	Default	Range	Description
valueName	—	any name	The shared name. Without one the object has a private value.
initial	—	any int, float or list	The starting value: the rest of the arguments, so ‘0 0’ is a list. Only the first .value with this name applies it.

~adc

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

Dart:

Obj.dAdc

Kind:

DSP (audio-rate)

There is one outlet per channel of the patcher, as set by Patcher(mainOutputs: ...). The outlets only carry audio when the patcher runs as an insert effect. When it is a sound source there is no incoming audio and they stay silent; outlets beyond the host’s channel count also stay silent. See Patcher.

Outlets

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

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

Dart:

Obj.dDac

Kind:

DSP (audio-rate)

There is one inlet per channel of the patcher, as set by Patcher(mainOutputs: ...). A patch can hold several ~dac objects. Their channels are added together without scaling, so keep the combined level in range. See Patcher for running a patch as a sound or as an insert.

Inlets

#	Label	Accepts	Range	Description
0	in	BUFFER	-1.0 to 1.0	One channel of the patch’s audio output.
1	in	BUFFER	-1.0 to 1.0	One channel of the patch’s audio output.