Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

added basic midi documention of common features #13113

Merged
merged 14 commits into from
Jun 7, 2021
Merged

added basic midi documention of common features #13113

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
d8f20ff
added basic midi documention of common features
wxyangf Jun 5, 2021
fc9c0cd
removed extra comment that confused example code
wxyangf Jun 5, 2021
e535680
Fixup spelling issues
wxyangf Jun 5, 2021
8cd5da5
spelling changes, etc
wxyangf Jun 5, 2021
fff0a72
added appropriate links
wxyangf Jun 5, 2021
314212a
Made changes as per @fauxpark's review
wxyangf Jun 5, 2021
4fbb1c8
Add Alias Col
wxyangf Jun 5, 2021
d54f611
As per @fauxpark's second review
wxyangf Jun 5, 2021
70eda39
MIDI Mode Description
wxyangf Jun 5, 2021
9fa9b48
Changed rules.mk to makefile (rules.mk)
wxyangf Jun 5, 2021
6f50416
Make codetype for codeblock 'makefile'
wxyangf Jun 5, 2021
5168f86
@fauxpark Changes for clarification
wxyangf Jun 5, 2021
c0baef5
removed extra comment marker from example code
wxyangf Jun 6, 2021
fc7526e
Add midi struct info
wxyangf Jun 6, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/_summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@
* [Haptic Feedback](feature_haptic_feedback.md)
* [Joystick](feature_joystick.md)
* [LED Indicators](feature_led_indicators.md)
* [MIDI](feature_midi.md)
* [Proton C Conversion](proton_c_conversion.md)
* [PS/2 Mouse](feature_ps2_mouse.md)
* [Split Keyboard](feature_split_keyboard.md)
Expand Down
114 changes: 1 addition & 113 deletions docs/feature_audio.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,8 +301,7 @@ You can configure the default, min and max frequencies, the stepping and built i

## MIDI Functionality

This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile.

See [MIDI](feature_midi.md)
fauxpark marked this conversation as resolved.
Show resolved Hide resolved

## Audio Keycodes

Expand All @@ -319,114 +318,3 @@ This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to s
|`MU_OFF` | |Turns off Music Mode |
|`MU_TOG` | |Toggles Music Mode |
|`MU_MOD` | |Cycles through the music modes |

<!-- FIXME: this formatting needs work

## Audio

```c
#ifdef AUDIO_ENABLE
AU_ON,
AU_OFF,
AU_TOG,

// Music mode on/off/toggle
MU_ON,
MU_OFF,
MU_TOG,

// Music voice iterate
MUV_IN,
MUV_DE,
#endif
```

### Midi

#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
MI_ON, // send midi notes when music mode is enabled
MI_OFF, // don't send midi notes when music mode is enabled
#endif

MIDI_TONE_MIN,
MIDI_TONE_MAX

MI_C = MIDI_TONE_MIN,
MI_Cs,
MI_Db = MI_Cs,
MI_D,
MI_Ds,
MI_Eb = MI_Ds,
MI_E,
MI_F,
MI_Fs,
MI_Gb = MI_Fs,
MI_G,
MI_Gs,
MI_Ab = MI_Gs,
MI_A,
MI_As,
MI_Bb = MI_As,
MI_B,

MIDI_TONE_KEYCODE_OCTAVES > 1

where x = 1-5:
MI_C_x,
MI_Cs_x,
MI_Db_x = MI_Cs_x,
MI_D_x,
MI_Ds_x,
MI_Eb_x = MI_Ds_x,
MI_E_x,
MI_F_x,
MI_Fs_x,
MI_Gb_x = MI_Fs_x,
MI_G_x,
MI_Gs_x,
MI_Ab_x = MI_Gs_x,
MI_A_x,
MI_As_x,
MI_Bb_x = MI_As_x,
MI_B_x,

MI_OCT_Nx 1-2
MI_OCT_x 0-7
MIDI_OCTAVE_MIN = MI_OCT_N2,
MIDI_OCTAVE_MAX = MI_OCT_7,
MI_OCTD, // octave down
MI_OCTU, // octave up

MI_TRNS_Nx 1-6
MI_TRNS_x 0-6
MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
MIDI_TRANSPOSE_MAX = MI_TRNS_6,
MI_TRNSD, // transpose down
MI_TRNSU, // transpose up

MI_VEL_x 1-10
MIDI_VELOCITY_MIN = MI_VEL_1,
MIDI_VELOCITY_MAX = MI_VEL_9,
MI_VELD, // velocity down
MI_VELU, // velocity up

MI_CHx 1-16
MIDI_CHANNEL_MIN = MI_CH1
MIDI_CHANNEL_MAX = MI_CH16,
MI_CHD, // previous channel
MI_CHU, // next channel

MI_ALLOFF, // all notes off

MI_SUS, // sustain
MI_PORT, // portamento
MI_SOST, // sostenuto
MI_SOFT, // soft pedal
MI_LEG, // legato

MI_MOD, // modulation
MI_MODSD, // decrease modulation speed
MI_MODSU, // increase modulation speed
#endif // MIDI_ADVANCED

-->
260 changes: 260 additions & 0 deletions docs/feature_midi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,260 @@
# MIDI

## Enabling MIDI

Add the following to the keyboard's rules.mk
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

```c
wxyangf marked this conversation as resolved.
Show resolved Hide resolved
MIDI_ENABLE = yes
```

## Using Basic MIDI

Enabling Basic MIDI

Add the following to your keyboard's config.h
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

```c
#define MIDI_BASIC
```

With basic MIDI you will only be able to send `NOTE_ON` and `NOTE_OFF` Commands to the internal MIDI device, meaning that keycodes like `MI_OCTU` and `MI_OCTD` will not work.

## Advanced MIDI

Enabling Advanced MIDI

Add the following to your keyboard's config.h
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

```c
#define MIDI_ADVANCED
```

With advanced MIDI you can do things like octave shifts, channel changes, velocity changes, and modulation.

### Sending MIDI Control Codes (MIDI CC)
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

If 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.

When sending MIDI CC you don't get the advantages of a preimplemented keycode and you will need to implement custom keycodes if you want to use them in your keymap directly using the function `process_record_user`. It is the same process as implementing custom keycodes for macros.

For an overview of that process look at: [Macros](feature_macros.md)
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

1. First enable MIDI_ADVANCED
2. use an `extern MidiDevice midi_device;` statement to bring the MIDI device into scope.
3. Send a control code with the `midi_send_cc(*midi_device, channel, number, value)` function
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

For reference of all the possible control code numbers see [MIDI Specification](#midi-specification)

#### Example code for using Generic On Off Switches as per MIDI Specification.
```c
#include QMK_KEYBOARD_H

extern MidiDevice midi_device;

/*
MIDI CC codes for generic ON/OFF swiches
80,81,82,83
values off = 0-63
*/

#define OFF 0

/*values on = 64-127*/

#define ON 127
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

enum custom_keycodes { MIDI_CC80 = SAFE_RANGE };
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case MIDI_CC80:
if (record->event.pressed) {
midi_send_cc(&midi_device, midi_config.channel, 80, ON);
} else {
midi_send_cc(&midi_device, midi_config.channel, 80, OFF);
}
return true;
}
return true;
};

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{MIDI_CC80, KC_ESC},
// ...
},
wxyangf marked this conversation as resolved.
Show resolved Hide resolved
};

wxyangf marked this conversation as resolved.
Show resolved Hide resolved
```

### Keycodes

|Keycode |Aliases |Description |
|------------|---------|---------------------------------|
|`MI_ON` | |Turn MIDI on |
|`MI_OFF` | |Turn MIDI off |
|`MI_TOG` | |Toggle MIDI enabled |
|`MI_C` | |C octave 0 |
|`MI_Cs` |`MI_Db` |C♯/D♭ octave 0 |
|`MI_D` | |D octave 0 |
|`MI_Ds` |`MI_Eb` |D♯/E♭ octave 0 |
|`MI_E` | |E octave 0 |
|`MI_F` | |F octave 0 |
|`MI_Fs` |`MI_Gb` |F♯/G♭ octave 0 |
|`MI_G` | |G octave 0 |
|`MI_Gs` |`MI_Gs` |G♯/A♭ octave 0 |
|`MI_A` | |A octave 0 |
|`MI_As` |`MI_Bb` |A♯/B♭ octave 0 |
|`MI_B` | |B octave 0 |
|`MI_C_1` | |C octave 1 |
|`MI_Cs_1` |`MI_Db_1`|C♯/D♭ octave 1 |
|`MI_D_1` | |D octave 1 |
|`MI_Ds_1` |`MI_Eb_1`|D♯/E♭ octave 1 |
|`MI_E_1` | |E octave 1 |
|`MI_F_1` | |F octave 1 |
|`MI_Fs_1` |`MI_Gb_1`|F♯/G♭ octave 1 |
|`MI_G_1` | |G octave 1 |
|`MI_Gs_1` |`MI_Ab_1`|G♯/A♭ octave 1 |
|`MI_A_1` | |A octave 1 |
|`MI_As_1` |`MI_Bb_1`|A♯/B♭ octave 1 |
|`MI_B_1` | |B octave 1 |
|`MI_C_2` | |C octave 2 |
|`MI_Cs_2` |`MI_Db_2`|C♯/D♭ octave 2 |
|`MI_D_2` | |D octave 2 |
|`MI_Ds_2` |`MI_Eb_2`|D♯/E♭ octave 2 |
|`MI_E_2` | |E octave 2 |
|`MI_F_2` | |F octave 2 |
|`MI_Fs_2` |`MI_Gb_2`|F♯/G♭ octave 2 |
|`MI_G_2` | |G octave 2 |
|`MI_Gs_2` |`MI_Ab_2`|G♯/A♭ octave 2 |
|`MI_A_2` | |A octave 2 |
|`MI_As_2` |`MI_Bb_2`|A♯/B♭ octave 2 |
|`MI_B_2` | |B octave 2 |
|`MI_C_3` | |C octave 3 |
|`MI_Cs_3` |`MI_Db_3`|C♯/D♭ octave 3 |
|`MI_D_3` | |D octave 3 |
|`MI_Ds_3` |`MI_Eb_3`|D♯/E♭ octave 3 |
|`MI_E_3` | |E octave 3 |
|`MI_F_3` | |F octave 3 |
|`MI_Fs_3` |`MI_Gb_3`|F♯/G♭ octave 3 |
|`MI_G_3` | |G octave 3 |
|`MI_Gs_3` |`MI_Ab_3`|G♯/A♭ octave 3 |
|`MI_A_3` | |A octave 3 |
|`MI_As_3` |`MI_Bb_3`|A♯/B♭ octave 3 |
|`MI_B_3` | |B octave 3 |
|`MI_C_4` | |C octave 4 |
|`MI_Cs_4` |`MI_Db_4`|C♯/D♭ octave 4 |
|`MI_D_4` | |D octave 4 |
|`MI_Ds_4` |`MI_Eb_4`|D♯/E♭ octave 4 |
|`MI_E_4` | |E octave 4 |
|`MI_F_4` | |F octave 4 |
|`MI_Fs_4` |`MI_Gb_4`|F♯/G♭ octave 4 |
|`MI_G_4` | |G octave 4 |
|`MI_Gs_4` |`MI_Ab_4`|G♯/A♭ octave 4 |
|`MI_A_4` | |A octave 4 |
|`MI_As_4` |`MI_Bb_4`|A♯/B♭ octave 4 |
|`MI_B_4` | |B octave 4 |
|`MI_C_5` | |C octave 5 |
|`MI_Cs_5` |`MI_Db_5`|C♯/D♭ octave 5 |
|`MI_D_5` | |D octave 5 |
|`MI_Ds_5` |`MI_Eb_5`|D♯/E♭ octave 5 |
|`MI_E_5` | |E octave 5 |
|`MI_F_5` | |F octave 5 |
|`MI_Fs_5` |`MI_Gb_5`|F♯/G♭ octave 5 |
|`MI_G_5` | |G octave 5 |
|`MI_Gs_5` |`MI_Ab_5`|G♯/A♭ octave 5 |
|`MI_A_5` | |A octave 5 |
|`MI_As_5` |`MI_Bb_5`|A♯/B♭ octave 5 |
|`MI_B_5` | |B octave 5 |
|`MI_OCT_N2` | |Set octave to -2 |
|`MI_OCT_N1` | |Set octave to -1 |
|`MI_OCT_0` | |Set octave to 0 |
|`MI_OCT_1` | |Set octave to 1 |
|`MI_OCT_2` | |Set octave to 2 |
|`MI_OCT_3` | |Set octave to 3 |
|`MI_OCT_4` | |Set octave to 4 |
|`MI_OCT_5` | |Set octave to 5 |
|`MI_OCT_6` | |Set octave to 6 |
|`MI_OCT_7` | |Set octave to 7 |
|`MI_OCTD` | |Move down an octave |
|`MI_OCTU` | |Move up an octave |
|`MI_TRNS_N6`| |Set transposition to -6 semitones|
|`MI_TRNS_N5`| |Set transposition to -5 semitones|
|`MI_TRNS_N4`| |Set transposition to -4 semitones|
|`MI_TRNS_N3`| |Set transposition to -3 semitones|
|`MI_TRNS_N2`| |Set transposition to -2 semitones|
|`MI_TRNS_N1`| |Set transposition to -1 semitone |
|`MI_TRNS_0` | |No transposition |
|`MI_TRNS_1` | |Set transposition to +1 semitone |
|`MI_TRNS_2` | |Set transposition to +2 semitones|
|`MI_TRNS_3` | |Set transposition to +3 semitones|
|`MI_TRNS_4` | |Set transposition to +4 semitones|
|`MI_TRNS_5` | |Set transposition to +5 semitones|
|`MI_TRNS_6` | |Set transposition to +6 semitones|
|`MI_TRNSD` | |Decrease transposition |
|`MI_TRNSU` | |Increase transposition |
|`MI_VEL_0` | |Set velocity to 0 |
|`MI_VEL_1` | |Set velocity to 12 |
|`MI_VEL_2` | |Set velocity to 25 |
|`MI_VEL_3` | |Set velocity to 38 |
|`MI_VEL_4` | |Set velocity to 51 |
|`MI_VEL_5` | |Set velocity to 64 |
|`MI_VEL_6` | |Set velocity to 76 |
|`MI_VEL_7` | |Set velocity to 89 |
|`MI_VEL_8` | |Set velocity to 102 |
|`MI_VEL_9` | |Set velocity to 114 |
|`MI_VEL_10` | |Set velocity to 127 |
|`MI_VELD` | |Decrease velocity |
|`MI_VELU` | |Increase velocity |
|`MI_CH1` | |Set channel to 1 |
|`MI_CH2` | |Set channel to 2 |
|`MI_CH3` | |Set channel to 3 |
|`MI_CH4` | |Set channel to 4 |
|`MI_CH5` | |Set channel to 5 |
|`MI_CH6` | |Set channel to 6 |
|`MI_CH7` | |Set channel to 7 |
|`MI_CH8` | |Set channel to 8 |
|`MI_CH9` | |Set channel to 9 |
|`MI_CH10` | |Set channel to 10 |
|`MI_CH11` | |Set channel to 11 |
|`MI_CH12` | |Set channel to 12 |
|`MI_CH13` | |Set channel to 13 |
|`MI_CH14` | |Set channel to 14 |
|`MI_CH15` | |Set channel to 15 |
|`MI_CH16` | |Set channel to 16 |
|`MI_CHD` | |Decrease channel |
|`MI_CHU` | |Increase channel |
|`MI_ALLOFF` | |Stop all notes |
|`MI_SUS` | |Sustain |
|`MI_PORT` | |Portmento |
|`MI_SOST` | |Sostenuto |
|`MI_SOFT` | |Soft Pedal |
|`MI_LEG` | |Legato |
|`MI_MOD` | |Modulation |
|`MI_MODSD` | |Decrease modulation speed |
|`MI_MODSU` | |Increase modulation speed |
|`MI_BENDD` | |Bend pitch down |
|`MI_BENDU` | |Bend pitch up |
wxyangf marked this conversation as resolved.
Show resolved Hide resolved

### References
#### MIDI Specification

* [MIDI.org](https://www.midi.org/specifications-old/item/table-1-summary-of-midi-message)
* [CMU MIDI Programmer's Reference](https://www.cs.cmu.edu/~music/cmsip/readings/MIDI%20tutorial%20for%20programmers.html)
#### QMK C Files

* `quantum/process_keycode/process_midi.c`
* `quantum/quantum_keycodes.h`
* `tmk_core/protocol/midi.h`
* `tmk_core/protocol/midi.c`
* `tmk_core/protocol/qmk_midi.c`
* `tmk_core/protocol/midi_device.h`

<!--
#### QMK Internals (Autogenerated)

* [Internals/MIDI Device Setup Process](internals_midi_device_setup_process.md)
* [Internals/MIDI Device](internals_midi_device.md)
* [Internals/MIDI Util](internals_midi_util.md)
-->