aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--docs/_summary.md1
-rw-r--r--docs/feature_audio.md114
-rw-r--r--docs/feature_midi.md260
3 files changed, 262 insertions, 113 deletions
diff --git a/docs/_summary.md b/docs/_summary.md
index 38937771f..9798ef512 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -108,6 +108,7 @@
108 * [Haptic Feedback](feature_haptic_feedback.md) 108 * [Haptic Feedback](feature_haptic_feedback.md)
109 * [Joystick](feature_joystick.md) 109 * [Joystick](feature_joystick.md)
110 * [LED Indicators](feature_led_indicators.md) 110 * [LED Indicators](feature_led_indicators.md)
111 * [MIDI](feature_midi.md)
111 * [Proton C Conversion](proton_c_conversion.md) 112 * [Proton C Conversion](proton_c_conversion.md)
112 * [PS/2 Mouse](feature_ps2_mouse.md) 113 * [PS/2 Mouse](feature_ps2_mouse.md)
113 * [Split Keyboard](feature_split_keyboard.md) 114 * [Split Keyboard](feature_split_keyboard.md)
diff --git a/docs/feature_audio.md b/docs/feature_audio.md
index 2c440c951..b7b572974 100644
--- a/docs/feature_audio.md
+++ b/docs/feature_audio.md
@@ -301,8 +301,7 @@ You can configure the default, min and max frequencies, the stepping and built i
301 301
302## MIDI Functionality 302## MIDI Functionality
303 303
304This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile. 304See [MIDI](feature_midi.md)
305
306 305
307## Audio Keycodes 306## Audio Keycodes
308 307
@@ -319,114 +318,3 @@ This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to s
319|`MU_OFF` | |Turns off Music Mode | 318|`MU_OFF` | |Turns off Music Mode |
320|`MU_TOG` | |Toggles Music Mode | 319|`MU_TOG` | |Toggles Music Mode |
321|`MU_MOD` | |Cycles through the music modes | 320|`MU_MOD` | |Cycles through the music modes |
322
323<!-- FIXME: this formatting needs work
324
325## Audio
326
327```c
328#ifdef AUDIO_ENABLE
329 AU_ON,
330 AU_OFF,
331 AU_TOG,
332
333 // Music mode on/off/toggle
334 MU_ON,
335 MU_OFF,
336 MU_TOG,
337
338 // Music voice iterate
339 MUV_IN,
340 MUV_DE,
341#endif
342```
343
344### Midi
345
346#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
347 MI_ON, // send midi notes when music mode is enabled
348 MI_OFF, // don't send midi notes when music mode is enabled
349#endif
350
351MIDI_TONE_MIN,
352MIDI_TONE_MAX
353
354MI_C = MIDI_TONE_MIN,
355MI_Cs,
356MI_Db = MI_Cs,
357MI_D,
358MI_Ds,
359MI_Eb = MI_Ds,
360MI_E,
361MI_F,
362MI_Fs,
363MI_Gb = MI_Fs,
364MI_G,
365MI_Gs,
366MI_Ab = MI_Gs,
367MI_A,
368MI_As,
369MI_Bb = MI_As,
370MI_B,
371
372MIDI_TONE_KEYCODE_OCTAVES > 1
373
374where x = 1-5:
375MI_C_x,
376MI_Cs_x,
377MI_Db_x = MI_Cs_x,
378MI_D_x,
379MI_Ds_x,
380MI_Eb_x = MI_Ds_x,
381MI_E_x,
382MI_F_x,
383MI_Fs_x,
384MI_Gb_x = MI_Fs_x,
385MI_G_x,
386MI_Gs_x,
387MI_Ab_x = MI_Gs_x,
388MI_A_x,
389MI_As_x,
390MI_Bb_x = MI_As_x,
391MI_B_x,
392
393MI_OCT_Nx 1-2
394MI_OCT_x 0-7
395MIDI_OCTAVE_MIN = MI_OCT_N2,
396MIDI_OCTAVE_MAX = MI_OCT_7,
397MI_OCTD, // octave down
398MI_OCTU, // octave up
399
400MI_TRNS_Nx 1-6
401MI_TRNS_x 0-6
402MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
403MIDI_TRANSPOSE_MAX = MI_TRNS_6,
404MI_TRNSD, // transpose down
405MI_TRNSU, // transpose up
406
407MI_VEL_x 1-10
408MIDI_VELOCITY_MIN = MI_VEL_1,
409MIDI_VELOCITY_MAX = MI_VEL_9,
410MI_VELD, // velocity down
411MI_VELU, // velocity up
412
413MI_CHx 1-16
414MIDI_CHANNEL_MIN = MI_CH1
415MIDI_CHANNEL_MAX = MI_CH16,
416MI_CHD, // previous channel
417MI_CHU, // next channel
418
419MI_ALLOFF, // all notes off
420
421MI_SUS, // sustain
422MI_PORT, // portamento
423MI_SOST, // sostenuto
424MI_SOFT, // soft pedal
425MI_LEG, // legato
426
427MI_MOD, // modulation
428MI_MODSD, // decrease modulation speed
429MI_MODSU, // increase modulation speed
430#endif // MIDI_ADVANCED
431
432-->
diff --git a/docs/feature_midi.md b/docs/feature_midi.md
new file mode 100644
index 000000000..ab29d89db
--- /dev/null
+++ b/docs/feature_midi.md
@@ -0,0 +1,260 @@
1# MIDI
2
3## Usage
4
5First, enable MIDI by adding the following to your `rules.mk`:
6
7```makefile
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### Basic MIDI
14
15To enable basic MIDI, add the following to your `config.h`:
16
17```c
18#define MIDI_BASIC
19```
20
21### Advanced MIDI
22
23To enable advanced MIDI, add the following to your `config.h`:
24
25```c
26#define MIDI_ADVANCED
27```
28
29#### Sending Control Change (CC) Messages
30
31If 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.
32
33Because 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.md) if you want to use them in your keymap directly using `process_record_user()`.
34
35
36For reference of all the possible control code numbers see [MIDI Specification](#midi-specification)
37
38#### Example code for using Generic On Off Switches as per MIDI Specification.
39```c
40#include QMK_KEYBOARD_H
41
42extern MidiDevice midi_device;
43
44// MIDI CC codes for generic on/off switches (80, 81, 82, 83)
45// Off: 0-63
46// On: 64-127
47
48#define MIDI_CC_OFF 0
49#define MIDI_CC_ON 127
50
51enum custom_keycodes {
52 MIDI_CC80 = SAFE_RANGE,
53};
54
55bool process_record_user(uint16_t keycode, keyrecord_t *record) {
56 switch (keycode) {
57 case MIDI_CC80:
58 if (record->event.pressed) {
59 midi_send_cc(&midi_device, midi_config.channel, 80, ON);
60 } else {
61 midi_send_cc(&midi_device, midi_config.channel, 80, OFF);
62 }
63 return true;
64 }
65 return true;
66};
67
68const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
69 LAYOUT(
70 // ...
71 MIDI_CC80,
72 // ...
73 )
74};
75```
76
77### Keycodes
78
79|Keycode |Aliases |Description |
80|------------|---------|---------------------------------|
81|`MI_ON` | |Turn MIDI on |
82|`MI_OFF` | |Turn MIDI off |
83|`MI_TOG` | |Toggle MIDI enabled |
84|`MI_C` | |C octave 0 |
85|`MI_Cs` |`MI_Db` |C♯/D♭ octave 0 |
86|`MI_D` | |D octave 0 |
87|`MI_Ds` |`MI_Eb` |D♯/E♭ octave 0 |
88|`MI_E` | |E octave 0 |
89|`MI_F` | |F octave 0 |
90|`MI_Fs` |`MI_Gb` |F♯/G♭ octave 0 |
91|`MI_G` | |G octave 0 |
92|`MI_Gs` |`MI_Gs` |G♯/A♭ octave 0 |
93|`MI_A` | |A octave 0 |
94|`MI_As` |`MI_Bb` |A♯/B♭ octave 0 |
95|`MI_B` | |B octave 0 |
96|`MI_C_1` | |C octave 1 |
97|`MI_Cs_1` |`MI_Db_1`|C♯/D♭ octave 1 |
98|`MI_D_1` | |D octave 1 |
99|`MI_Ds_1` |`MI_Eb_1`|D♯/E♭ octave 1 |
100|`MI_E_1` | |E octave 1 |
101|`MI_F_1` | |F octave 1 |
102|`MI_Fs_1` |`MI_Gb_1`|F♯/G♭ octave 1 |
103|`MI_G_1` | |G octave 1 |
104|`MI_Gs_1` |`MI_Ab_1`|G♯/A♭ octave 1 |
105|`MI_A_1` | |A octave 1 |
106|`MI_As_1` |`MI_Bb_1`|A♯/B♭ octave 1 |
107|`MI_B_1` | |B octave 1 |
108|`MI_C_2` | |C octave 2 |
109|`MI_Cs_2` |`MI_Db_2`|C♯/D♭ octave 2 |
110|`MI_D_2` | |D octave 2 |
111|`MI_Ds_2` |`MI_Eb_2`|D♯/E♭ octave 2 |
112|`MI_E_2` | |E octave 2 |
113|`MI_F_2` | |F octave 2 |
114|`MI_Fs_2` |`MI_Gb_2`|F♯/G♭ octave 2 |
115|`MI_G_2` | |G octave 2 |
116|`MI_Gs_2` |`MI_Ab_2`|G♯/A♭ octave 2 |
117|`MI_A_2` | |A octave 2 |
118|`MI_As_2` |`MI_Bb_2`|A♯/B♭ octave 2 |
119|`MI_B_2` | |B octave 2 |
120|`MI_C_3` | |C octave 3 |
121|`MI_Cs_3` |`MI_Db_3`|C♯/D♭ octave 3 |
122|`MI_D_3` | |D octave 3 |
123|`MI_Ds_3` |`MI_Eb_3`|D♯/E♭ octave 3 |
124|`MI_E_3` | |E octave 3 |
125|`MI_F_3` | |F octave 3 |
126|`MI_Fs_3` |`MI_Gb_3`|F♯/G♭ octave 3 |
127|`MI_G_3` | |G octave 3 |
128|`MI_Gs_3` |`MI_Ab_3`|G♯/A♭ octave 3 |
129|`MI_A_3` | |A octave 3 |
130|`MI_As_3` |`MI_Bb_3`|A♯/B♭ octave 3 |
131|`MI_B_3` | |B octave 3 |
132|`MI_C_4` | |C octave 4 |
133|`MI_Cs_4` |`MI_Db_4`|C♯/D♭ octave 4 |
134|`MI_D_4` | |D octave 4 |
135|`MI_Ds_4` |`MI_Eb_4`|D♯/E♭ octave 4 |
136|`MI_E_4` | |E octave 4 |
137|`MI_F_4` | |F octave 4 |
138|`MI_Fs_4` |`MI_Gb_4`|F♯/G♭ octave 4 |
139|`MI_G_4` | |G octave 4 |
140|`MI_Gs_4` |`MI_Ab_4`|G♯/A♭ octave 4 |
141|`MI_A_4` | |A octave 4 |
142|`MI_As_4` |`MI_Bb_4`|A♯/B♭ octave 4 |
143|`MI_B_4` | |B octave 4 |
144|`MI_C_5` | |C octave 5 |
145|`MI_Cs_5` |`MI_Db_5`|C♯/D♭ octave 5 |
146|`MI_D_5` | |D octave 5 |
147|`MI_Ds_5` |`MI_Eb_5`|D♯/E♭ octave 5 |
148|`MI_E_5` | |E octave 5 |
149|`MI_F_5` | |F octave 5 |
150|`MI_Fs_5` |`MI_Gb_5`|F♯/G♭ octave 5 |
151|`MI_G_5` | |G octave 5 |
152|`MI_Gs_5` |`MI_Ab_5`|G♯/A♭ octave 5 |
153|`MI_A_5` | |A octave 5 |
154|`MI_As_5` |`MI_Bb_5`|A♯/B♭ octave 5 |
155|`MI_B_5` | |B octave 5 |
156|`MI_OCT_N2` | |Set octave to -2 |
157|`MI_OCT_N1` | |Set octave to -1 |
158|`MI_OCT_0` | |Set octave to 0 |
159|`MI_OCT_1` | |Set octave to 1 |
160|`MI_OCT_2` | |Set octave to 2 |
161|`MI_OCT_3` | |Set octave to 3 |
162|`MI_OCT_4` | |Set octave to 4 |
163|`MI_OCT_5` | |Set octave to 5 |
164|`MI_OCT_6` | |Set octave to 6 |
165|`MI_OCT_7` | |Set octave to 7 |
166|`MI_OCTD` | |Move down an octave |
167|`MI_OCTU` | |Move up an octave |
168|`MI_TRNS_N6`| |Set transposition to -6 semitones|
169|`MI_TRNS_N5`| |Set transposition to -5 semitones|
170|`MI_TRNS_N4`| |Set transposition to -4 semitones|
171|`MI_TRNS_N3`| |Set transposition to -3 semitones|
172|`MI_TRNS_N2`| |Set transposition to -2 semitones|
173|`MI_TRNS_N1`| |Set transposition to -1 semitone |
174|`MI_TRNS_0` | |No transposition |
175|`MI_TRNS_1` | |Set transposition to +1 semitone |
176|`MI_TRNS_2` | |Set transposition to +2 semitones|
177|`MI_TRNS_3` | |Set transposition to +3 semitones|
178|`MI_TRNS_4` | |Set transposition to +4 semitones|
179|`MI_TRNS_5` | |Set transposition to +5 semitones|
180|`MI_TRNS_6` | |Set transposition to +6 semitones|
181|`MI_TRNSD` | |Decrease transposition |
182|`MI_TRNSU` | |Increase transposition |
183|`MI_VEL_0` | |Set velocity to 0 |
184|`MI_VEL_1` | |Set velocity to 12 |
185|`MI_VEL_2` | |Set velocity to 25 |
186|`MI_VEL_3` | |Set velocity to 38 |
187|`MI_VEL_4` | |Set velocity to 51 |
188|`MI_VEL_5` | |Set velocity to 64 |
189|`MI_VEL_6` | |Set velocity to 76 |
190|`MI_VEL_7` | |Set velocity to 89 |
191|`MI_VEL_8` | |Set velocity to 102 |
192|`MI_VEL_9` | |Set velocity to 114 |
193|`MI_VEL_10` | |Set velocity to 127 |
194|`MI_VELD` | |Decrease velocity |
195|`MI_VELU` | |Increase velocity |
196|`MI_CH1` | |Set channel to 1 |
197|`MI_CH2` | |Set channel to 2 |
198|`MI_CH3` | |Set channel to 3 |
199|`MI_CH4` | |Set channel to 4 |
200|`MI_CH5` | |Set channel to 5 |
201|`MI_CH6` | |Set channel to 6 |
202|`MI_CH7` | |Set channel to 7 |
203|`MI_CH8` | |Set channel to 8 |
204|`MI_CH9` | |Set channel to 9 |
205|`MI_CH10` | |Set channel to 10 |
206|`MI_CH11` | |Set channel to 11 |
207|`MI_CH12` | |Set channel to 12 |
208|`MI_CH13` | |Set channel to 13 |
209|`MI_CH14` | |Set channel to 14 |
210|`MI_CH15` | |Set channel to 15 |
211|`MI_CH16` | |Set channel to 16 |
212|`MI_CHD` | |Decrease channel |
213|`MI_CHU` | |Increase channel |
214|`MI_ALLOFF` | |Stop all notes |
215|`MI_SUS` | |Sustain |
216|`MI_PORT` | |Portmento |
217|`MI_SOST` | |Sostenuto |
218|`MI_SOFT` | |Soft Pedal |
219|`MI_LEG` | |Legato |
220|`MI_MOD` | |Modulation |
221|`MI_MODSD` | |Decrease modulation speed |
222|`MI_MODSU` | |Increase modulation speed |
223|`MI_BENDD` | |Bend pitch down |
224|`MI_BENDU` | |Bend pitch up |
225
226### Configuration
227
228Certain values are stored in the `midi_config` struct. This configuration is not persisted to EEPROM. By default, these values are:
229
230|Configuration |Value|Comments |
231|-------------------|-----|-------------------------|
232|Octave |`4` |Corresponds to `MI_OCT_2`|
233|Transposition |`0` | |
234|Velocity |`127`| |
235|Channel |`0` | |
236|Modulation Interval|`8` | |
237
238For the above, the `MI_C` keycode will produce a C3 (note number 48), and so on.
239
240### References
241#### MIDI Specification
242
243 * [MIDI.org](https://www.midi.org/specifications-old/item/table-1-summary-of-midi-message)
244 * [CMU MIDI Programmer's Reference](https://www.cs.cmu.edu/~music/cmsip/readings/MIDI%20tutorial%20for%20programmers.html)
245#### QMK C Files
246
247 * `quantum/process_keycode/process_midi.c`
248 * `quantum/quantum_keycodes.h`
249 * `tmk_core/protocol/midi.h`
250 * `tmk_core/protocol/midi.c`
251 * `tmk_core/protocol/qmk_midi.c`
252 * `tmk_core/protocol/midi_device.h`
253
254<!--
255#### QMK Internals (Autogenerated)
256
257 * [Internals/MIDI Device Setup Process](internals_midi_device_setup_process.md)
258 * [Internals/MIDI Device](internals_midi_device.md)
259 * [Internals/MIDI Util](internals_midi_util.md)
260-->
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-05 03:35:58 +0000