Skip to content

Latest commit

 

History

History
264 lines (229 loc) · 16.1 KB

feature_midi.md

File metadata and controls

264 lines (229 loc) · 16.1 KB
Raw

MIDI

Usage

First, enable MIDI by adding the following to your rules.mk:

MIDI_ENABLE = yes

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

Caveats

MIDI requires 2 USB endpoints and as such may not work on some hardware such as V-USB controllers.

Basic MIDI

To enable basic MIDI, add the following to your config.h:

#define MIDI_BASIC

Advanced MIDI

To enable advanced MIDI, add the following to your config.h:

#define MIDI_ADVANCED

Sending Control Change (CC) Messages

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.

Because 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 if you want to use them in your keymap directly using process_record_user().

For reference of all the possible control code numbers see MIDI Specification

Example code for using Generic On Off Switches as per MIDI Specification.

#include QMK_KEYBOARD_H

extern MidiDevice midi_device;

// MIDI CC codes for generic on/off switches (80, 81, 82, 83)
// Off: 0-63
// On:  64-127

#define MIDI_CC_OFF 0
#define MIDI_CC_ON  127

enum custom_keycodes {
    MIDI_CC80 = SAFE_RANGE,
};

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, MIDI_CC_ON);
            } else {
                midi_send_cc(&midi_device, midi_config.channel, 80, MIDI_CC_OFF);
            }
            return true;
    }
    return true;
};

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    LAYOUT(
        // ...
        MIDI_CC80,
        // ...
    )
};

Keycodes

Keycode Aliases Description
QK_MIDI_ON MI_ON Turn MIDI on
QK_MIDI_OFF MI_OFF Turn MIDI off
QK_MIDI_TOGGLE MI_TOGG Toggle MIDI enabled
QK_MIDI_NOTE_C_0 MI_C C octave 0
QK_MIDI_NOTE_C_SHARP_0 MI_Cs, MI_Db C♯/D♭ octave 0
QK_MIDI_NOTE_D_0 MI_D D octave 0
QK_MIDI_NOTE_D_SHARP_0 MI_Ds, MI_Eb D♯/E♭ octave 0
QK_MIDI_NOTE_E_0 MI_E E octave 0
QK_MIDI_NOTE_F_0 MI_F F octave 0
QK_MIDI_NOTE_F_SHARP_0 MI_Fs, MI_Gb F♯/G♭ octave 0
QK_MIDI_NOTE_G_0 MI_G G octave 0
QK_MIDI_NOTE_G_SHARP_0 MI_Gs, MI_Ab G♯/A♭ octave 0
QK_MIDI_NOTE_A_0 MI_A A octave 0
QK_MIDI_NOTE_A_SHARP_0 MI_As, MI_Bb A♯/B♭ octave 0
QK_MIDI_NOTE_B_0 MI_B B octave 0
QK_MIDI_NOTE_C_1 MI_C1 C octave 1
QK_MIDI_NOTE_C_SHARP_1 MI_Cs1, MI_Db1 C♯/D♭ octave 1
QK_MIDI_NOTE_D_1 MI_D1 D octave 1
QK_MIDI_NOTE_D_SHARP_1 MI_Ds1, MI_Eb1 D♯/E♭ octave 1
QK_MIDI_NOTE_E_1 MI_E1 E octave 1
QK_MIDI_NOTE_F_1 MI_F1 F octave 1
QK_MIDI_NOTE_F_SHARP_1 MI_Fs1, MI_Gb1 F♯/G♭ octave 1
QK_MIDI_NOTE_G_1 MI_G1 G octave 1
QK_MIDI_NOTE_G_SHARP_1 MI_Gs1, MI_Ab1 G♯/A♭ octave 1
QK_MIDI_NOTE_A_1 MI_A1 A octave 1
QK_MIDI_NOTE_A_SHARP_1 MI_As1, MI_Bb1 A♯/B♭ octave 1
QK_MIDI_NOTE_B_1 MI_B1 B octave 1
QK_MIDI_NOTE_C_2 MI_C2 C octave 2
QK_MIDI_NOTE_C_SHARP_2 MI_Cs2, MI_Db2 C♯/D♭ octave 2
QK_MIDI_NOTE_D_2 MI_D2 D octave 2
QK_MIDI_NOTE_D_SHARP_2 MI_Ds2, MI_Eb2 D♯/E♭ octave 2
QK_MIDI_NOTE_E_2 MI_E2 E octave 2
QK_MIDI_NOTE_F_2 MI_F2 F octave 2
QK_MIDI_NOTE_F_SHARP_2 MI_Fs2, MI_Gb2 F♯/G♭ octave 2
QK_MIDI_NOTE_G_2 MI_G2 G octave 2
QK_MIDI_NOTE_G_SHARP_2 MI_Gs2, MI_Ab2 G♯/A♭ octave 2
QK_MIDI_NOTE_A_2 MI_A2 A octave 2
QK_MIDI_NOTE_A_SHARP_2 MI_As2, MI_Bb2 A♯/B♭ octave 2
QK_MIDI_NOTE_B_2 MI_B2 B octave 2
QK_MIDI_NOTE_C_3 MI_C3 C octave 3
QK_MIDI_NOTE_C_SHARP_3 MI_Cs3, MI_Db3 C♯/D♭ octave 3
QK_MIDI_NOTE_D_3 MI_D3 D octave 3
QK_MIDI_NOTE_D_SHARP_3 MI_Ds3, MI_Eb3 D♯/E♭ octave 3
QK_MIDI_NOTE_E_3 MI_E3 E octave 3
QK_MIDI_NOTE_F_3 MI_F3 F octave 3
QK_MIDI_NOTE_F_SHARP_3 MI_Fs3, MI_Gb3 F♯/G♭ octave 3
QK_MIDI_NOTE_G_3 MI_G3 G octave 3
QK_MIDI_NOTE_G_SHARP_3 MI_Gs3, MI_Ab3 G♯/A♭ octave 3
QK_MIDI_NOTE_A_3 MI_A3 A octave 3
QK_MIDI_NOTE_A_SHARP_3 MI_As3, MI_Bb3 A♯/B♭ octave 3
QK_MIDI_NOTE_B_3 MI_B3 B octave 3
QK_MIDI_NOTE_C_4 MI_C4 C octave 4
QK_MIDI_NOTE_C_SHARP_4 MI_Cs4, MI_Db4 C♯/D♭ octave 4
QK_MIDI_NOTE_D_4 MI_D4 D octave 4
QK_MIDI_NOTE_D_SHARP_4 MI_Ds4, MI_Eb4 D♯/E♭ octave 4
QK_MIDI_NOTE_E_4 MI_E4 E octave 4
QK_MIDI_NOTE_F_4 MI_F4 F octave 4
QK_MIDI_NOTE_F_SHARP_4 MI_Fs4, MI_Gb4 F♯/G♭ octave 4
QK_MIDI_NOTE_G_4 MI_G4 G octave 4
QK_MIDI_NOTE_G_SHARP_4 MI_Gs4, MI_Ab4 G♯/A♭ octave 4
QK_MIDI_NOTE_A_4 MI_A4 A octave 4
QK_MIDI_NOTE_A_SHARP_4 MI_As4, MI_Bb4 A♯/B♭ octave 4
QK_MIDI_NOTE_B_4 MI_B4 B octave 4
QK_MIDI_NOTE_C_5 MI_C5 C octave 5
QK_MIDI_NOTE_C_SHARP_5 MI_Cs5, MI_Db5 C♯/D♭ octave 5
QK_MIDI_NOTE_D_5 MI_D5 D octave 5
QK_MIDI_NOTE_D_SHARP_5 MI_Ds5, MI_Eb5 D♯/E♭ octave 5
QK_MIDI_NOTE_E_5 MI_E5 E octave 5
QK_MIDI_NOTE_F_5 MI_F5 F octave 5
QK_MIDI_NOTE_F_SHARP_5 MI_Fs5, MI_Gb5 F♯/G♭ octave 5
QK_MIDI_NOTE_G_5 MI_G5 G octave 5
QK_MIDI_NOTE_G_SHARP_5 MI_Gs5, MI_Ab5 G♯/A♭ octave 5
QK_MIDI_NOTE_A_5 MI_A5 A octave 5
QK_MIDI_NOTE_A_SHARP_5 MI_As5, MI_Bb5 A♯/B♭ octave 5
QK_MIDI_NOTE_B_5 MI_B5 B octave 5
QK_MIDI_OCTAVE_N2 MI_OCN2 Set octave to -2
QK_MIDI_OCTAVE_N1 MI_OCN1 Set octave to -1
QK_MIDI_OCTAVE_0 MI_OC0 Set octave to 0
QK_MIDI_OCTAVE_1 MI_OC1 Set octave to 1
QK_MIDI_OCTAVE_2 MI_OC2 Set octave to 2
QK_MIDI_OCTAVE_3 MI_OC3 Set octave to 3
QK_MIDI_OCTAVE_4 MI_OC4 Set octave to 4
QK_MIDI_OCTAVE_5 MI_OC5 Set octave to 5
QK_MIDI_OCTAVE_6 MI_OC6 Set octave to 6
QK_MIDI_OCTAVE_7 MI_OC7 Set octave to 7
QK_MIDI_OCTAVE_DOWN MI_OCTD Move down an octave
QK_MIDI_OCTAVE_UP MI_OCTU Move up an octave
QK_MIDI_TRANSPOSE_N6 MI_TRN6 Set transposition to -6 semitones
QK_MIDI_TRANSPOSE_N5 MI_TRN5 Set transposition to -5 semitones
QK_MIDI_TRANSPOSE_N4 MI_TRN4 Set transposition to -4 semitones
QK_MIDI_TRANSPOSE_N3 MI_TRN3 Set transposition to -3 semitones
QK_MIDI_TRANSPOSE_N2 MI_TRN2 Set transposition to -2 semitones
QK_MIDI_TRANSPOSE_N1 MI_TRN1 Set transposition to -1 semitone
QK_MIDI_TRANSPOSE_0 MI_TR0 No transposition
QK_MIDI_TRANSPOSE_1 MI_TR1 Set transposition to +1 semitone
QK_MIDI_TRANSPOSE_2 MI_TR2 Set transposition to +2 semitones
QK_MIDI_TRANSPOSE_3 MI_TR3 Set transposition to +3 semitones
QK_MIDI_TRANSPOSE_4 MI_TR4 Set transposition to +4 semitones
QK_MIDI_TRANSPOSE_5 MI_TR5 Set transposition to +5 semitones
QK_MIDI_TRANSPOSE_6 MI_TR6 Set transposition to +6 semitones
QK_MIDI_TRANSPOSE_DOWN MI_TRSD Decrease transposition
QK_MIDI_TRANSPOSE_UP MI_TRSU Increase transposition
QK_MIDI_VELOCITY_0 MI_VL0 Set velocity to 0
QK_MIDI_VELOCITY_1 MI_VL1 Set velocity to 12
QK_MIDI_VELOCITY_2 MI_VL2 Set velocity to 25
QK_MIDI_VELOCITY_3 MI_VL3 Set velocity to 38
QK_MIDI_VELOCITY_4 MI_VL4 Set velocity to 51
QK_MIDI_VELOCITY_5 MI_VL5 Set velocity to 64
QK_MIDI_VELOCITY_6 MI_VL6 Set velocity to 76
QK_MIDI_VELOCITY_7 MI_VL7 Set velocity to 89
QK_MIDI_VELOCITY_8 MI_VL8 Set velocity to 102
QK_MIDI_VELOCITY_9 MI_VL9 Set velocity to 114
QK_MIDI_VELOCITY_10 MI_VL10 Set velocity to 127
QK_MIDI_VELOCITY_DOWN MI_VELD Decrease velocity
QK_MIDI_VELOCITY_UP MI_VELU Increase velocity
QK_MIDI_CHANNEL_1 MI_CH1 Set channel to 1
QK_MIDI_CHANNEL_2 MI_CH2 Set channel to 2
QK_MIDI_CHANNEL_3 MI_CH3 Set channel to 3
QK_MIDI_CHANNEL_4 MI_CH4 Set channel to 4
QK_MIDI_CHANNEL_5 MI_CH5 Set channel to 5
QK_MIDI_CHANNEL_6 MI_CH6 Set channel to 6
QK_MIDI_CHANNEL_7 MI_CH7 Set channel to 7
QK_MIDI_CHANNEL_8 MI_CH8 Set channel to 8
QK_MIDI_CHANNEL_9 MI_CH9 Set channel to 9
QK_MIDI_CHANNEL_10 MI_CH10 Set channel to 10
QK_MIDI_CHANNEL_11 MI_CH11 Set channel to 11
QK_MIDI_CHANNEL_12 MI_CH12 Set channel to 12
QK_MIDI_CHANNEL_13 MI_CH13 Set channel to 13
QK_MIDI_CHANNEL_14 MI_CH14 Set channel to 14
QK_MIDI_CHANNEL_15 MI_CH15 Set channel to 15
QK_MIDI_CHANNEL_16 MI_CH16 Set channel to 16
QK_MIDI_CHANNEL_DOWN MI_CHND Decrease channel
QK_MIDI_CHANNEL_UP MI_CHNU Increase channel
QK_MIDI_ALL_NOTES_OFF MI_AOFF Stop all notes
QK_MIDI_SUSTAIN MI_SUST Sustain
QK_MIDI_PORTAMENTO MI_PORT Portmento
QK_MIDI_SOSTENUTO MI_SOST Sostenuto
QK_MIDI_SOFT MI_SOFT Soft Pedal
QK_MIDI_LEGATO MI_LEG Legato
QK_MIDI_MODULATION MI_MOD Modulation
QK_MIDI_MODULATION_SPEED_DOWN MI_MODD Decrease modulation speed
QK_MIDI_MODULATION_SPEED_UP MI_MODU Increase modulation speed
QK_MIDI_PITCH_BEND_DOWN MI_BNDD Bend pitch down
QK_MIDI_PITCH_BEND_UP MI_BNDU Bend pitch up

Configuration

Certain values are stored in the midi_config struct. This configuration is not persisted to EEPROM. By default, these values are:

Configuration Value Comments
Octave 4 Corresponds to MI_OC2
Transposition 0
Velocity 127
Channel 0
Modulation Interval 8

For the above, the MI_C keycode will produce a C3 (note number 48), and so on.

References

MIDI Specification

QMK C Files

  • quantum/process_keycode/process_midi.c
  • quantum/quantum_keycodes.h
  • quantum/midi/midi.h
  • quantum/midi/midi.c
  • quantum/midi/qmk_midi.c
  • quantum/midi/midi_device.h