Classes | External Control > MIDI

MIDIOut : Object

send MIDI messages
Source: MIDIOut.sc


a MIDIOut is bound to a specific MIDIEndPoint as defined by the operating system.

Linux users, or any users who require cross-platform compatibility with Linux, should read Linux specific: Connecting and disconnecting ports carefully.

Class Methods

MIDIOut.new(port, uid)

Create a new MIDIOut instance. Note that this method is not safe for cross-platform usage with Linux, because the meaning of the port argument is different. See Linux specific: Connecting and disconnecting ports for details.


macOS, Windows
The index of the MIDIEndPoint in the MIDIClient.destinations array.
The output port number. MIDIEndPoint("SuperCollider", "out0") is port 0; "out1" is port 1. In Linux, this argument has no connection at all to MIDIClient.destinations.
macOS / Windows
uid is optional; if specified, it should be the uid of that port ie. MIDIClient.destinations[port].uid. If you don't provide a uid, the correct uid will be filled in for you (easier).
using the uid is optional as described below.

MIDIOut.newByName(deviceName, portName, dieIfNotFound: true)

Searches for the MIDI output device, by a name found in the MIDIClient.destinations array. This is safer then depending on the index which will change if your studio setup changes. It is also Linux compatible.

MIDIOut.findPort(deviceName, portName)

Searches for a connected MIDIEndPoint by name.

MIDIOut.connect(outport: 0, device: 0)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/Platform/linux/SystemOverwrites/extMIDIOut.sc

MIDIOut.disconnect(outport: 0, device: 0)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/Platform/linux/SystemOverwrites/extMIDIOut.sc

Linux only. MacOS does not need to connect. On Linux it is an optional feature (see below).

Inherited class methods

Instance Methods


Sends a sysex command represented as an Int8Array to the device.

NOTE: On Windows, the function call must contain a full sysex message. In other words, it must start with 0xF0 (240 or -16) and end with 0xF7 (247 or -9).



An Int8Array of data bytes to be sent.


.latency = value

This sets the latency with which a midi event is sent out. Per default this is set to 0.2, in order to be equal to the Server.latency.

NOTE: On Linux there seems to be an ALSA or kernel bug if the latency is larger than 0, for some Linux kernels. If MIDIOut does not seem to work, set the latency to 0.

Inherited instance methods

Undocumented instance methods


.bend(chan, val: 8192)

.connect(device: 0)

From extension in /usr/local/share/SuperCollider/SCClassLibrary/Platform/linux/SystemOverwrites/extMIDIOut.sc


.control(chan, ctlNum: 7, val: 64)


From extension in /usr/local/share/SuperCollider/SCClassLibrary/Platform/linux/SystemOverwrites/extMIDIOut.sc


.noteOff(chan, note: 60, veloc: 64)

.noteOn(chan, note: 60, veloc: 64)

.polyTouch(chan, note: 60, val: 64)


.port = value

.program(chan, num: 1)


.smpte(frames: 0, seconds: 0, minutes: 0, hours: 0, frameRate: 3)





.touch(chan, val: 64)


.uid = value

.write(len, hiStatus, loStatus, a: 0, b: 0)


Using patterns for sending MIDI events

See Pattern Guide 08: Event Types and Parameters: MIDI output for a list of midi commands supported by the 'midi' event type.

Linux specific: Connecting and disconnecting ports

In Linux, the MIDIOut architecture is different from other operating systems.

In macOS and Windows, a MIDIOut instance is bound to a specific destination MIDI device.

SuperCollider in Linux uses the ALSA MIDI layer. ALSA MIDI applications send messages out through a "virtual output port," which is one of the members of MIDIClient.sources.

MIDI Sources:
    MIDIEndPoint("System", "Timer")
    MIDIEndPoint("System", "Announce")
    MIDIEndPoint("Midi Through", "Midi Through Port-0")
    MIDIEndPoint("SuperCollider", "out0")
    MIDIEndPoint("SuperCollider", "out1")

At this point, creating MIDIOut(0) tells SuperCollider that this MIDIOut object should direct messages to MIDIEndPoint("SuperCollider", "out0"). (It seems strange, if you think of SuperCollider sending messages to this MIDI source. It is more accurate to think of SuperCollider sending messages through this port. The port is, then, a source for the rest of the system.)

A MIDIOut(0) object, then, will not reach any destinations by default. The user needs to connect destination devices to the virtual source port, using either a graphical tool such as Qjackctl, or by MIDIOut's connect method.

WARNING: The port argument to MIDIOut: *new has an entirely different meaning in Linux, compared to macOS and Windows. If user code calls this method and cross-platform compatibility is needed, it is the user's responsibility to handle Linux separately. User code can check the platform using thisProcess.platform.name (which returns one of \osx, \linux or \windows). Or, for compatibility, use *newByName instead.

MIDIOut: *new optionally takes a second argument, for the uid of the MIDI destination device. This establishes a direct connection to the target, which is not visible in Qjackctl. The port argument is irrelevant in this case; the MIDIOut instance is always one-to-one with the target.

MIDIOut: *newByName should create one-to-one MIDIOut connections on all platforms.


macOS specific: Sending MIDI to other applications

Open the Audio MIDI Setup application. Double-click on IAC Driver and check "device is online".



The IAC Bus will now appear in MIDIClient.destinations. It will appear first, which means that any code that you have written that addresses the first physical bus as 0 will now have to be changed.

For this reason it is always safer to find the port by name :

The IAC Bus will now also appear to other applications.

MIDIMonitor (freeware) can be very useful for troubleshooting:


Sysex example

a machinedrum manual say sysex commands should be formatted like this...

and to set the tempo the machinedrum expects this command...

so to create and send a valid set tempo sysex command from SuperCollider to this machinedrum do...

This will set the tempo to 114.23 bpm. One can calculate the upper and lower 7bit values like this...

where the resulting 21 and 54 are the same as 2r0010101 and 2r0110110 in binary notation.