HelpSource/Classes/MIDIResponder.schelp

   1 class:: MIDIResponder
   2 summary:: Register multiple functions to be evaluated when MIDI events occur
   3 related:: Classes/MIDIFunc, Classes/MIDIdef, Classes/MIDIIn, Guides/MIDI, Guides/UsingMIDI
   4 categories:: External Control>MIDI
   5
   6 description::
   7 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 still lack some features of the MIDIresponder classes.::
   8
   9 MIDIResponder is an emphasis::abstract:: class. Its subclasses allow functions to be registered to respond to midi events.
  10
  11 Read the general help file here and then see the individual help files.
  12
  13 definitionList::
  14 ## link::Classes/CCResponder:: || Respond to control messages
  15 ## link::Classes/NoteOnResponder:: || Respond to note-on messages
  16 ## link::Classes/NoteOffResponder:: || Respond to note-off messages
  17 ## link::Classes/BendResponder:: || Respond to pitch bend messages
  18 ## link::Classes/TouchResponder:: || Respond to aftertouch messages
  19 ## link::Classes/ProgramChangeResponder:: || Respond to programchange messages
  20 ::
  21
  22 subsection::Creation and initialization
  23
  24 list::
  25 ## CCResponder(function, src, chan, num, value, install = true, swallowEvent = false)
  26 ## NoteOnResponder(function, src, chan, num, veloc, install = true, swallowEvent = false)
  27 ## NoteOffResponder(function, src, chan, num, veloc, install = true, swallowEvent = false)
  28 ## BendResponder(function, src, chan, value, install = true, swallowEvent = false)
  29 ## TouchResponder(function, src, chan, value, install = true, swallowEvent = false)
  30 ## ProgramChangeResponder(function, src, chan, value, install = true)
  31 ::
  32
  33 definitionList::
  34
  35 ## 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).
  36
  37 ## 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.
  38
  39 ## chan || The MIDI channel(s) to match.
  40
  41 ## num || The control or note number(s) to match.
  42
  43 ## value || The value(s) to match.
  44
  45 ## veloc || The velocities to match.
  46
  47 ## install || If true, install the responder automatically so it is active and ready to respond. If false, then it will be inactive.
  48
  49 ## 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.
  50
  51 ::
  52
  53 Any of the matching values may be one of the following:
  54
  55 definitionList::
  56 ## Nil || Match anything. eg. if chan is nil, then respond to any MIDI channel.
  57 ## Integer || Match only this specific number.
  58 ## Array || Match any item in the array. Any kind of link::Classes/Collection:: will work here.
  59 ## Function || Evaluate the function with the incoming value as the argument. The function should return true or false.
  60 ::
  61
  62 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.
  63 code::
  64 NoteOnResponder({ |src, chan, num, vel| [src, chan, num, vel].postln },
  65         nil,    // any port
  66         [2, 7], // midi channels 2 or 7 only
  67         (0, 2..126),    // this is an array of even numbers. could also be specified as { |num| num.even } or _.even
  68         { |vel| vel > 50 });    // velocities greater than 50
  69 ::
  70
  71 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.
  72
  73 subsection::Removal
  74
  75 Just call .remove on the responder.
  76 code::
  77 c = CCResponder({ ... }, num: 1);       // respond to any modwheel
  78
  79 c.remove;               // stop this responder
  80 ::
  81
  82 Or remove all of a specific class:
  83 code::
  84 CCResponder.removeAll
  85 NoteOnResponder.removeAll
  86 NoteOffResponder.removeAll
  87 BendResponder.removeAll
  88 TouchResponder.removeAll
  89 ProgramChange.removeAll
  90 ::
  91
  92 or remove all midi responders in all classes:
  93 code::
  94 MIDIResponder.removeAll
  95 ::