Routing#

Steering messages between inlets and outlets.

13 objects. Every entry is 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.

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

Kind:: Control-rate

By default the register runs one step behind: a number first sends what the register holds, then shifts and stores itself at outlet 0. It shows up on the next input. With echo mode on (a non-zero second argument), the number is stored first and is part of the same burst.

[.bucket 3]     1, 2, 3   =>  (out0 out1 out2)  0 0 0,  1 0 0,  2 1 0
[.bucket 3 1]   1, 2, 3   =>  (out0 out1 out2)  1 0 0,  2 1 0,  3 2 1

Every outlet sends on every input, the last outlet first and outlet 0 last (see Messages and dispatch). A value keeps the int or float type it arrived with.

Messages

a number: shift and send.
a list that starts with a number: each number is fed in on its own, as if sent separately. Words in the list are skipped.
bang: send the stored values without shifting.
set <n>: fill every stage with n and send it out every outlet.
clear: set every stage to 0 without sending anything.
freeze: stop all output, including bang, set and roll, while numbers go on shifting in. thaw turns output back on; it sends nothing by itself, so follow it with a bang to see what was collected.
L2R / R2L: new values enter at outlet 0 (the default) or at the last outlet. Spelled in capitals.
roll: feed the value at the far end, the one the next input would push out, back in as the input. The register rotates and nothing is lost. A number after roll is ignored.

Any other message is ignored. The direction and the freeze are not saved, and changing the arguments starts again from zeros.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	A number shifts the register and every outlet sends. A bang sends without shifting. A list of numbers is fed in one number at a time. Also takes ‘set <n>’, ‘clear’, ‘freeze’, ‘thaw’, ‘L2R’, ‘R2L’ and ‘roll’.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	any	The value this stage holds: outlet 0 the newest, each outlet to its right one step older (the other way round after ‘R2L’). A value keeps its int or float type.

Parameters

Name	Default	Range	Description
outlets	1	1-256, optional echo flag	How many outlets (stages) to build. A non-zero second number turns on echo mode: the number that just arrived is sent in the same burst instead of the next one.

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

Kind:: Control-rate

Messages

bang, int or float: goes out the next outlet whole.
a list that starts with a number: dealt one item per outlet, each number keeping its int or float type and each word going out as a one-word list.
a message that starts with a word (note 60 100): goes out the next outlet whole.
set <n>: the next message goes out outlet n. Nothing is sent, and an outlet number the object does not have is ignored.
thresh <n>: event mode on (non-zero) or off. The creation argument sets the same mode; thresh is not saved.

[.cycle 3]   1, 2, 3, 4   =>  out0: 1, out1: 2, out2: 3, out0: 4
[.cycle 3]   10 20        =>  out0: 10, out1: 20, and out2 is next

In event mode the rotation starts again at outlet 0 for every new logical event (see Messages and dispatch). A chord that arrives as one burst, from a list or a .trigger, is dealt from outlet 0 each time, however many notes the last chord had. Two separate host calls are two events, however close together. A set holds for the rest of its own event.

The rotation always starts at outlet 0. It does not know whether a receiver is still busy; to give notes to free voices, use .poly.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	Any message goes out the next outlet in turn. A list of numbers is dealt one item per outlet. ‘set <n>’ makes outlet n the next one; ‘thresh <0/1>’ turns event mode off or on.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	any	Each message whose turn falls on this outlet, unchanged.

Parameters

Name	Default	Range	Description
outlets	1	1-256, optional mode	How many outlets to build. A non-zero second number turns on event mode: each new event starts again at outlet 0.

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

Kind:: Control-rate

Every message sends the whole state, one int out every outlet, the last outlet first. A bank wired to the outlets therefore always matches the selection, whatever it missed before. Before anything arrives, outlet 0 is selected.

The right inlet overrides the middle one, and the middle one overrides the selection. Each inlet remembers its last number, so turning an override off brings back the state underneath it without sending the index again:

[.decode 3]                (out0 out1 out2)
  left 2              =>   0 0 1
  middle 1            =>   1 1 1
  right 1             =>   0 0 0
  right 0             =>   1 1 1
  middle 0            =>   0 0 1

Any non-zero number mutes in the right inlet, negative numbers too; the middle inlet only turns on for numbers above 0. The inlets take ints, and the left inlet also takes a bang. Floats and lists are not accepted.

Inlets

#	Label	Accepts	Range	Description
0	select	INT, BANG	0 to outlets-1	An int selects the outlet that gets 1, and every outlet sends its state. An index with no outlet is ignored. A bang sends the current state again. Outlet 0 is selected at the start.
1	secondary	INT	int	All on: an int above 0 sends 1 out every outlet; 0 or less goes back to the selection. The right inlet overrides it.
2	primary	INT	int	Mute: a non-zero int sends 0 out every outlet, whatever the other inlets say. 0 brings back the state they describe.

Outlets

#	Label	Type	Range	Description
0	out0	INT	0 or 1	1 when this outlet is selected or all are on, 0 otherwise.

Parameters

Name	Default	Range	Description
outlets	1	1-256	How many outlets to build.

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

Kind:: Control-rate

[.funnel 3]     inlet 2 <- 60            =>  2 60
                inlet 0 <- note 60 100   =>  0 note 60 100
[.funnel 3 1]   inlet 0 <- 0.5           =>  1 0.5

The number in front is always an int. The message after it keeps its spelling, so a float stays a float.

Messages

Every inlet takes all of these:

a number: sent with the inlet’s number in front, and stored.
a list or a word message: sent with the inlet’s number in front. It is not stored.
bang: send the inlet’s stored number, with the inlet’s number in front. An inlet that has stored nothing sends 0.
set <n0> <n1> ...: store numbers for inlets 0, 1, 2 … in order, without sending anything. Extra numbers are ignored, a short list leaves the other inlets alone, and a word in the list skips that inlet.
offset <n>: the number added to every inlet’s number. The second argument sets the same value; offset is not saved.

A bare set or offset does nothing.

A .funnel n into a .spray n with the same offset carries n separate streams over one cord: what enters inlet i leaves outlet i. .route and .sel can also branch on the number in front.

Inlets

#	Label	Accepts	Range	Description
0	in0	FLOAT, INT, BANG, LIST	any	A message goes out with this inlet’s number in front. A number is also stored, and a bang sends the stored number again. ‘set <n0> <n1> …’ and ‘offset <n>’ work in every inlet.
1	in1	FLOAT, INT, BANG, LIST	any	A message goes out with this inlet’s number in front. A number is also stored, and a bang sends the stored number again. ‘set <n0> <n1> …’ and ‘offset <n>’ work in every inlet.

Outlets

#	Label	Type	Range	Description
0	out	LIST	list	The inlet’s number plus the offset, followed by the message as it arrived.

Parameters

Name	Default	Range	Description
inlets	2	1-256, optional offset	How many inlets to build. A second number is the offset added to every inlet’s number, so inlet 0 sends that value.

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

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	select	INT	0+	The outlet to send to, counting from 1. 0 (the start value) or a number with no outlet closes the gate.
1	in	FLOAT, INT, BANG, LIST	—	Bang, int, float or list to pass to the selected outlet.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	—	Sends the message when select is 1.
1	out1	ANY	—	Sends the message when select is 2.

Parameters

Name	Default	Range	Description
numOutlets	2	2+	How many outlets to build. Fewer than 2 still builds 2.

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

Kind:: Control-rate

Layout

The leftmost inlet takes the connection messages and nothing else. The data inlets are to its right, and connection messages number them from 0, so connect 0 0 means the first data inlet. The data outlets are numbered from 0 as well. The rightmost outlet only sends the answer to dumpconnections. .router has the same layout.

Connection messages

<inlet> <outlet> <gain>: connect with that gain. A gain of 0 disconnects.
connect <inlet> <outlet> [gain]: connect. Without a gain the third argument is used, 1 by default.
disconnect <inlet> <outlet>: remove the connection.
clear: remove every connection.
dumpconnections: send one <inlet> <outlet> <gain> line per connection out the rightmost outlet, by inlet and then by outlet. The lines have the same form as the first message, so clear followed by the stored lines restores a routing. A request that arrives during a dump is ignored.

A port number the object does not have, extra text after a message, or a message in any other form is ignored. dictionary <name> is accepted and ignored: reading the connections from a dictionary is not supported.

Scaling

A message at a data inlet goes out every connected outlet, the last outlet first, scaled by that connection’s gain:

At a gain of exactly 1 the message passes unchanged: an int stays an int and a list is not rewritten. A .matrix at gain 1 works like a .router.
At any other gain each number is multiplied and leaves as a float, also when it arrived as an int.
A bang stays a bang.
A list is scaled item by item when every item is a number. Otherwise, as with note 60 100, it passes unchanged. A list of more than 256 items also passes unscaled.

[.matrix 2 2]   connect 0 1 0.5, then 10 into data inlet 0   =>  out1: 5.

When several inlets reach one outlet, each message leaves separately; they are not added together. Connection words that arrive at a data inlet are passed on as data.

The connections are not saved with the patch, and changing the arguments removes them. Store the output of dumpconnections to keep a routing.

Inlets

#	Label	Accepts	Range	Description
0	connections	LIST	list	Sets the connections: ‘<inlet> <outlet> <gain>’ (gain 0 disconnects), ‘connect <inlet> <outlet> [gain]’, ‘disconnect <inlet> <outlet>’, ‘clear’ and ‘dumpconnections’. Inlets and outlets count from 0, starting at the first data inlet.
1	in0	FLOAT, INT, BANG, LIST	any	A message here goes out every outlet this inlet is connected to, right to left, scaled by each connection’s gain.
2	in1	FLOAT, INT, BANG, LIST	any	A message here goes out every outlet this inlet is connected to, right to left, scaled by each connection’s gain.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	any	Messages from every inlet connected to this outlet, each scaled by its connection’s gain. Messages from different inlets are not added together.
1	out1	ANY	any	Messages from every inlet connected to this outlet, each scaled by its connection’s gain. Messages from different inlets are not added together.
2	connections	LIST	list	The answer to ‘dumpconnections’: one ‘<inlet> <outlet> <gain>’ list per connection.

Parameters

Name	Default	Range	Description
inputs	2	1-256, optional outputs 1-256, optional default gain	How many data inlets, then how many data outlets (2 each by default), then the gain ‘connect’ uses when none is given (1 by default).

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

Kind:: Control-rate

What the matching outlet sends is the rest of the message: a list, a single int or float, or a bang when nothing is left. The matching rules, the no-argument case and examples are under Selector matching in Messages and dispatch.

To keep the matched item on the message, use .routepass.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	Bang, int, float or list. Its first item is matched against the selectors.

Outlets

#	Label	Type	Range	Description
0	match0	ANY	0	The rest of the message when its first item matches selector 0 (0): a list, a single int or float, or a bang when nothing is left.
1	rest	ANY	any	The message, unchanged, when its first item matched no selector. Wire it into another .route to test further.

Parameters

Name	Default	Range	Description
list	0	any tokens	The selectors, one outlet each. A number matches by value, anything else by exact text. With no argument the object matches 0.

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

Kind:: Control-rate

The matching rules are the same as for .sel and .route; see Selector matching in Messages and dispatch. The matched message leaves exactly as it arrived, matched item included, so an object further down can still see it.

Without arguments there are no selectors and only the rightmost outlet, which everything passes through.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	Bang, int, float or list. Its first item is matched against the selectors, and the message leaves unchanged.

Outlets

#	Label	Type	Range	Description
0	rest	ANY	any	The message, unchanged, when it matched no selector. Wire it into another .routepass to test further.

Parameters

Name	Default	Range	Description
selectors	—	any list of numbers and symbols	The selectors, one outlet each, at most 256. A number matches by value, anything else by exact text. With no argument there is only the rightmost outlet.

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

Kind:: Control-rate

The layout and port numbering are as described under .matrix. A data message goes out every connected outlet unchanged, the last outlet first.

Connection messages

<inlet> <outlet> <state>: a non-zero state connects, 0 disconnects.
connect <inlet> <outlet> / disconnect <inlet> <outlet>.
patch <inlet> <outlet>: connect, and disconnect every other inlet from that outlet, in one step.
clear: remove every connection.
dump: send one <inlet> <outlet> <state> line for every pair, connected or not, by inlet and then by outlet. A request that arrives during a dump is ignored.
print: accepted and ignored. Use dump to read the routing.

A port number the object does not have, or a message in any other form, is ignored. The connect messages take exactly the numbers shown; clear, dump and print ignore anything after the word.

An inlet may reach several outlets and several inlets may reach one outlet, all at once. Changing a connection takes effect from the next message, so a patch can rewire itself while it runs.

[.router 2 2]   connect 0 1, connect 1 1   =>  both data inlets reach out1

The connections are not saved with the patch, and changing the arguments removes them. Store the output of dump to keep a routing.

Inlets

#	Label	Accepts	Range	Description
0	connections	LIST	list	Sets the connections: ‘<inlet> <outlet> <0/1>’, ‘connect <inlet> <outlet>’, ‘disconnect <inlet> <outlet>’, ‘patch <inlet> <outlet>’, ‘clear’ and ‘dump’. Inlets and outlets count from 0, starting at the first data inlet.
1	in0	FLOAT, INT, BANG, LIST	any	A message here goes out, unchanged, every outlet this inlet is connected to, right to left.
2	in1	FLOAT, INT, BANG, LIST	any	A message here goes out, unchanged, every outlet this inlet is connected to, right to left.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	any	Messages from every inlet connected to this outlet, unchanged.
1	out1	ANY	any	Messages from every inlet connected to this outlet, unchanged.
2	dump	LIST	list	The answer to ‘dump’: one ‘<inlet> <outlet> <state>’ list for every inlet and outlet pair.

Parameters

Name	Default	Range	Description
inlets	2	1-256, optional outlets 1-256	How many data inlets, then how many data outlets (2 each by default).

`.sel`#

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

Kind:: Control-rate

The matching rules are under Selector matching in Messages and dispatch. A list matches on its first item, so .sel 5 bangs for 5 6 as well.

When there is exactly one selector and it is a number, a right inlet appears. A number sent there replaces the selector without sending anything. With more than one selector, the selectors cannot be changed after creation.

There is no setting for near matches. To match computed floats, put a .round in front.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	Bang, int, float or list to match. A list is matched on its first item, and the rest is dropped on a match.
1	value	FLOAT, INT	any float	Replaces the selector’s value without sending anything. Present only when there is exactly one selector and it is a number.

Outlets

#	Label	Type	Range	Description
0	match0	BANG	0	A bang when the input matches selector 0 (0).
1	rest	ANY	any	The input, unchanged, when it matched no selector. Wire it into another .sel to test further.

Parameters

Name	Default	Range	Description
selectors	0	any list of numbers and symbols	The selectors, one outlet each, at most 256. A number matches by value, anything else by exact text. With no argument the object matches 0.

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

Kind:: Control-rate

Chain the right outlet into another .split to test the next range, for keyboard splits or velocity layers. The default range is 0 to 127.

Limits given the wrong way round still work: the lower of the two is used as the low limit. Numbers leave as floats, also when they arrive as ints. A NaN goes out the right outlet.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT	any float	The number to test; sends it out one of the outlets.
1	low	FLOAT, INT	any float	Lower limit, inclusive. Stored for the next number.
2	high	FLOAT, INT	any float	Upper limit, inclusive. Stored for the next number.

Outlets

#	Label	Type	Range	Description
0	in	FLOAT	low to high	The number, as a float, when it lies inside [low, high].
1	out	FLOAT	any float	The number, as a float, when it lies outside [low, high].

Parameters

Name	Default	Range	Description
low	0	any float	Lower limit, inclusive.
high	127	any float	Upper limit, inclusive.

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

Kind:: Control-rate

Value k after the index goes out outlet index + k. Values that would land past the last outlet are dropped. The outlets send right to left (see Messages and dispatch), and each value keeps its int or float type. A word in the list is skipped but still uses up its outlet.

[.spray 4]     1 60 64   =>  out2: 64, then out1: 60
[.spray 4 1]   1 60      =>  out0: 60
[.spray 4]     -1 0 1    =>  out3: 1, out2: 0, out1: 1, out0: 0

Messages

a list that starts with a number: the index, then the values.
-1 as the index: the values are repeated across all the outlets, so a single value reaches every outlet. This is checked before the offset is applied.
offset <n>: an index of n reaches outlet 0. The second argument sets the same value; offset is not saved. Values pushed below outlet 0 by the offset are dropped.

A bare number, a bang, an index with nothing after it, or a message that starts with any other word is ignored.

In list mode (a non-zero third argument), the whole rest of the list goes out the one indicated outlet as a list. With -1 every outlet gets it.

Inlets

#	Label	Accepts	Range	Description
0	in	LIST	list	A list: an outlet index, then the values for that outlet and the ones to its right. An index of -1 sends the values to every outlet. ‘offset <n>’ shifts the outlet numbering.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	any	The value addressed to this outlet, or the whole rest of the list in list mode.
1	out1	ANY	any	The value addressed to this outlet, or the whole rest of the list in list mode.

Parameters

Name	Default	Range	Description
outlets	2	1-256, optional offset and list mode	How many outlets to build. A second number is the offset: an index equal to it reaches outlet 0. A non-zero third number turns on list mode, which sends the whole rest of the list out the one indicated outlet.

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

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	select	INT	0+	Which inlet passes, counting from 1 for the inlet next to this one. 0 (the start value) or a number with no inlet passes nothing.
1	in0	FLOAT, INT, BANG, LIST	—	Bang, int, float or list, passed on when select is 1.
2	in1	FLOAT, INT, BANG, LIST	—	Bang, int, float or list, passed on when select is 2.

Outlets

#	Label	Type	Range	Description
0	out	ANY	—	Messages from the selected inlet.

Parameters

Name	Default	Range	Description
numInlets	2	2+	How many inlets to pass from. Fewer than 2 still builds 2.

Routing

Contents

Routing#