96 lines
4.6 KiB
Text
96 lines
4.6 KiB
Text
|
class:: MIDIResponder
|
||
|
|
summary:: Register multiple functions to be evaluated when MIDI events occur
|
||
|
|
related:: Classes/MIDIFunc, Classes/MIDIdef, Classes/MIDIIn, Guides/MIDI, Guides/UsingMIDI
|
||
|
|
categories:: External Control>MIDI
|
||
|
|
|
||
|
|
description::
|
||
|
|
note:: SC 3.5 added the link::Classes/MIDIFunc:: and link::Classes/MIDIdef:: classes. These are faster, and aim to have a more convenient, logical and consistent interface, which shares a common design with link::Classes/OSCFunc:: and link::Classes/OSCdef::. They also provide support for all MIDI message types.::
|
||
|
|
|
||
|
|
MIDIResponder is an emphasis::abstract:: class. Its subclasses allow functions to be registered to respond to midi events.
|
||
|
|
|
||
|
|
Read the general help file here and then see the individual help files.
|
||
|
|
|
||
|
|
definitionList::
|
||
|
|
## link::Classes/CCResponder:: || Respond to control messages
|
||
|
|
## link::Classes/NoteOnResponder:: || Respond to note-on messages
|
||
|
|
## link::Classes/NoteOffResponder:: || Respond to note-off messages
|
||
|
|
## link::Classes/BendResponder:: || Respond to pitch bend messages
|
||
|
|
## link::Classes/TouchResponder:: || Respond to aftertouch messages
|
||
|
|
## link::Classes/ProgramChangeResponder:: || Respond to programchange messages
|
||
|
|
::
|
||
|
|
|
||
|
|
subsection::Creation and initialization
|
||
|
|
|
||
|
|
list::
|
||
|
|
## CCResponder(function, src, chan, num, value, install = true, swallowEvent = false)
|
||
|
|
## NoteOnResponder(function, src, chan, num, veloc, install = true, swallowEvent = false)
|
||
|
|
## NoteOffResponder(function, src, chan, num, veloc, install = true, swallowEvent = false)
|
||
|
|
## BendResponder(function, src, chan, value, install = true, swallowEvent = false)
|
||
|
|
## TouchResponder(function, src, chan, value, install = true, swallowEvent = false)
|
||
|
|
## ProgramChangeResponder(function, src, chan, value, install = true)
|
||
|
|
::
|
||
|
|
|
||
|
|
definitionList::
|
||
|
|
|
||
|
|
## function || The function to execute when the incoming MIDI event matches the responder. The function takes the arguments src, chan, A, B (or for Bend, ProgramChange and Touch: src, chan, value).
|
||
|
|
|
||
|
|
## src || If a number is given, the responder will fire only for messages coming in from this port. The number may be the system UID (obtained from MIDIClient.sources[index].uid) or the index itself. If nil, the responder will match any port.
|
||
|
|
|
||
|
|
## chan || The MIDI channel(s) to match.
|
||
|
|
|
||
|
|
## num || The control or note number(s) to match.
|
||
|
|
|
||
|
|
## value || The value(s) to match.
|
||
|
|
|
||
|
|
## veloc || The velocities to match.
|
||
|
|
|
||
|
|
## install || If true, install the responder automatically so it is active and ready to respond. If false, then it will be inactive.
|
||
|
|
|
||
|
|
## swallowEvent || If true, then if the midi event is matched, cease testing any further responders. eg. if a CCResponder matches port, chan and num, and swallowEvent is set to true, then no further CCResponders will be offered the chance to respond to the event. The event is "swallowed". By default this is false. Note that doing this will prevent any other responders of this type from responding, including ones added behind the scenes in classes. Note also that this functionality is sensitive to the order in which responders are added.
|
||
|
|
|
||
|
|
::
|
||
|
|
|
||
|
|
Any of the matching values may be one of the following:
|
||
|
|
|
||
|
|
definitionList::
|
||
|
|
## Nil || Match anything. eg. if chan is nil, then respond to any MIDI channel.
|
||
|
|
## Integer || Match only this specific number.
|
||
|
|
## Array || Match any item in the array. Any kind of link::Classes/Collection:: will work here.
|
||
|
|
## Function || Evaluate the function with the incoming value as the argument. The function should return true or false.
|
||
|
|
::
|
||
|
|
|
||
|
|
For instance, the following example would respond to note on messages from any port, channels 2 and 7 only, even numbered note numbers only, and only velocity values greater than 50.
|
||
|
|
code::
|
||
|
|
NoteOnResponder({ |src, chan, num, vel| [src, chan, num, vel].postln },
|
||
|
|
nil, // any port
|
||
|
|
[2, 7], // midi channels 2 or 7 only
|
||
|
|
(0, 2..126), // this is an array of even numbers. could also be specified as { |num| num.even } or _.even
|
||
|
|
{ |vel| vel > 50 }); // velocities greater than 50
|
||
|
|
::
|
||
|
|
|
||
|
|
MIDIResponders automatically initialize the MIDIClient with 1 standard device. This means the first time you install any MIDIResponder, it will make sure that MIDI has been initialized. If you have more devices or a specific setup, simply initialize the MIDIClient yourself before using any MIDIResponders.
|
||
|
|
|
||
|
|
subsection::Removal
|
||
|
|
|
||
|
|
Just call .remove on the responder.
|
||
|
|
code::
|
||
|
|
c = CCResponder({ ... }, num: 1); // respond to any modwheel
|
||
|
|
|
||
|
|
c.remove; // stop this responder
|
||
|
|
::
|
||
|
|
|
||
|
|
Or remove all of a specific class:
|
||
|
|
code::
|
||
|
|
CCResponder.removeAll
|
||
|
|
NoteOnResponder.removeAll
|
||
|
|
NoteOffResponder.removeAll
|
||
|
|
BendResponder.removeAll
|
||
|
|
TouchResponder.removeAll
|
||
|
|
ProgramChange.removeAll
|
||
|
|
::
|
||
|
|
|
||
|
|
or remove all midi responders in all classes:
|
||
|
|
code::
|
||
|
|
MIDIResponder.removeAll
|
||
|
|
::
|