MIDI

MIDI#

Formatting, parsing and note handling for MIDI, and MIDI device I/O.

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

Note

Objects marked MIDI device only below hold a MIDI device port. They exist only in builds with YSE_ENABLE_MIDI_DEVICE — not on macOS or Android.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Only available when libYSE is built with YSE_ENABLE_MIDI_DEVICE (on by default on Windows and Linux desktop builds). On macOS and Android the option is off and this object is not registered, so a patch that uses it is not portable to those platforms.

Reads only the coarse byte of the pitch-bend message. Over a two-semitone bend range that is a step of about three cents, which can be heard on a slow bend; use .xbendin for the full resolution. Subtract 64 before scaling the value into a bend amount.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	bend	INT	0-127	The wheel position: 0 fully down, 64 at rest, 127 fully up.
1	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

`.bendout`#

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

Kind:: Control-rate

The value is sent as the coarse byte of the pitch-bend message, with the fine byte set to 0. That matches what .bendin and .midiparse report, so a value means the same on the way in and on the way out. .xbendout sends the full 14 bits.

The channel argument and the output work as described under .noteon.

Inlets

#	Label	Accepts	Range	Description
0	bend	INT	0-127	Pitch bend, 64 at rest; sends the message.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The pitch-bend message, for .midiout. The fine byte is 0.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

`.borax`#

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

Kind:: Control-rate

Each pair that arrives is a note-on when its velocity is not 0, and a note-off when it is 0. The object measures the notes; it does not pass them on, so wire it beside the path the notes take, not into it.

Outlets

Not every outlet fires on every message:

A note-on sends the delta pair (when there was an earlier note-on), then velocity, pitch, polyphony, voice and serial.
A note-off sends duration and note-off count, then velocity 0, pitch, polyphony, voice and serial.
delta sends only the delta pair: the time since the last note-on, right now. Before the first note-on it sends nothing.

The serial is sent last and is the same at the attack and the release of a note, so it identifies the note. Voices are the lowest free number from 1, as .poly numbers them. A pitch played twice takes two voices, and the releases close them oldest first. Durations and deltas are measured in milliseconds with sub-millisecond precision, on the same clock .timer uses.

Reset

A bang on the right inlet sends a full note-off report for every note still sounding, in voice order, then sets every counter back to 0 and forgets the last note-on, so the next note-on reports no delta.

Limits

At most 128 notes are tracked at once. A note-on with 128 notes sounding is ignored, and so is a note-off for a pitch no voice holds. Pitches and velocities are not clamped.

Inlets

#	Label	Accepts	Range	Description
0	pitch	FLOAT, INT, LIST	int, float, list, ‘delta’	A pitch is measured as a note-on, or as a note-off when the stored velocity is 0. A list “pitch velocity” sets the velocity first. “delta” reports the time since the last note-on.
1	velocity	FLOAT, INT, LIST	0-127	Velocity for the pitches that follow; sends nothing. 0 means a note-off. Not clamped.
2	reset	BANG	bang	A bang reports a note-off for every sounding note, then sets every counter back to 0.

Outlets

#	Label	Type	Range	Description
0	serial	INT	1+	The note’s number, counting note-ons from 1. The same at its note-on and its note-off. Sent last.
1	voice	INT	1-128	The voice the note took: the lowest free number, from 1.
2	poly	INT	0-128	How many notes are sounding, on every note-on and note-off.
3	pitch	INT	int	The pitch of the note that started or ended.
4	velocity	INT	int	The stored velocity at a note-on, 0 at a note-off.
5	notesoff	INT	1+	How many notes have ended, sent at each note-off.
6	duration	FLOAT	0+ ms	How long the note that just ended lasted, in milliseconds.
7	deltacount	INT	1+	How many delta times have been reported, sent with each one.
8	delta	FLOAT	0+ ms	Milliseconds since the previous note-on, sent at each note-on after the first and on “delta”.

`.channelpressure`#

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

Kind:: Control-rate

The value is clamped to 0-127. The channel argument and the output work as described under .noteon.

Inlets

#	Label	Accepts	Range	Description
0	pressure	INT	0-127	Pressure for the whole channel; sends the message.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The channel-pressure message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

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

Kind:: Control-rate

The value is clamped to 0-127. The channel and controller number are creation arguments. The channel argument and the output work as described under .noteon.

.xctlout sends a controller at 14-bit resolution.

Inlets

#	Label	Accepts	Range	Description
0	value	INT	0-127	Controller value; sends the message.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The control-change message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.
controller	0	0-127	Controller number.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Wire the controller-number outlet into .route or .sel to split one .ctlin across a whole control surface. The default controller filter is -1, not 0, because controller 0 (bank select) is a real controller.

A switch such as the sustain pedal sends 0 and 127 rather than a sweep. .xctlin combines the paired controllers 0-31 and 32-63 into 14-bit values.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	value	INT	0-127	The controller’s value. Sent last.
1	controller	INT	0-127	The controller number: 1 is the modulation wheel, 7 volume, 64 the sustain pedal.
2	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.
controller	-1	-1 to 127	Controller number to listen to, 0-127, or -1 for all controllers. Any other value means all controllers.

`.flush`#

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

Kind:: Control-rate

Use it between the logic that plays notes and the object that sends them. A pair with a velocity other than 0 marks the pitch as sounding, a pair with velocity 0 clears it, and every pair passes through unchanged.

Messages

bang: send pitch and velocity 0 for every note still sounding, from the lowest pitch up, and forget them. A second bang sends nothing.
clear: forget the sounding notes without sending anything.
<pitch> <velocity>: set the velocity, then play the pitch. This is the shape .midiparse sends from its note outlet.

The object has no channel. To release notes in a MIDI byte stream on the channels they were played on, use .midiflush after the formatters.

Pitches outside 0-127 pass through but are not tracked. When the patcher is cleared or destroyed, or the object is deleted, the object releases its sounding notes first.

Inlets

#	Label	Accepts	Range	Description
0	pitch	FLOAT, INT, BANG, LIST	int, float, list, ‘bang’, ‘clear’	A pitch passes through with the stored velocity. A list “pitch velocity” sets the velocity first. A bang releases every sounding note; “clear” forgets them.
1	velocity	FLOAT, INT, LIST	0-127	Velocity for the pitches that follow; sends nothing. 0 means a release. Not clamped.

Outlets

#	Label	Type	Range	Description
0	pitch	INT	int	The pitch, as it passes and again when a bang releases it. Sent last.
1	velocity	INT	int	The stored velocity as a pair passes, or 0 for a release.

`.makenote`#

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

Kind:: Control-rate

The velocity and duration inlets set the values for notes played after them; a note already sounding keeps its own. A velocity of 0 is a release in MIDI, so the pair passes through and nothing is scheduled. The velocity starts at 0, so give it as the first argument or send one before playing:

[.makenote 100 500]   60  =>  60 100 now, 60 0 half a second later

Messages

stop: release every sounding note now, in the order they were played.
clear: forget the sounding notes without releasing them.
<pitch> <velocity>: set the velocity, then play the pitch.

The duration is in milliseconds. A duration of 0 releases the note on the next audio block. Durations follow the engine’s audio clock: while the engine is paused, pending releases wait. Note values such as 4n and tick counts are not supported; they are ignored and the duration is left as it was.

A pitch played twice is two notes, each released after its own duration.

Limits

One .makenote holds at most 64 sounding notes. Past that, a new note is refused completely: nothing is sent. The patcher also holds at most 128 pending timed messages, shared with .pipe, .delay and the other timing objects; when that runs out, the note is released at once instead of after its duration.

When the patcher is cleared or destroyed, or the object is deleted, it releases its sounding notes first.

Inlets

#	Label	Accepts	Range	Description
0	pitch	FLOAT, INT, LIST	int, float, list, ‘stop’, ‘clear’	A pitch plays a note with the stored velocity and duration. A list “pitch velocity” sets the velocity first. “stop” releases every sounding note; “clear” forgets them.
1	velocity	FLOAT, INT, LIST	0-127	Velocity for the notes that follow; sends nothing. Clamped to 0-127. With 0, the pair passes through and no release is scheduled.
2	duration	FLOAT, INT, LIST	0+ ms	Duration in milliseconds for the notes that follow; sends nothing. A negative value counts as 0. Note values and ticks are not supported.

Outlets

#	Label	Type	Range	Description
0	pitch	INT	int	The pitch, when the note plays and again when it is released. Sent last.
1	velocity	INT	0-127	The velocity when the note plays, 0 when it is released.

Parameters

Name	Default	Range	Description
velocity	0	0-127	Starting velocity. With 0, notes pass through and no release is scheduled, so set it or send a velocity before playing.
duration	0	0+ ms	Starting duration in milliseconds. 0 releases each note on the next audio block.

`.midiflush`#

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

Kind:: Control-rate

Put it in a MIDI byte stream, for example between the formatters and .midiout. Everything that arrives passes out unchanged, in the form it arrived in. On the way through, the object follows the stream and remembers which notes are sounding on which channel.

A bang sends a note-off for every note still sounding, as numeric lists such as 128 60 0, ordered by channel and then pitch, and forgets them.

The stream is decoded the way .midiparse decodes it, so notes sent under running status are tracked, a clock byte between two data bytes does not break a note, and bytes inside a system-exclusive dump are never read as notes. Both forms of a release clear a note: a note-off, and a note-on with velocity 0.

The inlet reads numeric byte lists, the binary messages the MIDI sender objects build, and single ints. A numeric list holding a number outside 0-255 is dropped whole.

.midiout’s allnotesoff is a controller message that many devices ignore; .midiflush sends a real note-off for each note. When the patcher is cleared or destroyed, or the object is deleted, it flushes first.

Inlets

#	Label	Accepts	Range	Description
0	midi	FLOAT, INT, BANG, LIST	0-255	MIDI bytes as a list of byte values, a message from a sender object, or one int at a time; all pass through. A bang sends a note-off for every sounding note.

Outlets

#	Label	Type	Range	Description
0	midi	ANY	0-255	The stream, unchanged, plus the note-offs a bang sends, as lists such as 128 60 0.

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

Kind:: Control-rate

Every inlet except the channel sends a message at once, on the channel the channel inlet holds (1 until set). The output is a list of byte values, such as 144 60 100, one message per list.

Inlets

note: <pitch> <velocity>. A bare pitch is sent with velocity 0, which is a release. Releases are sent as note-ons with velocity 0, never as note-off messages.
poly pressure: <pitch> <pressure>; a bare pitch sends pressure 0.
control change: <controller> <value>; a bare number sends value 0.
program change: 1-128, the numbering .pgmin and .midiparse report.
aftertouch: one pressure value for the channel.
pitch bend: 0-127, the coarse byte, with 64 at rest. The fine byte is sent as 0.
channel: 1-16, stored only.
raw: byte values passed straight to the outlet, so the system-exclusive and clock messages .midiparse sends from its rightmost outlet can be put back.

Values are clamped to the range MIDI allows, except on the raw inlet, where a value outside 0-255 is dropped. A raw list is cut at 128 bytes.

Because .midiparse reports a note-off as velocity 0 and pitch bend as the coarse byte, a stream taken apart and put back together loses note-off release velocities and the fine bend byte.

Inlets

#	Label	Accepts	Range	Description
0	note	FLOAT, INT, LIST	0-127 0-127	“pitch velocity”; a bare pitch sends velocity 0, a release. Sends a note-on.
1	poly	FLOAT, INT, LIST	0-127 0-127	Polyphonic key pressure as “pitch pressure”; a bare pitch sends 0.
2	control	FLOAT, INT, LIST	0-127 0-127	Control change as “controller value”; a bare number sends value 0.
3	program	FLOAT, INT	1-128	Program change, numbered from 1.
4	aftertouch	FLOAT, INT	0-127	Channel pressure: one value for the whole channel.
5	bend	FLOAT, INT	0-127	Pitch bend, coarse byte, 64 at rest. The fine byte is sent as 0.
6	channel	FLOAT, INT	1-16	Channel for the messages that follow. Stores only; starts at 1.
7	raw	FLOAT, INT, LIST	0-255	Byte values passed straight to the outlet, as a list or one at a time. A value outside 0-255 is dropped; a list is cut at 128 bytes.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	0-255	One message per list, such as 144 60 100: a note-on for middle C, velocity 100, channel 1.

`.midiin`#

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

Kind:: Control-rate
Availability:: MIDI device only

Note

The bytes arrive exactly as the device sent them, so a note-on is three ints and a system-exclusive dump is as many ints as it has bytes. To work with whole messages, use .xmidiin; to decode them, wire .midiin into .midiparse.

Every MIDI input object

The objects that receive from a MIDI device (.midiin, .xmidiin, .notein, .ctlin, .sysexin and the others) share these rules:

The first argument is the input port, counted from 0. .midiinfo lists the ports by name. Several objects can listen to one port; each receives every message.
A port that cannot be opened, because the device is missing or another program holds it, leaves the object silent. The patch still loads.
Changing the port argument while the patch runs recreates the object.
Messages that arrive between two audio blocks reach the patch at the start of the next block. At most 64 short messages (512 bytes) are handed out per block; the rest wait for the next block, so a long dump arrives over several blocks.
These objects exist only in builds with MIDI device support, which includes the Windows and Linux builds.

Objects that decode channel messages (.notein, .ctlin, .bendin, .pgmin, .touchin, .polyin, .rpnin, .nrpnin and the .x input objects) also share these:

The second argument is the channel to listen to, 1-16. 0, the default, listens to all channels.
Channels are reported as 1-16. The channel outlet is there even when the object listens to one channel, and then always reports that channel.
The outlets fire from right to left, so the channel and the other values are out before the leftmost outlet triggers anything.

Limits

A message of up to 8192 bytes arrives whole. A longer one is dropped entirely and logged, never passed on cut short. Messages are also dropped, and logged, when they arrive faster than the patch takes them. At most 8 input ports can be open at once, and at most 8 objects can listen to one port.

Outlets

#	Label	Type	Range	Description
0	byte	INT	0-255	Each received byte as an int. Status bytes keep their value on the wire (144-159 is a note-on, 240 starts a system-exclusive dump); data bytes are 0-127.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Input ports and output ports are numbered separately: input port 1 and output port 1 are unrelated devices. The direction argument chooses which list a bang reports.

Messages

bang: send the number of ports, then for each port its index and then its name.
input, output: switch which list is reported.
refresh: scan the machine again, for example after a device was plugged in. The scan runs in the background, and the full listing is sent again when it finishes, from the next audio block.

The ports are scanned when the object is created; a bang reports that scan until refresh takes a new one. Names are sent whole, spaces included.

Limits

At most 32 ports are listed per direction, and names are cut at 63 characters. At most 16 .midiinfo objects can use refresh at the same time. Only available in builds with MIDI device support.

Inlets

#	Label	Accepts	Range	Description
0	bang	BANG, LIST	—	A bang sends the listing. “input” and “output” switch which ports are listed; “refresh” scans the machine again and sends the listing when the scan is done.

Outlets

#	Label	Type	Range	Description
0	name	LIST	—	The port’s name, spaces included, cut at 63 characters. Sent after its index.
1	index	INT	0-31	The port’s index: the port argument .midiout, .notein and the other MIDI objects take. Counted from 0.
2	count	INT	0-32	How many ports there are. Sent first; 0 when there are none.

Parameters

Name	Default	Range	Description
direction	input	input \| output	Which ports to list: “input” or “output”. Anything else means “input”.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Input

Each list is sent as one MIDI message, at its own length, so a program change goes out as two bytes and a system-exclusive dump as a whole. Two forms are accepted:

numeric, 144 60 100: what .midiformat, .sxformat, .xmidiin and .seq send;
binary: what .noteon, .bendout, .rpnout and the other sender objects build.

A numeric list with a number outside 0-255, or longer than 256 bytes, is not sent.

Messages

allnotesoff: controller 123 (all notes off) on all 16 channels.
reset: controller 121 (reset all controllers) on all 16 channels.
omni on, omni off, poly on, poly off, local control on, local control off: the matching channel-mode message on channel 1.

Opening the port

The port opens when the first message arrives, not when the object is created, so a patch loads on a machine without its devices. The port is opened in the background, and messages sent before it is open are dropped, including the first one. If the port cannot be opened, every message is dropped.

Sending never blocks the audio thread: messages are handed to a separate thread, which normally sends them within a millisecond, in order. If that queue is full, a message is dropped.

At most 64 .midiout objects can exist at once; a further one never opens its port. Only available in builds with MIDI device support.

Inlets

#	Label	Accepts	Range	Description
0	midi	LIST	0-255	One MIDI message: a list of byte values such as 144 60 100, or a message from a sender object such as .noteon. Messages that arrive before the port is open, including the first, are dropped.

Parameters

Name	Default	Range	Description
port	0	device-dependent	MIDI output port, counted from 0; .midiinfo lists them.

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

Kind:: Control-rate

Bytes may arrive one at a time or as numeric lists, in any split: a message spread over several lists decodes the same as one sent whole.

Outlets

note: <pitch> <velocity>. A note-off, and a note-on with velocity 0, both report velocity 0.
poly pressure: <pitch> <pressure>.
control change: <controller> <value>.
program change: 1-128, the value on the wire plus one.
aftertouch: the channel pressure.
pitch bend: 0-127, the coarse byte only, with 64 at rest.
channel: 1-16, sent before the outlet it belongs to.
raw: everything else, as byte lists: system exclusive, song position, song select, time code, tune request, and clock messages (248-255).

The parser understands running status, so a chord sent with one status byte decodes as separate notes. A clock byte that arrives in the middle of another message is sent at once and does not disturb it. A system-exclusive dump longer than 128 bytes leaves in consecutive pieces, the first starting with 240 and the last ending with 247; a dump cut short by another status byte ends there.

Data bytes that arrive with no status byte before them are dropped. A value outside 0-255 is ignored. .midiformat is the inverse; see its notes for what does not survive the round trip.

Inlets

#	Label	Accepts	Range	Description
0	midi	FLOAT, INT, LIST	0-255	MIDI bytes, one int at a time or as a list of byte values. A value outside 0-255 is ignored.

Outlets

#	Label	Type	Range	Description
0	note	LIST	0-127 0-127	Note as “pitch velocity”; a release reports velocity 0.
1	poly	LIST	0-127 0-127	Polyphonic key pressure as “pitch pressure”.
2	control	LIST	0-127 0-127	Control change as “controller value”.
3	program	INT	1-128	Program change, numbered from 1.
4	aftertouch	INT	0-127	Channel pressure: one value for the whole channel.
5	bend	INT	0-127	Pitch bend, coarse byte only, 64 at rest.
6	channel	INT	1-16	The channel the message arrived on. Sent before the typed outlet.
7	raw	LIST	0-255	Every other message as a list of byte values: system exclusive, song position, time code, clock and the rest.

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

Kind:: Control-rate

MPE gives every sounding note its own MIDI channel, so pitch bend, pressure and slide apply to one note. Before playing, both ends must agree how many channels the zone uses; this message sets that.

A value on the inlet sends three control-change messages on the zone’s master channel: channel 1 for the lower zone, channel 16 for the upper. Wire the outlet to .midiout.

15, the default, gives the zone every other channel.
A smaller number leaves room for a second zone or for ordinary MIDI.
0 switches MPE off on the device.

On receiving the message, a device sets its pitch-bend range to 48 semitones on the member channels and 2 on the master channel, and stops its sounding notes. MPE defines only the lower and upper zone.

Inlets

#	Label	Accepts	Range	Description
0	members	INT	0-15	Number of member channels; sends the message. 0 switches MPE off on the device.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	0-255	Three control-change messages on the zone’s master channel, as byte lists for .midiout.

Parameters

Name	Default	Range	Description
zone	0	0-1	0 for the lower zone (master channel 1, members counting up from 2) or 1 for the upper zone (master channel 16, members counting down from 15). Anything other than 1 means the lower zone.

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

Kind:: Control-rate

Set the member channel on the right inlet first; it is stored and sends nothing. Every other inlet sends one message on that channel at once, as a numeric byte list. In MPE one channel is one note, so a polyphonic patch changes the channel for each note.

Inlets

note: <pitch> <velocity>. A bare pitch is sent with velocity 0, a release. Releases are sent as note-ons with velocity 0.
bend: 0-16383, 8192 at rest. The full 14 bits are needed at the 48-semitone bend range MPE devices use.
pressure: sent as channel pressure, which on a member channel belongs to that note.
slide: sent as controller 74.
channel: 1-16.

Values are clamped to the range MIDI allows. .mpeconfig tells the device how many member channels to expect.

Inlets

#	Label	Accepts	Range	Description
0	note	FLOAT, INT, LIST	0-127 0-127	“pitch velocity”; a bare pitch sends velocity 0, a release. Sends a note-on.
1	bend	FLOAT, INT	0-16383	Per-note pitch bend, 8192 at rest, at the full 14 bits.
2	pressure	FLOAT, INT	0-127	Per-note pressure, sent as channel pressure.
3	slide	FLOAT, INT	0-127	Per-note slide, sent as controller 74.
4	channel	FLOAT, INT	1-16	Member channel for the messages that follow. Stores only; starts at 1.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	0-255	One message per list, such as 146 60 100: a note-on for middle C on channel 3.

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

Kind:: Control-rate

Each message on the four left outlets is preceded by its role, then its channel. The role says what the channel is doing in the zone:

2: the master channel. Its messages apply to every note.
1: a member channel. Its messages belong to the one note on that channel.
0: a channel outside the zone, such as ordinary MIDI on the same cable.

Pitch bend is reported at the full 14 bits. A release, in either form, is reported as velocity 0.

The zone and members arguments say which channels to expect. An MPE configuration message on the zone’s master channel updates the member count while the patch runs, and is not reported. The member count only changes the role reported; nothing is filtered.

Program changes, other controllers, poly pressure and system exclusive are not reported here. Wire .midiparse to the same source to read them. Input is read the same way .midiparse reads it.

Inlets

#	Label	Accepts	Range	Description
0	midi	FLOAT, INT, LIST	0-255	MIDI bytes, one int at a time or as a list of byte values. A value outside 0-255 is ignored.

Outlets

#	Label	Type	Range	Description
0	note	LIST	0-127 0-127	Note as “pitch velocity”; a release reports velocity 0.
1	bend	INT	0-16383	Pitch bend at the full 14 bits, 8192 at rest.
2	pressure	INT	0-127	Channel pressure: on a member channel, that note’s pressure.
3	slide	INT	0-127	Controller 74.
4	channel	INT	1-16	The channel the message arrived on: in MPE, the note it belongs to.
5	role	INT	0-2	The channel’s role: 2 master, 1 member, 0 outside the zone. Sent first.

Parameters

Name	Default	Range	Description
zone	0	0-1	0 for the lower zone (master channel 1, members counting up from 2) or 1 for the upper zone (master channel 16, members counting down from 15). Anything other than 1 means the lower zone.
members	15	0-15	Member channels to assume until a configuration message in the stream changes it.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Outlets

#	Label	Type	Range	Description
0	pitch	INT	0-127	The note number; middle C is 60. Sent last.
1	velocity	INT	0-127	How hard the key was struck, or 0 for a release: a note-off message and a note-on with velocity 0 both report 0.
2	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

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

Kind:: Control-rate

The pitch and velocity are clamped to 0-127. The channel argument and the output work as described under .noteon.

.xnoteout sends both note-ons and note-offs from one object.

Inlets

#	Label	Accepts	Range	Description
0	pitch	INT	0-127	Note number; sends the message.
1	velocity	INT	0-127	Release velocity, stored for the next pitch.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The note-off message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

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

Kind:: Control-rate

A note-on with velocity 0 is a release on most devices, so .noteon can end the notes it starts. The pitch and velocity are clamped to 0-127.

The MIDI sender objects

.noteon, .noteoff, .controlchange, .polypressure, .channelpressure, .programchange, .bendout, .xbendout, .xbendout2, .xctlout, .xnoteout, .rpnout and .nrpnout share these rules:

The channel is a creation argument counted from 0: 0 is MIDI channel 1 and 15 is channel 16. This differs from the input objects and .midiformat, which number channels 1-16. A channel outside 0-15 is clamped.
The leftmost inlet sends the message. The other inlets store a value for the next message.
Values are clamped to the range MIDI allows rather than refused.
The output is a binary message meant for .midiout. .midiflush reads it too, but other objects, including .midiparse, do not; use .midiformat for a message as a list of numbers.

[.notein] pitch, velocity  ->  [.noteon 0]  ->  [.midiout 1]

Inlets

#	Label	Accepts	Range	Description
0	pitch	INT	0-127	Note number; sends the message.
1	velocity	INT	0-127	Note velocity, stored for the next pitch.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The note-on message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Works like .rpnin, with controllers 99 and 98 selecting the parameter. A non-registered number means whatever the device’s documentation says; it is where a hardware synthesiser keeps its own settings.

.rpnin and .nrpnin follow the same selection, so each reports only the writes to its own kind of parameter. Parameter 16383 is a valid non-registered number and is reported.

Outlets

#	Label	Type	Range	Description
0	value	INT	0-16383	The value written. Sent last. A device that sends only the coarse byte moves in steps of 128.
1	parameter	INT	0-16383	The non-registered parameter written. What each number means is in the sending device’s documentation.
2	channel	INT	1-16	The channel the value arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

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

Kind:: Control-rate

Works like .rpnout, with controllers 99 and 98 selecting the parameter. A non-registered number means whatever the receiving device’s documentation says.

Inlets

#	Label	Accepts	Range	Description
0	value	INT	0-16383	The value to write; sends all four messages. A device that reads only the coarse byte sees the value in steps of 128.
1	parameter	INT	0-16383	Non-registered parameter number, stored for the next value. What each number means is in the receiving device’s documentation.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Four control-change messages, for .midiout: the parameter number’s coarse and fine bytes, then the value’s coarse byte on controller 6 and fine byte on controller 38.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

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

Kind:: Control-rate

It was made for note streams that are transformed on the way through: store the original pitch with the pitch actually played, and when the note-off arrives, its pitch looks up the played one.

Inlets

y (right): arm a y value. Nothing is stored yet; only one y can wait, and a second one replaces the first. 0 is a valid y.
x (left), with a y armed: store the pair x,y and disarm the y.
x (left), with no y armed: look up x. If a pair matches, send its y and delete the pair; otherwise do nothing.

Messages

<x> <y>: arm y, then store the pair. A bare x is a lookup.
bang: send the y of every stored pair, oldest first, without deleting anything.
clear: delete every pair and disarm a waiting y.

72 -> right inlet, 60 -> left inlet    stores 60,72
60 -> left inlet                       sends 72 and deletes the pair

Storing an x that is already there keeps both pairs, and a lookup takes the newest. A float is truncated to an int. The store holds at most 256 pairs; a store past that is refused, and the armed y is still used up. Nothing is saved with the patch.

Inlets

#	Label	Accepts	Range	Description
0	x	FLOAT, INT, BANG, LIST	int, float, list ‘<x> <y>’, bang, ‘clear’	With a y armed, stores the pair x,y. Otherwise looks up x: sends the matching pair’s y and deletes the pair. A list “x y” stores a pair; a bang sends every stored y; “clear” deletes all pairs.
1	y	FLOAT, INT, LIST	any int	Arms a y for the next x; sends nothing. A second y replaces the first. 0 is a valid y.

Outlets

#	Label	Type	Range	Description
0	y	INT	any int	The y of a pair looked up by x, or every stored y, oldest first, on a bang.

`.pgmin`#

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Programs are reported as 1-128, one more than the value on the wire, which is how most devices display them. .midiformat takes the same numbering; .programchange takes the value on the wire, 0-127.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	program	INT	1-128	The program number: the value on the wire plus one.
1	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

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

Kind:: Control-rate

Wire the voice outlet into .route or .gate to send each note to its own voice chain. The voice number is sent last, after the velocity and pitch, so it is the value that triggers.

Allocation

A note-on takes the lowest free voice.
A note-off frees the voice holding that pitch and sends the same voice number with velocity 0. A pitch played twice takes two voices; the releases free them oldest first.
When every voice is busy and stealing is off, the note leaves the overflow outlet as <pitch> <velocity> and is not tracked.
When stealing is on, the note held longest gives up its voice: its release is sent first, then the new note on the same voice number.
A note-off for a pitch no voice holds leaves the overflow outlet as <pitch> 0, so the releases of overflowed notes follow them. With stealing on this happens when a stolen note’s key is released.

Messages

stop: release every sounding voice, in voice order.
<pitch> <velocity>: set the velocity, then play the pitch.

Pitches and velocities are not clamped. Making the pool smaller while notes sound strands nothing: notes above the new size still get their releases. When the patcher is cleared or destroyed, or the object is deleted, it releases every sounding voice first.

Inlets

#	Label	Accepts	Range	Description
0	pitch	FLOAT, INT, LIST	int, float, list, ‘stop’	A pitch takes a voice, or frees one when the stored velocity is 0. A list “pitch velocity” sets the velocity first. “stop” releases every sounding voice.
1	velocity	FLOAT, INT, LIST	0-127	Velocity for the pitches that follow; sends nothing. 0 means a release. Not clamped.

Outlets

#	Label	Type	Range	Description
0	voice	INT	1-128	The voice number, from 1: the same for a note’s attack and its release. Sent last.
1	pitch	INT	int	The pitch of the note being started or released.
2	velocity	INT	int	The stored velocity for a note-on, 0 for a release.
3	overflow	LIST	pitch velocity	“pitch velocity” for a note no voice could take, and “pitch 0” for a release whose pitch no voice holds.

Parameters

Name	Default	Range	Description
voices	16	1-128	Number of voices. Clamped to 1-128.
steal	0	0 or non-zero	0 sends notes that find no free voice to the overflow outlet. Any other value takes the voice of the note held longest, releasing that note first.

`.polyin`#

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Few keyboards send per-key pressure; most send only channel pressure, which .touchin reads. Match the pitch with the one .notein reported to route the pressure to the right voice.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	pitch	INT	0-127	The key the pressure belongs to, numbered as .notein numbers it. Sent last.
1	pressure	INT	0-127	The pressure on that key.
2	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

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

Kind:: Control-rate

The pitch and pressure are clamped to 0-127. The channel argument and the output work as described under .noteon.

Inlets

#	Label	Accepts	Range	Description
0	pitch	INT	0-127	Note number of the pressed key; sends the message.
1	pressure	INT	0-127	Pressure on that key, stored for the next pitch.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The poly-pressure message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

`.programchange`#

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

Kind:: Control-rate

Programs are numbered as on the wire, 0-127. Devices that display programs from 1 show the value plus one, which is also what .pgmin reports. The value is clamped to 0-127. The channel argument and the output work as described under .noteon.

Inlets

#	Label	Accepts	Range	Description
0	program	INT	0-127	Program number as on the wire, from 0; sends the message.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The program-change message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

A parameter write is four control changes, not one message: controllers 101 and 100 select a 14-bit parameter number, then controllers 6 and 38 write a 14-bit value. The object remembers the selection for each channel and reports each value written.

Registered numbers are defined by the MIDI standard: 0 is pitch-bend range, 1 fine tuning, 2 coarse tuning, 3 tuning program, 4 tuning bank.

A value is reported as soon as its coarse byte (controller 6) arrives, with the fine byte as 0, and again when the fine byte (controller 38) follows. Devices that send only the coarse byte are therefore reported in steps of 128. Selecting parameter 16383 (null) ends the selection, so later data bytes are not reported.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	value	INT	0-16383	The value written. Sent last. A device that sends only the coarse byte moves in steps of 128.
1	parameter	INT	0-16382	The registered parameter written: 0 pitch-bend range, 1 fine tuning, 2 coarse tuning, 3 tuning program, 4 tuning bank.
2	channel	INT	1-16	The channel the value arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

`.rpnout`#

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

Kind:: Control-rate

Each value sends four control-change messages: controllers 101 and 100 select the parameter number from the right inlet, then controllers 6 and 38 write the value. The selection is sent again with every value, so another device on the cable cannot change it in between.

0 -> right inlet, then 1536 -> left inlet
pitch-bend range of 12 semitones (12 * 128)

The selection is not reset to null afterwards. Send to parameter 16383 when a device needs that.

Inlets

#	Label	Accepts	Range	Description
0	value	INT	0-16383	The value to write; sends all four messages. A device that reads only the coarse byte sees the value in steps of 128.
1	parameter	INT	0-16383	Registered parameter number, stored for the next value: 0 pitch-bend range, 1 fine tuning, 2 coarse tuning, 3 tuning program, 4 tuning bank, 16383 null.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Four control-change messages, for .midiout: the parameter number’s coarse and fine bytes, then the value’s coarse byte on controller 6 and fine byte on controller 38.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

`.rtin`#

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

Kind:: Control-rate
Availability:: MIDI device only

Note

A clock sends 24 timing messages per quarter note. Count them with .counter to follow an external sequencer’s tempo, and use start and stop to drive a .transport. Active sensing (254) is filtered out.

Clock messages can arrive in the middle of other messages, such as a system-exclusive dump; they reach this object whole without disturbing the other objects on the port. The port argument works as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	status	INT	248-255	The message: 248 timing clock (24 per quarter note), 250 start, 251 continue, 252 stop, 255 reset.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.

`.stripnote`#

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

Kind:: Control-rate

Use it after a note source when only attacks matter, such as triggering a sample. Every note source reports a release as velocity 0, so without it a patch fires twice per key.

A list <pitch> <velocity> sets the velocity and then tests the pitch, so .midiparse’s note outlet can be wired straight in. Nothing is clamped: any velocity other than 0 passes.

Inlets

#	Label	Accepts	Range	Description
0	pitch	FLOAT, INT, LIST	int, float, list	A pitch passes with the stored velocity, unless that velocity is 0. A list “pitch velocity” sets the velocity first.
1	velocity	FLOAT, INT, LIST	0-127	Velocity for the pitches that follow; sends nothing. Not clamped.

Outlets

#	Label	Type	Range	Description
0	pitch	INT	int	The pitch of a note-on. Sent last.
1	velocity	INT	int	The velocity of a note-on; never 0.

`.sustain`#

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

Kind:: Control-rate

A note-on always passes straight through. A note-off (velocity 0) passes through with the pedal up, and is held back with the pedal down. Lifting the pedal sends every held note-off, from the lowest pitch up.

Messages

sustain 1, sustain 0: press or lift the pedal, as the right inlet does.
flush: send every held note-off now and leave the pedal where it is.
clear: forget the held note-offs without sending them.
<pitch> <velocity>: set the velocity, then play the pitch.

A key played again while its release is held sounds again, and the held release still goes out when the pedal lifts. Pitches outside 0-127 are never held.

Placed before a .flush, it leaves the .flush tracking what is really sounding. When the patcher is cleared or destroyed, or the object is deleted, it sends its held note-offs first.

Inlets

#	Label	Accepts	Range	Description
0	pitch	FLOAT, INT, LIST	int, float, list, ‘sustain 0/1’, ‘flush’, ‘clear’	A pitch passes with the stored velocity; a release is held back while the pedal is down. Also takes “pitch velocity”, “sustain 0/1”, “flush” and “clear”.
1	velocity	FLOAT, INT, LIST	0-127	Velocity for the pitches that follow; sends nothing. 0 means a release. Not clamped.
2	pedal	FLOAT, INT, LIST	0 (up) or non-zero (down)	Non-zero presses the pedal. 0 lifts it and sends every held release. The pedal starts up.

Outlets

#	Label	Type	Range	Description
0	pitch	INT	int	The pitch, as a pair passes or as a held release is sent. Sent last.
1	velocity	INT	int	The stored velocity as a pair passes, or 0 for a release.

`.sxformat`#

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

Kind:: Control-rate

The arguments are the template, one token per byte:

a number 0-255: a constant byte,
$i1 to $i9: a byte taken from an inlet; $i1 is the left inlet,
sumstart: sends nothing, and starts the checksum region,
sum: a checksum byte that makes the region’s total a multiple of 128, as Roland devices expect. Without sumstart, the region is everything before it except a leading 240.

The object has one inlet for each placeholder up to the highest one used. The left inlet sends the message; the others only store. A list on the left inlet fills $i1, $i2 and so on, then sends. A bang sends with the stored values.

A negative value leaves its byte out, so one template can cover a short and a long form of a message. A value above 127 is clamped to 127. A placeholder that has not received a value is 0.

[.sxformat 240 67 16 0 $i1 $i2 247]   5 99 -> left inlet  =>  240 67 16 0 5 99 247

The message leaves as a list of byte values for .midiout. Start it with 240 and end it with 247; the object does not add them.

Limits

A template holds at most 256 tokens; the rest is cut, with an error in the log. A token that is not a byte, a placeholder, sumstart or sum is skipped, with an error in the log.

Inlets

#	Label	Accepts	Range	Description
0	$i1	FLOAT, INT, BANG, LIST	-1 to 127	Value for $i1; sends the message. A list fills $i1, $i2 and so on, then sends; a bang sends with the stored values. A negative value leaves its byte out; above 127 is clamped.

Outlets

#	Label	Type	Range	Description
0	sysex	LIST	0-255	The message as a list of byte values, such as 240 67 0 1 247.

Parameters

Name	Default	Range	Description
sysex	—	0-255, $i1-$i9, sumstart, sum	The message, one token per byte: a number 0-255, a placeholder $i1 to $i9 filled from the inlets, “sumstart” to start the checksum region, or “sum” for the checksum byte.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Use it to receive the answer to a request built with .sxformat. Nothing is collected: bytes are sent as they arrive, so collect a whole dump downstream, for example with .zl group, and watch for the 247 that ends it.

Clock bytes inside a dump are dropped. A status byte other than 247 ends the dump without a 247 on the outlet, which happens when a device is interrupted mid-transfer. A second 240 starts a new dump.

The port argument and the size limit work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	byte	INT	0-247	Each byte of a system-exclusive message, in arrival order: 240, the manufacturer ID, the data, then 247.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.

`.touchin`#

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Most keyboards with aftertouch send this kind: one pressure value for the whole channel, from the hardest-pressed key. Per-key pressure is .polyin’s.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	pressure	INT	0-127	Channel pressure: one value however many keys are held. Per-key pressure is .polyin’s.
1	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

`.xbendin`#

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Reports both bytes of the pitch-bend message combined. Subtract 8192 before scaling the value into a bend amount. .bendin reports only the coarse byte, and .xbendin2 reports the two bytes separately.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	bend	INT	0-16383	The wheel position: 0 fully down, 8192 at rest, 16383 fully up.
1	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Use it when the two bytes are wanted apart, or to pass a bend through .xbendout2 unchanged. .xbendin reports the same message as one number.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	msb	INT	0-127	The coarse byte, 64 at rest: the value .bendin reports. Sent last.
1	lsb	INT	0-127	The fine byte: 128 steps between one coarse value and the next.
2	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

`.xbendout`#

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

Kind:: Control-rate

The value is clamped to 0-16383. The channel argument and the output work as described under .noteon.

Inlets

#	Label	Accepts	Range	Description
0	bend	INT	0-16383	Pitch bend, 8192 at rest; sends the message.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The pitch-bend message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

`.xbendout2`#

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

Kind:: Control-rate

The left inlet takes the coarse byte (64 at rest) and sends; the right inlet stores the fine byte. Both are clamped to 0-127. The channel argument and the output work as described under .noteon.

Inlets

#	Label	Accepts	Range	Description
0	msb	INT	0-127	Coarse byte, 64 at rest; sends the message.
1	lsb	INT	0-127	Fine byte, stored for the next coarse byte.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The pitch-bend message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

MIDI pairs controllers 0-31 with controllers 32-63 as the coarse and fine halves of one 14-bit value. A value is reported when the coarse controller arrives, with the fine half as 0, and again when the fine controller follows. A device that sends only the coarse half is reported in steps of 128.

The coarse value is remembered per channel and controller. Controllers 64-127 have no fine half and are not reported; use .ctlin for them.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	value	INT	0-16383	The controller’s value. Sent last. A device that sends only the coarse controller moves in steps of 128.
1	controller	INT	0-31	The coarse controller number, whichever of the pair moved.
2	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.
controller	-1	-1 to 31	Coarse controller number to listen to, 0-31, or -1 for all of them. Any other value means all of them.

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

Kind:: Control-rate

Each value sends two control-change messages: the coarse half on the controller number, then the fine half on that number plus 32. Only controllers 0-31 have a fine half, so the controller number is clamped to 0-31. The value is clamped to 0-16383.

The channel argument and the output work as described under .noteon.

Inlets

#	Label	Accepts	Range	Description
0	value	INT	0-16383	Controller value; sends both messages.
1	controller	INT	0-31	Coarse controller number, stored for the next value. The fine half goes to this number plus 32.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	Two control-change messages, coarse then fine, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

Unlike .midiin, which sends single bytes, this object sends each complete message as one list, ready for .midiparse, .seq or .midiout.

Messages sent under running status get their status byte back.
A clock byte (248-255) is sent at once as a list of its own, without disturbing the message it arrived in.
A new status byte drops an unfinished message.
A system-exclusive dump longer than 256 bytes leaves in consecutive 256-byte lists.

The port argument and the size limit work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	0-255 per byte	One message per list: the status byte, then its data bytes. A clock byte is a list of one; a system-exclusive dump longer than 256 bytes leaves in 256-byte lists.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.

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

Kind:: Control-rate
Availability:: MIDI device only

Note

A note-off message carries a release velocity: how fast the key came up. .notein discards it; this object reports it. The velocity outlet still reports 0 for every release, so a patch tests for a release the same way as with .notein. A note-on with velocity 0 has no release velocity and reports 0 for both.

Port and channel arguments, and the order of the outlets, work as described under .midiin.

Outlets

#	Label	Type	Range	Description
0	pitch	INT	0-127	The note number; middle C is 60. Sent last.
1	velocity	INT	0-127	How hard the key was struck, or 0 for a release, as .notein reports.
2	release	INT	0-127	How fast the key came up, from a note-off message. 0 on a note-on, including one with velocity 0.
3	channel	INT	1-16	The channel the message arrived on, 1-16. Sent before the outlets to its left.

Parameters

Name	Default	Range	Description
port	0	0-7	MIDI input port to listen to, counted from 0; .midiinfo lists them. A port that cannot be opened leaves the object silent, and the patch still loads.
channel	0	0-16	MIDI channel to listen to, 1-16, or 0 for all channels. Any other value means all channels. The channel outlet stays either way.

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

Kind:: Control-rate

A velocity above 0 sends a note-on. A velocity of 0 sends a note-off message carrying the release velocity from the right inlet, which defaults to 64. All three values are clamped to 0-127. The middle and right inlets store their value for the next pitch.

The channel argument and the output work as described under .noteon.

Inlets

#	Label	Accepts	Range	Description
0	pitch	INT	0-127	Note number; sends the message.
1	velocity	INT	0-127	Note velocity, stored for the next pitch. 0 makes the message a note-off.
2	release	INT	0-127	Release velocity, stored for the next pitch and used only when the velocity is 0. Starts at 64.

Outlets

#	Label	Type	Range	Description
0	midi	LIST	—	The note-on or note-off message, for .midiout.

Parameters

Name	Default	Range	Description
channel	0	0-15	MIDI channel, counted from 0: 0 is channel 1.

MIDI

Contents

MIDI#