auri.ee / qmk_firmware
keyboard stuff
fork atom
qmk_firmware / docs / features / midi.md
at master 264 lines 16 kB view raw view rendered
1# MIDI 2 3## Usage 4 5First, enable MIDI by adding the following to your `rules.mk`: 6 7```make 8MIDI_ENABLE = yes 9``` 10 11There are two MIDI systems in QMK: basic and advanced. With basic MIDI you will only be able to send Note On and Note Off messages using the note keycodes, meaning that keycodes like `MI_OCTU` and `MI_OCTD` will not work. Advanced MIDI allows you to do things like octave shifts, channel changes, velocity changes, modulation, and more. 12 13### Caveats 14 15MIDI requires 2 USB endpoints and as such may not work on some hardware such as V-USB controllers. 16 17### Basic MIDI 18 19To enable basic MIDI, add the following to your `config.h`: 20 21```c 22#define MIDI_BASIC 23``` 24 25### Advanced MIDI 26 27To enable advanced MIDI, add the following to your `config.h`: 28 29```c 30#define MIDI_ADVANCED 31``` 32 33#### Sending Control Change (CC) Messages 34 35If you're aiming to emulate the features of something like a Launchpad or other MIDI controller you'll need to access the internal MIDI device directly. 36 37Because there are so many possible CC messages, not all of them are implemented as keycodes. Additionally, you might need to provide more than just two values that you would get from a keycode (pressed and released) - for example, the analog values from a fader or a potentiometer. So, you will need to implement [custom keycodes](../feature_macros) if you want to use them in your keymap directly using `process_record_user()`. 38 39 40For reference of all the possible control code numbers see [MIDI Specification](#midi-specification) 41 42#### Example code for using Generic On Off Switches as per MIDI Specification. 43```c 44#include QMK_KEYBOARD_H 45 46extern MidiDevice midi_device; 47 48// MIDI CC codes for generic on/off switches (80, 81, 82, 83) 49// Off: 0-63 50// On: 64-127 51 52#define MIDI_CC_OFF 0 53#define MIDI_CC_ON 127 54 55enum custom_keycodes { 56 MIDI_CC80 = SAFE_RANGE, 57}; 58 59bool process_record_user(uint16_t keycode, keyrecord_t *record) { 60 switch (keycode) { 61 case MIDI_CC80: 62 if (record->event.pressed) { 63 midi_send_cc(&midi_device, midi_config.channel, 80, MIDI_CC_ON); 64 } else { 65 midi_send_cc(&midi_device, midi_config.channel, 80, MIDI_CC_OFF); 66 } 67 return true; 68 } 69 return true; 70}; 71 72const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { 73 LAYOUT( 74 // ... 75 MIDI_CC80, 76 // ... 77 ) 78}; 79``` 80 81### Keycodes 82 83|Keycode |Aliases |Description | 84|-------------------------------|------------------|---------------------------------| 85|`QK_MIDI_ON` |`MI_ON` |Turn MIDI on | 86|`QK_MIDI_OFF` |`MI_OFF` |Turn MIDI off | 87|`QK_MIDI_TOGGLE` |`MI_TOGG` |Toggle MIDI enabled | 88|`QK_MIDI_NOTE_C_0` |`MI_C` |C octave 0 | 89|`QK_MIDI_NOTE_C_SHARP_0` |`MI_Cs`, `MI_Db` |C♯/D♭ octave 0 | 90|`QK_MIDI_NOTE_D_0` |`MI_D` |D octave 0 | 91|`QK_MIDI_NOTE_D_SHARP_0` |`MI_Ds`, `MI_Eb` |D♯/E♭ octave 0 | 92|`QK_MIDI_NOTE_E_0` |`MI_E` |E octave 0 | 93|`QK_MIDI_NOTE_F_0` |`MI_F` |F octave 0 | 94|`QK_MIDI_NOTE_F_SHARP_0` |`MI_Fs`, `MI_Gb` |F♯/G♭ octave 0 | 95|`QK_MIDI_NOTE_G_0` |`MI_G` |G octave 0 | 96|`QK_MIDI_NOTE_G_SHARP_0` |`MI_Gs`, `MI_Ab` |G♯/A♭ octave 0 | 97|`QK_MIDI_NOTE_A_0` |`MI_A` |A octave 0 | 98|`QK_MIDI_NOTE_A_SHARP_0` |`MI_As`, `MI_Bb` |A♯/B♭ octave 0 | 99|`QK_MIDI_NOTE_B_0` |`MI_B` |B octave 0 | 100|`QK_MIDI_NOTE_C_1` |`MI_C1` |C octave 1 | 101|`QK_MIDI_NOTE_C_SHARP_1` |`MI_Cs1`, `MI_Db1`|C♯/D♭ octave 1 | 102|`QK_MIDI_NOTE_D_1` |`MI_D1` |D octave 1 | 103|`QK_MIDI_NOTE_D_SHARP_1` |`MI_Ds1`, `MI_Eb1`|D♯/E♭ octave 1 | 104|`QK_MIDI_NOTE_E_1` |`MI_E1` |E octave 1 | 105|`QK_MIDI_NOTE_F_1` |`MI_F1` |F octave 1 | 106|`QK_MIDI_NOTE_F_SHARP_1` |`MI_Fs1`, `MI_Gb1`|F♯/G♭ octave 1 | 107|`QK_MIDI_NOTE_G_1` |`MI_G1` |G octave 1 | 108|`QK_MIDI_NOTE_G_SHARP_1` |`MI_Gs1`, `MI_Ab1`|G♯/A♭ octave 1 | 109|`QK_MIDI_NOTE_A_1` |`MI_A1` |A octave 1 | 110|`QK_MIDI_NOTE_A_SHARP_1` |`MI_As1`, `MI_Bb1`|A♯/B♭ octave 1 | 111|`QK_MIDI_NOTE_B_1` |`MI_B1` |B octave 1 | 112|`QK_MIDI_NOTE_C_2` |`MI_C2` |C octave 2 | 113|`QK_MIDI_NOTE_C_SHARP_2` |`MI_Cs2`, `MI_Db2`|C♯/D♭ octave 2 | 114|`QK_MIDI_NOTE_D_2` |`MI_D2` |D octave 2 | 115|`QK_MIDI_NOTE_D_SHARP_2` |`MI_Ds2`, `MI_Eb2`|D♯/E♭ octave 2 | 116|`QK_MIDI_NOTE_E_2` |`MI_E2` |E octave 2 | 117|`QK_MIDI_NOTE_F_2` |`MI_F2` |F octave 2 | 118|`QK_MIDI_NOTE_F_SHARP_2` |`MI_Fs2`, `MI_Gb2`|F♯/G♭ octave 2 | 119|`QK_MIDI_NOTE_G_2` |`MI_G2` |G octave 2 | 120|`QK_MIDI_NOTE_G_SHARP_2` |`MI_Gs2`, `MI_Ab2`|G♯/A♭ octave 2 | 121|`QK_MIDI_NOTE_A_2` |`MI_A2` |A octave 2 | 122|`QK_MIDI_NOTE_A_SHARP_2` |`MI_As2`, `MI_Bb2`|A♯/B♭ octave 2 | 123|`QK_MIDI_NOTE_B_2` |`MI_B2` |B octave 2 | 124|`QK_MIDI_NOTE_C_3` |`MI_C3` |C octave 3 | 125|`QK_MIDI_NOTE_C_SHARP_3` |`MI_Cs3`, `MI_Db3`|C♯/D♭ octave 3 | 126|`QK_MIDI_NOTE_D_3` |`MI_D3` |D octave 3 | 127|`QK_MIDI_NOTE_D_SHARP_3` |`MI_Ds3`, `MI_Eb3`|D♯/E♭ octave 3 | 128|`QK_MIDI_NOTE_E_3` |`MI_E3` |E octave 3 | 129|`QK_MIDI_NOTE_F_3` |`MI_F3` |F octave 3 | 130|`QK_MIDI_NOTE_F_SHARP_3` |`MI_Fs3`, `MI_Gb3`|F♯/G♭ octave 3 | 131|`QK_MIDI_NOTE_G_3` |`MI_G3` |G octave 3 | 132|`QK_MIDI_NOTE_G_SHARP_3` |`MI_Gs3`, `MI_Ab3`|G♯/A♭ octave 3 | 133|`QK_MIDI_NOTE_A_3` |`MI_A3` |A octave 3 | 134|`QK_MIDI_NOTE_A_SHARP_3` |`MI_As3`, `MI_Bb3`|A♯/B♭ octave 3 | 135|`QK_MIDI_NOTE_B_3` |`MI_B3` |B octave 3 | 136|`QK_MIDI_NOTE_C_4` |`MI_C4` |C octave 4 | 137|`QK_MIDI_NOTE_C_SHARP_4` |`MI_Cs4`, `MI_Db4`|C♯/D♭ octave 4 | 138|`QK_MIDI_NOTE_D_4` |`MI_D4` |D octave 4 | 139|`QK_MIDI_NOTE_D_SHARP_4` |`MI_Ds4`, `MI_Eb4`|D♯/E♭ octave 4 | 140|`QK_MIDI_NOTE_E_4` |`MI_E4` |E octave 4 | 141|`QK_MIDI_NOTE_F_4` |`MI_F4` |F octave 4 | 142|`QK_MIDI_NOTE_F_SHARP_4` |`MI_Fs4`, `MI_Gb4`|F♯/G♭ octave 4 | 143|`QK_MIDI_NOTE_G_4` |`MI_G4` |G octave 4 | 144|`QK_MIDI_NOTE_G_SHARP_4` |`MI_Gs4`, `MI_Ab4`|G♯/A♭ octave 4 | 145|`QK_MIDI_NOTE_A_4` |`MI_A4` |A octave 4 | 146|`QK_MIDI_NOTE_A_SHARP_4` |`MI_As4`, `MI_Bb4`|A♯/B♭ octave 4 | 147|`QK_MIDI_NOTE_B_4` |`MI_B4` |B octave 4 | 148|`QK_MIDI_NOTE_C_5` |`MI_C5` |C octave 5 | 149|`QK_MIDI_NOTE_C_SHARP_5` |`MI_Cs5`, `MI_Db5`|C♯/D♭ octave 5 | 150|`QK_MIDI_NOTE_D_5` |`MI_D5` |D octave 5 | 151|`QK_MIDI_NOTE_D_SHARP_5` |`MI_Ds5`, `MI_Eb5`|D♯/E♭ octave 5 | 152|`QK_MIDI_NOTE_E_5` |`MI_E5` |E octave 5 | 153|`QK_MIDI_NOTE_F_5` |`MI_F5` |F octave 5 | 154|`QK_MIDI_NOTE_F_SHARP_5` |`MI_Fs5`, `MI_Gb5`|F♯/G♭ octave 5 | 155|`QK_MIDI_NOTE_G_5` |`MI_G5` |G octave 5 | 156|`QK_MIDI_NOTE_G_SHARP_5` |`MI_Gs5`, `MI_Ab5`|G♯/A♭ octave 5 | 157|`QK_MIDI_NOTE_A_5` |`MI_A5` |A octave 5 | 158|`QK_MIDI_NOTE_A_SHARP_5` |`MI_As5`, `MI_Bb5`|A♯/B♭ octave 5 | 159|`QK_MIDI_NOTE_B_5` |`MI_B5` |B octave 5 | 160|`QK_MIDI_OCTAVE_N2` |`MI_OCN2` |Set octave to -2 | 161|`QK_MIDI_OCTAVE_N1` |`MI_OCN1` |Set octave to -1 | 162|`QK_MIDI_OCTAVE_0` |`MI_OC0` |Set octave to 0 | 163|`QK_MIDI_OCTAVE_1` |`MI_OC1` |Set octave to 1 | 164|`QK_MIDI_OCTAVE_2` |`MI_OC2` |Set octave to 2 | 165|`QK_MIDI_OCTAVE_3` |`MI_OC3` |Set octave to 3 | 166|`QK_MIDI_OCTAVE_4` |`MI_OC4` |Set octave to 4 | 167|`QK_MIDI_OCTAVE_5` |`MI_OC5` |Set octave to 5 | 168|`QK_MIDI_OCTAVE_6` |`MI_OC6` |Set octave to 6 | 169|`QK_MIDI_OCTAVE_7` |`MI_OC7` |Set octave to 7 | 170|`QK_MIDI_OCTAVE_DOWN` |`MI_OCTD` |Move down an octave | 171|`QK_MIDI_OCTAVE_UP` |`MI_OCTU` |Move up an octave | 172|`QK_MIDI_TRANSPOSE_N6` |`MI_TRN6` |Set transposition to -6 semitones| 173|`QK_MIDI_TRANSPOSE_N5` |`MI_TRN5` |Set transposition to -5 semitones| 174|`QK_MIDI_TRANSPOSE_N4` |`MI_TRN4` |Set transposition to -4 semitones| 175|`QK_MIDI_TRANSPOSE_N3` |`MI_TRN3` |Set transposition to -3 semitones| 176|`QK_MIDI_TRANSPOSE_N2` |`MI_TRN2` |Set transposition to -2 semitones| 177|`QK_MIDI_TRANSPOSE_N1` |`MI_TRN1` |Set transposition to -1 semitone | 178|`QK_MIDI_TRANSPOSE_0` |`MI_TR0` |No transposition | 179|`QK_MIDI_TRANSPOSE_1` |`MI_TR1` |Set transposition to +1 semitone | 180|`QK_MIDI_TRANSPOSE_2` |`MI_TR2` |Set transposition to +2 semitones| 181|`QK_MIDI_TRANSPOSE_3` |`MI_TR3` |Set transposition to +3 semitones| 182|`QK_MIDI_TRANSPOSE_4` |`MI_TR4` |Set transposition to +4 semitones| 183|`QK_MIDI_TRANSPOSE_5` |`MI_TR5` |Set transposition to +5 semitones| 184|`QK_MIDI_TRANSPOSE_6` |`MI_TR6` |Set transposition to +6 semitones| 185|`QK_MIDI_TRANSPOSE_DOWN` |`MI_TRSD` |Decrease transposition | 186|`QK_MIDI_TRANSPOSE_UP` |`MI_TRSU` |Increase transposition | 187|`QK_MIDI_VELOCITY_0` |`MI_VL0` |Set velocity to 0 | 188|`QK_MIDI_VELOCITY_1` |`MI_VL1` |Set velocity to 12 | 189|`QK_MIDI_VELOCITY_2` |`MI_VL2` |Set velocity to 25 | 190|`QK_MIDI_VELOCITY_3` |`MI_VL3` |Set velocity to 38 | 191|`QK_MIDI_VELOCITY_4` |`MI_VL4` |Set velocity to 51 | 192|`QK_MIDI_VELOCITY_5` |`MI_VL5` |Set velocity to 64 | 193|`QK_MIDI_VELOCITY_6` |`MI_VL6` |Set velocity to 76 | 194|`QK_MIDI_VELOCITY_7` |`MI_VL7` |Set velocity to 89 | 195|`QK_MIDI_VELOCITY_8` |`MI_VL8` |Set velocity to 102 | 196|`QK_MIDI_VELOCITY_9` |`MI_VL9` |Set velocity to 114 | 197|`QK_MIDI_VELOCITY_10` |`MI_VL10` |Set velocity to 127 | 198|`QK_MIDI_VELOCITY_DOWN` |`MI_VELD` |Decrease velocity | 199|`QK_MIDI_VELOCITY_UP` |`MI_VELU` |Increase velocity | 200|`QK_MIDI_CHANNEL_1` |`MI_CH1` |Set channel to 1 | 201|`QK_MIDI_CHANNEL_2` |`MI_CH2` |Set channel to 2 | 202|`QK_MIDI_CHANNEL_3` |`MI_CH3` |Set channel to 3 | 203|`QK_MIDI_CHANNEL_4` |`MI_CH4` |Set channel to 4 | 204|`QK_MIDI_CHANNEL_5` |`MI_CH5` |Set channel to 5 | 205|`QK_MIDI_CHANNEL_6` |`MI_CH6` |Set channel to 6 | 206|`QK_MIDI_CHANNEL_7` |`MI_CH7` |Set channel to 7 | 207|`QK_MIDI_CHANNEL_8` |`MI_CH8` |Set channel to 8 | 208|`QK_MIDI_CHANNEL_9` |`MI_CH9` |Set channel to 9 | 209|`QK_MIDI_CHANNEL_10` |`MI_CH10` |Set channel to 10 | 210|`QK_MIDI_CHANNEL_11` |`MI_CH11` |Set channel to 11 | 211|`QK_MIDI_CHANNEL_12` |`MI_CH12` |Set channel to 12 | 212|`QK_MIDI_CHANNEL_13` |`MI_CH13` |Set channel to 13 | 213|`QK_MIDI_CHANNEL_14` |`MI_CH14` |Set channel to 14 | 214|`QK_MIDI_CHANNEL_15` |`MI_CH15` |Set channel to 15 | 215|`QK_MIDI_CHANNEL_16` |`MI_CH16` |Set channel to 16 | 216|`QK_MIDI_CHANNEL_DOWN` |`MI_CHND` |Decrease channel | 217|`QK_MIDI_CHANNEL_UP` |`MI_CHNU` |Increase channel | 218|`QK_MIDI_ALL_NOTES_OFF` |`MI_AOFF` |Stop all notes | 219|`QK_MIDI_SUSTAIN` |`MI_SUST` |Sustain | 220|`QK_MIDI_PORTAMENTO` |`MI_PORT` |Portmento | 221|`QK_MIDI_SOSTENUTO` |`MI_SOST` |Sostenuto | 222|`QK_MIDI_SOFT` |`MI_SOFT` |Soft Pedal | 223|`QK_MIDI_LEGATO` |`MI_LEG` |Legato | 224|`QK_MIDI_MODULATION` |`MI_MOD` |Modulation | 225|`QK_MIDI_MODULATION_SPEED_DOWN`|`MI_MODD` |Decrease modulation speed | 226|`QK_MIDI_MODULATION_SPEED_UP` |`MI_MODU` |Increase modulation speed | 227|`QK_MIDI_PITCH_BEND_DOWN` |`MI_BNDD` |Bend pitch down | 228|`QK_MIDI_PITCH_BEND_UP` |`MI_BNDU` |Bend pitch up | 229 230### Configuration 231 232Certain values are stored in the `midi_config` struct. This configuration is not persisted to EEPROM. By default, these values are: 233 234|Configuration |Value|Comments | 235|-------------------|-----|-----------------------| 236|Octave |`4` |Corresponds to `MI_OC2`| 237|Transposition |`0` | | 238|Velocity |`127`| | 239|Channel |`0` | | 240|Modulation Interval|`8` | | 241 242For the above, the `MI_C` keycode will produce a C3 (note number 48), and so on. 243 244### References 245#### MIDI Specification 246 247 * [MIDI.org](https://www.midi.org/specifications-old/item/table-1-summary-of-midi-message) 248 * [CMU MIDI Programmer's Reference](https://www.cs.cmu.edu/~music/cmsip/readings/MIDI%20tutorial%20for%20programmers.html) 249#### QMK C Files 250 251 * `quantum/process_keycode/process_midi.c` 252 * `quantum/quantum_keycodes.h` 253 * `quantum/midi/midi.h` 254 * `quantum/midi/midi.c` 255 * `quantum/midi/qmk_midi.c` 256 * `quantum/midi/midi_device.h` 257 258<!-- 259#### QMK Internals (Autogenerated) 260 261 * [Internals/MIDI Device Setup Process](internals/midi_device_setup_process) 262 * [Internals/MIDI Device](internals/midi_device) 263 * [Internals/MIDI Util](internals/midi_util) 264-->