SuperCollider CLASSES

MIDIFunc

Fast Responder for incoming MIDI Messages
Inherits from: AbstractResponderFunc : Object
Subclasses: MIDIdef

Description

MIDIFunc (and its subclass MIDIdef) registers one or more functions to respond to an incoming MIDI message. Many of its methods are inherited from its superclass AbstractResponderFunc.

NOTE: MIDIFunc and MIDIdef aim to improve upon the MIDIresponder classes by being faster, easier to use, and providing support for all MIDI message types. They were made with the intention of creating a more convenient, logical and consistent interface, which shares a common design with OSCFunc and OSCdef. Note that unlike the older classes, MIDIFuncs are removed on Cmd-. by default. This can be overridden using either of the fix or permanent methods.

Class Methods

*defaultDispatchers

*defaultDispatchers = value

Get or set an IdentityDictionary containing the default dispatcher objects for MIDIFuncs of different types (these are what you get if you pass nil as the dispatcher argument to *new). These objects will decide if any of their registered MIDIFuncs should respond to an incoming MIDI message. The dictionary should have the keys [\noteOn, \noteOff, \control, \polytouch, \touch, \program, \bend] and values of an appropriate subclass of AbstractDispatcher for each message type. By default these will be instances of MIDIMessageDispatcher for the the first four message types, and instances of MIDIMessageDispatcherNV for the last three.

Returns:

The getter returns an IdentityDictionary.

*new (func, msgNum, chan, msgType, srcID, argTemplate, dispatcher)

Create a new, enabled MIDIFunc. Normally one would use one of the message type specific convenience methods below, rather than use this method directly.

Arguments:

func

A Function or similar object which will respond to the incoming message. When evaluated for noteOn, noteOff, control, and polytouch messages it will be passed the arguments val, num, chan, and src, corresponding to the message value (e.g. velocity, control value, etc.), message number (e.g. note number), MIDI channel, and MIDI source uid. For touch, program change and bend messages it will be passed only val, chan, and src. For information on the args passed for the other sorts of msgType see the convenience methods below.

msgNum

An Integer indicating the MIDI message number (note number, control number, or program number) for this MIDIFunc. This can be an array. If nil, the MIDIFunc will respond to messages of all possible message numbers.

chan

An Integer indicating the MIDI channel number for this MIDIFunc. This can be an array. If nil, the MIDIFunc will respond to messages received on all channels.

msgType

A Symbol indicating which kind of MIDI message this MIDIFunc should respond to. One of \noteOn, \noteOff, \control, \touch, \polytouch, \bend, \program, \sysex, \mtcQF, \smpte, \songPosition, \songSelect, \tuneRequest, \midiClock, \sysrt, \tick, \start, \continue, \stop, \activeSense, or \reset.

srcID

An Integer corresponding to the uid of the MIDI input. (See MIDIClient.) If nil, the MIDIFunc will respond to messages received from all sources.

argTemplate

An optional Integer or Function (or object which responds to the method Methods: matchItem) used to match the value of an incoming MIDI message. (e.g. velocity, control value, program number, etc.). If a Function, it will be evaluated with the message value as an argument, and should return a Boolean indicating whether the message matches and this MIDIFunc should respond.

dispatcher

An optional instance of an appropriate subclass of AbstractDispatcher. This can be used to allow for customised dispatching. Normally this should not be needed.

Returns:

A new instance of MIDIFunc.

*cc (func, ccNum, chan, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI control messages. See *new for argument descriptions.

Returns:

A new instance of MIDIFunc which responds to MIDI control messages.

*noteOn (func, noteNum, chan, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI note on messages. See *new for argument descriptions.

Returns:

A new instance of MIDIFunc which responds to MIDI note on messages.

*noteOff (func, noteNum, chan, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI note off messages. See *new for argument descriptions.

Returns:

A new instance of MIDIFunc which responds to MIDI note off messages.

*polytouch (func, noteNum, chan, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI polytouch messages. See *new for argument descriptions.

Returns:

A new instance of MIDIFunc which responds to MIDI polytouch messages.

*touch (func, chan, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI touch messages. See *new for argument descriptions.

Returns:

A new instance of MIDIFunc which responds to MIDI touch messages.

*bend (func, chan, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI bend messages. See *new for argument descriptions.

Returns:

A new instance of MIDIFunc which responds to MIDI bend messages.

*program (func, chan, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI program change messages. See *new for argument descriptions.

Returns:

A new instance of MIDIFunc which responds to MIDI program change messages.

*sysex (func, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI system exclusive messages. See *new for argument descriptions. The responding func will be passed the arguments data (an Int8Array) and srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI system exclusive messages.

System Common

N.B. Because of SC's underlying low level MIDI implementation, there is no generic msgType and convenience method for System Common messages. Instead these are grouped with System Realtime under *sysrt below.

*smpte (func, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI smpte messages. See *new for argument descriptions. The responding func will be passed the arguments seconds, framerate, dropframe, and srcID. (dropframe is a Boolean).

Returns:

A new instance of MIDIFunc which responds to MIDI smpte messages.

*mtcQuarterFrame (func, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI Time Code Quarter Frame messages. Note that the smpte method above automatically assembles quarter frames into time code. See *new for argument descriptions. The responding func will be passed the arguments data, srcID, and pieceNumber. You will need to manually assemble each 8 messages into smpte.

Returns:

A new instance of MIDIFunc which responds to MIDI Time Code Quarter Frame messages.

*songPosition (func, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI song position messages. See *new for argument descriptions. The responding func will be passed the arguments position and srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI song position messages.

*songSelect (func, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI song select messages. See *new for argument descriptions. The responding func will be passed the arguments song and srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI song select messages.

*tuneRequest (func, srcID, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI tune request messages. See *new for argument descriptions. The responding func will be passed the argument srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI tune request messages.

*midiClock (func, srcID, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI clock messages. See *new for argument descriptions. The responding func will be passed the argument srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI clock messages.

System Realtime

*sysrt (func, index, srcID, argTemplate, dispatcher)

A convenience method to create a new MIDIFunc which responds generically to MIDI System Realtime and System Common messages. Note that the message specific methods above and below are probably more convenient in most cases. Note that this does not include MIDI Time Code Quarter Frame messages (sysrt index 1). For those see *mtcQuarterFrame and *smpte. See *new for argument descriptions. The responding func will be passed the arguments data (may be nil), srcID, and index. Index indicates the message type as follows:
MIDI Time Code Quarter Frames1
Song Position2
Song Select3
Tune Request6
MIDI Clock8
Tick9
Start10
Continue11
Stop12
Active Sense14
Reset15

Returns:

A new instance of MIDIFunc which responds to MIDI System Realtime messages.

*tick (func, srcID, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI tick messages. See *new for argument descriptions. The responding func will be passed the argument srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI tick messages.

*start (func, srcID, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI start messages. See *new for argument descriptions. The responding func will be passed the argument srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI start messages.

*stop (func, srcID, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI stop messages. See *new for argument descriptions. The responding func will be passed the argument srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI stop messages.

*continue (func, srcID, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI continue messages. See *new for argument descriptions. The responding func will be passed the argument srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI continue messages.

*reset (func, srcID, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI reset messages. See *new for argument descriptions. The responding func will be passed the argument srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI reset messages.

*activeSense (func, srcID, dispatcher)

A convenience method to create a new MIDIFunc which responds to MIDI active sense messages. See *new for argument descriptions. The responding func will be passed the argument srcID.

Returns:

A new instance of MIDIFunc which responds to MIDI active sense messages.

Debugging

*trace (bool: true)

A convenience method which dumps all incoming MIDI messages.

Arguments:

bool

A Boolean indicating whether dumping is on or off.

Inherited class methods

Instance Methods

-chan

Get this MIDIFunc's MIDI channel number.

Returns:

An Integer.

-msgNum

Get this MIDIFunc's MIDI message number.

Returns:

An Integer.

-msgType

Get this MIDIFunc's message type.

Returns:

A Symbol; one of \noteOn, \noteOff, \control, \touch, \polytouch, \bend, \program, \sysex, \mtcQF, \smpte, \songPosition, \songSelect, \tuneRequest, \midiClock, \sysrt, \tick, \start, \continue, \stop, \activeSense, or \reset.

-argTemplate

Get this MIDIFunc's argTemplate.

Returns:

A Integer or Function (or object which responds to the method Methods: matchItem) used to match the value of an incoming MIDI message. (e.g. velocity, control value, program number, etc.).

-learn (learnVal: false)

Train this MIDIFunc to respond to the next message of its type. Arguments passed at creation (e.g. chan, srcID, msgNum, etc.) will filter the training to the next matching message received.

Arguments:

learnVal

A Boolean indicating whether the responder should learn the specific value. For example, if used with a control change MIDIFunc, the object would learn to match the next specific control change value. If used with a note on MIDIFunc, it would match only a specific velocity. The default is false.

Inherited instance methods

Undocumented instance methods

-learnFunc (learnVal)

Examples

MIDIIn.connectAll

a = MIDIFunc.cc({arg ...args; args.postln}, 1); // match cc 1
a.free; // cleanup

b = MIDIFunc.cc({arg ...args; args.postln}, 1, 1); // match cc1, chan 1
b.free; // cleanup

c = MIDIFunc.cc({arg ...args; args.postln}, (1..10)); // match cc 1-10
c.free; // cleanup

n = MIDIFunc.noteOn({arg ...args; args.postln}); // match any noteOn
n.free; // cleanup

MIDIIn.doNoteOnAction(1, 1, 64, 64); // spoof a note on
MIDIIn.doControlAction(1, 1, 1, 64); // spoof a cc
MIDIIn.doControlAction(1, 1, 9, 64);
MIDIIn.doControlAction(1, 10, 1, 64);