-
Notifications
You must be signed in to change notification settings - Fork 731
/
MIDIFunc.schelp
230 lines (150 loc) · 13.1 KB
/
MIDIFunc.schelp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
CLASS:: MIDIFunc
summary:: Fast Responder for incoming MIDI Messages
categories:: External Control>MIDI
related:: Guides/MIDI, Classes/MIDIdef
DESCRIPTION::
MIDIFunc (and its subclass link::Classes/MIDIdef::) registers one or more functions to respond to an incoming MIDI message. Many of its methods are inherited from its superclass link::Classes/AbstractResponderFunc::.
subsection:: Important note on persistence
MIDIFunc (and its subclass link::Classes/MIDIdef:: like all other
AbstractResponderFuncs) are removed on pressing Cmd/ctrl-. To override this
behavior, use the link::Classes/AbstractResponderFunc#-permanent:: method.
CLASSMETHODS::
private:: initClass, cmdPeriod
METHOD:: defaultDispatchers
Get or set an link::Classes/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 link::#*new::). These objects will decide if any of their registered MIDIFuncs should respond to an incoming MIDI message. The dictionary should have the keys code::[\noteOn, \noteOff, \control, \polytouch, \touch, \program, \bend]:: and values of an appropriate subclass of link::Classes/AbstractDispatcher:: for each message type. By default these will be instances of link::Classes/MIDIMessageDispatcher:: for the first four message types, and instances of link::Classes/MIDIMessageDispatcherNV:: for the last three.
returns:: The getter returns an link::Classes/IdentityDictionary::.
METHOD:: new
Create a new, enabled MIDIFunc. Normally one would use one of the message type specific convenience methods below, rather than use this method directly.
argument:: func
A link::Classes/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 code::msgType:: see the convenience methods below.
argument:: msgNum
An link::Classes/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.
argument:: chan
An link::Classes/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.
argument:: msgType
A link::Classes/Symbol:: indicating which kind of MIDI message this MIDIFunc should respond to. One of code::\noteOn::, code::\noteOff::, code::\control::, code::\touch::, code::\polytouch::, code::\bend::, code::\program::, code::\sysex::, code::\mtcQF::, code::\smpte::, code::\songPosition::, code::\songSelect::, code::\tuneRequest::, code::\midiClock::, code::\sysrt::, code::\tick::, code::\start::, code::\continue::, code::\stop::, code::\activeSense::, or code::\reset::.
argument:: srcID
An link::Classes/Integer:: corresponding to the uid of the MIDI input. (See link::Guides/UsingMIDI#MIDIFunc and MIDIdef: Filtering based on device or message data::.) If nil, the MIDIFunc will respond to messages received from all sources.
argument:: argTemplate
An optional link::Classes/Integer:: or link::Classes/Function:: (or object which responds to the method link::Overviews/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 link::Classes/Boolean:: indicating whether the message matches and this MIDIFunc should respond.
argument:: dispatcher
An optional instance of an appropriate subclass of link::Classes/AbstractDispatcher::. This can be used to allow for customised dispatching. Normally this should not be needed.
returns:: A new instance of MIDIFunc.
METHOD:: cc
A convenience method to create a new MIDIFunc which responds to MIDI control messages. See link::#*new:: for argument descriptions.
returns:: A new instance of MIDIFunc which responds to MIDI control messages.
METHOD:: noteOn
A convenience method to create a new MIDIFunc which responds to MIDI note on messages. See link::#*new:: for argument descriptions.
returns:: A new instance of MIDIFunc which responds to MIDI note on messages.
METHOD:: noteOff
A convenience method to create a new MIDIFunc which responds to MIDI note off messages. See link::#*new:: for argument descriptions.
returns:: A new instance of MIDIFunc which responds to MIDI note off messages.
METHOD:: polytouch
A convenience method to create a new MIDIFunc which responds to MIDI polytouch messages. See link::#*new:: for argument descriptions.
returns:: A new instance of MIDIFunc which responds to MIDI polytouch messages.
METHOD:: touch
A convenience method to create a new MIDIFunc which responds to MIDI touch messages. See link::#*new:: for argument descriptions.
returns:: A new instance of MIDIFunc which responds to MIDI touch messages.
METHOD:: bend
A convenience method to create a new MIDIFunc which responds to MIDI bend messages. See link::#*new:: for argument descriptions.
returns:: A new instance of MIDIFunc which responds to MIDI bend messages.
METHOD:: program
A convenience method to create a new MIDIFunc which responds to MIDI program change messages. See link::#*new:: for argument descriptions.
returns:: A new instance of MIDIFunc which responds to MIDI program change messages.
METHOD:: sysex
A convenience method to create a new MIDIFunc which responds to MIDI system exclusive messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the arguments data (an link::Classes/Int8Array::) and srcID.
returns:: A new instance of MIDIFunc which responds to MIDI system exclusive messages.
SUBSECTION:: System Common
N.B. Because of SC's underlying low level MIDI implementation, there is no generic code::msgType:: and convenience method for System Common messages. Instead these are grouped with System Realtime under link::#*sysrt:: below.
METHOD:: smpte
A convenience method to create a new MIDIFunc which responds to MIDI smpte messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the arguments seconds, framerate, dropframe, and srcID. (dropframe is a link::Classes/Boolean::).
returns:: A new instance of MIDIFunc which responds to MIDI smpte messages.
METHOD:: mtcQuarterFrame
A convenience method to create a new MIDIFunc which responds to MIDI Time Code Quarter Frame messages. Note that the link::#*smpte:: method above automatically assembles quarter frames into time code. See link::#*new:: for argument descriptions. The responding code::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.
METHOD:: songPosition
A convenience method to create a new MIDIFunc which responds to MIDI song position messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the arguments position and srcID.
returns:: A new instance of MIDIFunc which responds to MIDI song position messages.
METHOD:: songSelect
A convenience method to create a new MIDIFunc which responds to MIDI song select messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the arguments song and srcID.
returns:: A new instance of MIDIFunc which responds to MIDI song select messages.
METHOD:: tuneRequest
A convenience method to create a new MIDIFunc which responds to MIDI tune request messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the argument srcID.
returns:: A new instance of MIDIFunc which responds to MIDI tune request messages.
METHOD:: midiClock
A convenience method to create a new MIDIFunc which responds to MIDI clock messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the argument srcID.
returns:: A new instance of MIDIFunc which responds to MIDI clock messages.
SUBSECTION:: System Realtime
METHOD:: sysrt
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 link::#*mtcQuarterFrame:: and link::#*smpte::. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the arguments data (may be nil), srcID, and index. Index indicates the message type as follows:
table::
## MIDI Time Code Quarter Frames || 1
## Song Position || 2
## Song Select || 3
## Tune Request || 6
## MIDI Clock || 8
## Tick || 9
## Start || 10
## Continue || 11
## Stop || 12
## Active Sense || 14
## Reset || 15
::
returns:: A new instance of MIDIFunc which responds to MIDI System Realtime messages.
METHOD:: tick
A convenience method to create a new MIDIFunc which responds to MIDI tick messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the argument srcID.
returns:: A new instance of MIDIFunc which responds to MIDI tick messages.
METHOD:: start
A convenience method to create a new MIDIFunc which responds to MIDI start messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the argument srcID.
returns:: A new instance of MIDIFunc which responds to MIDI start messages.
METHOD:: stop
A convenience method to create a new MIDIFunc which responds to MIDI stop messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the argument srcID.
returns:: A new instance of MIDIFunc which responds to MIDI stop messages.
METHOD:: continue
A convenience method to create a new MIDIFunc which responds to MIDI continue messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the argument srcID.
returns:: A new instance of MIDIFunc which responds to MIDI continue messages.
METHOD:: reset
A convenience method to create a new MIDIFunc which responds to MIDI reset messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the argument srcID.
returns:: A new instance of MIDIFunc which responds to MIDI reset messages.
METHOD:: activeSense
A convenience method to create a new MIDIFunc which responds to MIDI active sense messages. See link::#*new:: for argument descriptions. The responding code::func:: will be passed the argument srcID.
returns:: A new instance of MIDIFunc which responds to MIDI active sense messages.
SUBSECTION:: Debugging
METHOD:: trace
A convenience method which dumps all incoming MIDI messages.
argument:: bool
A link::Classes/Boolean:: indicating whether dumping is on or off.
INSTANCEMETHODS::
private:: init, printOn
METHOD:: chan
Get this MIDIFunc's MIDI channel number.
returns:: An link::Classes/Integer::.
METHOD:: msgNum
Get this MIDIFunc's MIDI message number.
returns:: An link::Classes/Integer::.
METHOD:: msgType
Get this MIDIFunc's message type.
returns:: A link::Classes/Symbol::; one of code::\noteOn::, code::\noteOff::, code::\control::, code::\touch::, code::\polytouch::, code::\bend::, code::\program::, code::\sysex::, code::\mtcQF::, code::\smpte::, code::\songPosition::, code::\songSelect::, code::\tuneRequest::, code::\midiClock::, code::\sysrt::, code::\tick::, code::\start::, code::\continue::, code::\stop::, code::\activeSense::, or code::\reset::.
METHOD:: argTemplate
Get this MIDIFunc's argTemplate.
returns:: A link::Classes/Integer:: or link::Classes/Function:: (or object which responds to the method link::Overviews/Methods#matchItem::) used to match the value of an incoming MIDI message. (e.g. velocity, control value, program number, etc.).
METHOD:: learn
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.
argument:: learnVal
A link::Classes/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.
EXAMPLES::
code::
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);
::