midi_consts/lib.rs
1//! Constants for dealing with midi events.
2//! Currently, only channel events are supported.
3
4/// Constants for channel events
5///
6/// Channel events consist of two or three bytes:
7/// * byte 1: event type (first four bits) and midi channel (last four bits)
8/// * byte 2: parameter 1
9/// * byte 3: parameter 2 (used for most, but not all event types)
10pub mod channel_event {
11 /// The first byte of a channel event contains both the event type
12 /// and the midi channel in one byte.
13 /// Use this bit mask to get the event type.
14 ///
15 /// ## Example
16 /// ```
17 /// use midi_consts::channel_event::EVENT_TYPE_MASK;
18 /// # fn get_byte() -> u8 { 0x94}
19 /// let byte: u8 = get_byte(); // Suppose we got this byte somewhere.
20 /// let event_type = byte & EVENT_TYPE_MASK; // (binary AND)
21 /// match event_type {
22 /// EVENT_TYPE_NOTE_OFF => { /* ... */ },
23 /// EVENT_TYPE_NOTE_ON => { /* ... */ },
24 /// // ...
25 /// _ => { /* ...*/ }
26 /// }
27 /// ```
28 pub const EVENT_TYPE_MASK: u8 = 0b1111_0000;
29
30 /// The first byte of a channel event contains both the event type
31 /// and the midi channel in one byte.
32 /// Use this bit mask to get the midi channel.
33 ///
34 /// ## Example
35 /// ```
36 /// use midi_consts::channel_event::MIDI_CHANNEL_MASK;
37 /// # fn get_byte() -> u8 { 0x94}
38 /// let byte: u8 = get_byte(); // Suppose we got this byte somewhere.
39 /// let midi_channel: u8 = byte & MIDI_CHANNEL_MASK; // (binary AND)
40 /// ```
41 pub const MIDI_CHANNEL_MASK: u8 = 0b0000_1111;
42
43 /// Event type of note off event.
44 ///
45 /// A channel event of this type is as follows:
46 /// * byte 1: `NOTE_OFF | channel`
47 /// * byte 2: note number (0-127)
48 /// * byte 3: velocity (how hard the key was released)
49 ///
50 /// # Remark
51 /// A note off event is often represented as a note on event
52 /// with velocity `0`.
53 pub const NOTE_OFF: u8 = 0x80;
54
55 /// Event type of note on event.
56 ///
57 /// A channel event of this type is as follows:
58 /// * byte one: `NOTE_ON | channel`
59 /// * byte two: note number (0-127)
60 /// * byte three: velocity (how hard the key was pressed)
61 ///
62 /// # Remark
63 /// A note off event is often represented as a note on event
64 /// with velocity `0`.
65 pub const NOTE_ON: u8 = 0x90;
66
67 /// Event type for polyphonic key pressure ("aftertouch").
68 ///
69 /// A channel event of this type is as follows:
70 /// * byte one: `POLYPHONIC_KEY_PRESSURE | channel`, where `channel` is the channel (0-16)
71 /// * byte two: note number (0-127)
72 /// * byte three: aftertouch value
73 pub const POLYPHONIC_KEY_PRESSURE: u8 = 0xA0;
74
75 /// Event type of a controller event.
76 ///
77 /// A channel event of this type is as follows:
78 /// * byte one: `CONTROL_CHANGE | channel`, where `channel` is the channel (0-16)
79 /// * byte two: controller type (0-127)
80 /// * byte three: new controller value
81 ///
82 /// See the [`control_change`] module for more details.
83 ///
84 /// [`control_change`]: ./control_change/index.html
85 pub const CONTROL_CHANGE: u8 = 0xB0;
86
87 /// Event type of a program change.
88 ///
89 /// A channel event of this type has only two bytes and is as follows:
90 /// * byte one: `PROGRAM_CHANGE | channel`, where `channel` is the channel (0-16)
91 /// * byte two: program number (0-127)
92 pub const PROGRAM_CHANGE: u8 = 0xC0;
93
94 /// Event type of channel pressure ("channel aftertouch").
95 ///
96 /// Events of this type are assumed to effect all currently
97 /// playing notes for the specified channel.
98 /// A channel event of this type has only two bytes and is as follows:
99 /// * byte one: `CHANNEL_KEY_PRESSURE | channel`, where `channel` is the channel (0-16)
100 /// * byte two: pressure amount (0-127)
101 pub const CHANNEL_KEY_PRESSURE: u8 = 0xD0;
102
103 /// Event type of a pitch bend event.
104 ///
105 /// A channel event of this type is as follows:
106 /// * byte one: `PITCH_BEND_CHANGE | channel`, where `channel` is the channel (0-16)
107 /// * byte two: least significant byte of the pitch bend amount (0-127)
108 /// * byte three: most significant byte of the pitch bend amount
109 ///
110 /// By combining the two bytes that make up the pitch bend amount, you
111 /// can get a `u16` value that describes the pitch bend amount.
112 /// Value 8192 means "no pitch change", lower values mean decrease in pitch
113 /// and higher values mean increase in pitch.
114 pub const PITCH_BEND_CHANGE: u8 = 0xE0;
115
116 /// Constants to represent controller change types.
117 ///
118 /// A control change channel event is as follows:
119 /// * byte one: `CONTROL_CHANGE | channel`, where `channel` is the channel (0-16)
120 /// * byte two: controller type (0-127). This module contains constants for these types.
121 /// * byte three: new controller value
122 ///
123 /// # Remark
124 /// Some control change types come in pairs: one with the most significant byte (MSB)
125 /// and one with the least significant byte (LSB).
126 pub mod control_change {
127 const LSB_MASK: u8 = 0x20;
128
129 /// Bank select: most significant byte.
130 pub const BANK_SELECT_MSB: u8 = 0x00;
131
132 /// Bank select: least significant byte.
133 pub const BANK_SELECT_LSB: u8 = BANK_SELECT_MSB | LSB_MASK;
134
135 /// Modulation: most significant byte.
136 pub const MODULATION_MSB: u8 = 0x01;
137
138 /// Modulation: least significant byte.
139 pub const MODULATION_LSB: u8 = MODULATION_MSB | LSB_MASK;
140
141 /// Breath controller: most significant byte.
142 pub const BREATH_CONTROLLER_MSB: u8 = 0x02;
143
144 /// Breach controller: least significant byte.
145 pub const BREATH_CONTROLLER_LSB: u8 = BREATH_CONTROLLER_MSB | LSB_MASK;
146
147 /// Foot controller: most significant byte.
148 pub const FOOT_CONTROLLER_MSB: u8 = 0x04;
149
150 /// Foot controller: least significant byte.
151 pub const FOOT_CONTROLLER_LSB: u8 = FOOT_CONTROLLER_MSB | LSB_MASK;
152
153 /// Portamento: most significant byte.
154 pub const PORTAMENTO_TIME_MSB: u8 = 0x05;
155
156 /// Portamento: least significant byte.
157 pub const PORTAMENTO_TIME_LSB: u8 = PORTAMENTO_TIME_MSB | LSB_MASK;
158
159 /// Data entry: most significant byte.
160 pub const DATA_ENTRY_MSB: u8 = 0x06;
161
162 /// Data entry: least significant byte.
163 pub const DATA_ENTRY_LSB: u8 = DATA_ENTRY_MSB | LSB_MASK;
164
165 /// Main volume: most significant byte.
166 pub const MAIN_VOLUME_MSB: u8 = 0x07;
167
168 /// Main volume: least significant byte.
169 pub const MAIN_VOLUME_LSB: u8 = MAIN_VOLUME_MSB | LSB_MASK;
170
171 /// Balance: most significant byte.
172 pub const BALANCE_MSB: u8 = 0x08;
173
174 /// Balance: least significant byte.
175 pub const BALANCE_LSB: u8 = BALANCE_MSB | LSB_MASK;
176
177 /// Pan: most significant byte.
178 pub const PAN_MSB: u8 = 0x0A;
179
180 /// Pan: least significant byte.
181 pub const PAN_LSB: u8 = PAN_MSB | LSB_MASK;
182
183 /// Expression controller: most significant byte.
184 pub const EXPRESSION_CONTROLLER_MSB: u8 = 0x0B;
185
186 /// Expression controller: least significant byte.
187 pub const EXPRESSION_CONTROLLER_LSB: u8 = EXPRESSION_CONTROLLER_MSB | LSB_MASK;
188
189 /// Effect control 1: most significant byte.
190 pub const EFFECT_CONTROL_1_MSB: u8 = 0x0C;
191
192 /// Effect control 1: least significant byte.
193 pub const EFFECT_CONTROL_1_LSB: u8 = EFFECT_CONTROL_1_MSB | LSB_MASK;
194
195 /// Effect control 2: most significant byte.
196 pub const EFFECT_CONTROL_2_MSB: u8 = 0x0D;
197
198 /// Effect control 2: least significant byte.
199 pub const EFFECT_CONTROL_2_LSB: u8 = EFFECT_CONTROL_2_MSB | LSB_MASK;
200
201 /// General purpose controller 1: most significant byte.
202 pub const GENERAL_PURPOSE_CONTROLLER_1_MSB: u8 = 0x10;
203
204 /// General purpose controller 1: least significant byte.
205 pub const GENERAL_PURPOSE_CONTROLLER_1_LSB: u8 =
206 GENERAL_PURPOSE_CONTROLLER_1_MSB | LSB_MASK;
207
208 /// General purpose controller 2: most significant byte.
209 pub const GENERAL_PURPOSE_CONTROLLER_2_MSB: u8 = 0x11;
210
211 /// General purpose controller 2: least significant byte.
212 pub const GENERAL_PURPOSE_CONTROLLER_2_LSB: u8 =
213 GENERAL_PURPOSE_CONTROLLER_2_MSB | LSB_MASK;
214
215 /// General purpose controller 3: most significant byte.
216 pub const GENERAL_PURPOSE_CONTROLLER_3_MSB: u8 = 0x12;
217
218 /// General purpose controller 3: least significant byte.
219 pub const GENERAL_PURPOSE_CONTROLLER_3_LSB: u8 =
220 GENERAL_PURPOSE_CONTROLLER_3_MSB | LSB_MASK;
221
222 /// General purpose controller 4: most significant byte.
223 pub const GENERAL_PURPOSE_CONTROLLER_4_MSB: u8 = 0x13;
224
225 /// General purpose controller 4: least significant byte.
226 pub const GENERAL_PURPOSE_CONTROLLER_4_LSB: u8 =
227 GENERAL_PURPOSE_CONTROLLER_4_MSB | LSB_MASK;
228
229 /// Damper pedal.
230 pub const DAMPER_PEDAL: u8 = 0x40;
231
232 /// Portamento.
233 pub const PORTAMENTO: u8 = 0x41;
234
235 /// Sustenuto.
236 pub const SUSTENUTO: u8 = 0x42;
237
238 /// Soft pedal.
239 pub const SOFT_PEDAL: u8 = 0x43;
240
241 /// Legato footswitch.
242 pub const LEGATO_FOOTSWITCH: u8 = 0x44;
243
244 /// Hold 2.
245 pub const HOLD_2: u8 = 0x45;
246
247 /// Sound controller 1. Default: Timber variation
248 pub const SOUND_CONTROLLER_1: u8 = 0x46;
249
250 /// Sound controller 2. Default: Timber/harmonic content
251 pub const SOUND_CONTROLLER_2: u8 = 0x47;
252
253 /// Sound controller 3. Default: Release time
254 pub const SOUND_CONTROLLER_3: u8 = 0x48;
255
256 /// Sound controller 4. Default: Attack time
257 pub const SOUND_CONTROLLER_4: u8 = 0x49;
258
259 /// Sound controller 5.
260 pub const SOUND_CONTROLLER_5: u8 = 0x4A;
261
262 /// Sound controller 6.
263 pub const SOUND_CONTROLLER_6: u8 = 0x4B;
264
265 /// Sound controller 7.
266 pub const SOUND_CONTROLLER_7: u8 = 0x4C;
267
268 /// Sound controller 8.
269 pub const SOUND_CONTROLLER_8: u8 = 0x4D;
270
271 /// Sound controller 9.
272 pub const SOUND_CONTROLLER_9: u8 = 0x4E;
273
274 /// Sound controller 10.
275 pub const SOUND_CONTROLLER_10: u8 = 0x4F;
276
277 /// General purpose controller 5: most significant byte.
278 ///
279 /// # Remark
280 /// As far as I know, this has no LSB (least significant byte) variant.
281 pub const GENERAL_PURPOSE_CONTROLLER_5_MSB: u8 = 0x50;
282
283 /// General purpose controller 6: most significant byte.
284 ///
285 /// # Remark
286 /// As far as I know, this has no LSB (least significant byte) variant.
287 pub const GENERAL_PURPOSE_CONTROLLER_6_MSB: u8 = 0x51;
288
289 /// General purpose controller 7: most significant byte.
290 ///
291 /// # Remark
292 /// As far as I know, this has no LSB (least significant byte) variant.
293 pub const GENERAL_PURPOSE_CONTROLLER_7_MSB: u8 = 0x52;
294
295 /// General purpose controller 8: most significant byte.
296 ///
297 /// # Remark
298 /// As far as I know, this has no LSB (least significant byte) variant.
299 pub const GENERAL_PURPOSE_CONTROLLER_8_MSB: u8 = 0x53;
300
301 /// Portamento.
302 pub const PORTAMENTO_CONTROL: u8 = 0x54;
303
304 /// Effects depth 1. Formerly "External Effects Depth"
305 pub const EFFECTS_1_DEPTH: u8 = 0x5B;
306
307 /// Effects depth 2. Formerly "Tremolo Depth"
308 pub const EFFECTS_2_DEPTH: u8 = 0x5C;
309
310 /// Effects depth 3. Formerly "Chorus Depth"
311 pub const EFFECTS_3_DEPTH: u8 = 0x5D;
312
313 /// Effects depth 4. Formerly "Celeste Detune"
314 pub const EFFECTS_4_DEPTH: u8 = 0x5E;
315
316 /// Effects depth 5. Formerly "Phaser Depth"
317 pub const EFFECTS_5_DEPTH: u8 = 0x5F;
318
319 /// Non-registered parameter number: least significant byte.
320 pub const NON_REGISTERED_PARAMETER_NUMBER_LSB: u8 = 0x62;
321
322 /// Non-registered parameter number: most significant byte.
323 pub const NON_REGISTERED_PARAMETER_NUMBER_MSB: u8 = 0x63;
324
325 /// Registered parameter number: least significant byte.
326 pub const REGISTERED_PARAMETER_NUMBER_LSB: u8 = 0x64;
327
328 /// Registered parameter number: most significant byte.
329 pub const REGISTERED_PARAMETER_NUMBER_MSB: u8 = 0x65;
330
331 /// Mode message: all sound off.
332 ///
333 /// For this event, the data byte (the third byte of the event) should be `0`
334 pub const ALL_SOUND_OFF: u8 = 0x78;
335
336 /// Mode message: reset all controllers.
337 ///
338 /// For this event, the data byte (the third byte of the event) should be `0`
339 pub const RESET_ALL_CONTROLLERS: u8 = 0x79;
340
341 /// Mode message: local control.
342 ///
343 /// When local control is on (default), the device responds to its local controls.
344 /// When local control is off, it only responds to data recieved over MIDI.
345 ///
346 /// See the module [`local_control`] for possible values of the data byte
347 /// (the third byte of the event).
348 ///
349 /// [`local_control`]: ./local_control/index.html
350 pub const LOCAL_CONTROL: u8 = 0x7A;
351
352 /// Constants for the data byte (3rd byte) of a local control control change event.
353 pub mod local_control {
354 /// Local control off: the device only responds to data recieved over MIDI.
355 pub const LOCAL_CONTROL_OFF: u8 = 0;
356 /// Local control on: the device also responds to local events (keys played, ...).
357 pub const LOCAL_CONTROL_ON: u8 = 127;
358 }
359
360 /// Mode message: all notes off.
361 ///
362 /// For this event, the data byte (the third byte of the event) should be `0`.
363 pub const ALL_NOTES_OFF: u8 = 0x7B;
364
365 /// Mode message: omni mode off.
366 ///
367 /// For this event, the data byte (the third byte of the event) should be `0`.
368 /// # Remark
369 /// This message also causes all notes off.
370 pub const OMNI_MODE_OFF: u8 = 0x7C;
371
372 /// Mode message: omni mode on.
373 ///
374 /// For this event, the data byte (the third byte of the event) should be `0`.
375 /// # Remark
376 /// This message also causes all notes off.
377 pub const OMNI_MODE_ON: u8 = 0x7D;
378
379 /// Mode message: mono mode on
380 ///
381 /// For this event, the data byte (the third byte of the event)
382 /// indicates the number of channels (omni off) or `0` (omni on).
383 /// # Remark
384 /// This message also causes all notes off.
385 pub const MONO_MODE_ON: u8 = 0x7E;
386
387 /// Poly mode on
388 ///
389 /// # Remark
390 /// This message also causes all notes off.
391 pub const POLY_MODE_ON: u8 = 0x7F;
392 }
393}