docs/feature_audio.md

   1 # Audio
   2
   3 Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
   4
   5 Up to two simultaneous audio voices are supported, one driven by timer 1 and another driven by timer 3.  The following pins can be defined as audio outputs in config.h:
   6 Timer 1:
   7 `#define B5_AUDIO`
   8 `#define B6_AUDIO`
   9 `#define B7_AUDIO`
  10
  11 Timer 3:
  12 `#define C4_AUDIO`
  13 `#define C5_AUDIO`
  14 `#define C6_AUDIO`
  15
  16 If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration:
  17
  18 ```
  19 STARTUP_SONG // plays when the keyboard starts up (audio.c)
  20 GOODBYE_SONG // plays when you press the RESET key (quantum.c)
  21 AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
  22 AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
  23 MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
  24 MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
  25 CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)
  26 GUITAR_SONG // plays when the guitar music mode is selected (process_music.c)
  27 VIOLIN_SONG // plays when the violin music mode is selected (process_music.c)
  28 MAJOR_SONG // plays when the major music mode is selected (process_music.c)
  29 ```
  30
  31 You can override the default songs by doing something like this in your `config.h`:
  32
  33 ```c
  34 #ifdef AUDIO_ENABLE
  35   #define STARTUP_SONG SONG(STARTUP_SOUND)
  36 #endif
  37 ```
  38
  39 A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h).
  40
  41 To play a custom sound at a particular time, you can define a song like this (near the top of the file):
  42
  43 ```c
  44 float my_song[][2] = SONG(QWERTY_SOUND);
  45 ```
  46
  47 And then play your song like this:
  48
  49 ```c
  50 PLAY_SONG(my_song);
  51 ```
  52
  53 Alternatively, you can play it in a loop like this:
  54
  55 ```c
  56 PLAY_LOOP(my_song);
  57 ```
  58
  59 It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
  60
  61 ## Music Mode
  62
  63 The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode.
  64
  65 Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
  66
  67 Keycodes available:
  68
  69 * `MU_ON` - Turn music mode on
  70 * `MU_OFF` - Turn music mode off
  71 * `MU_TOG` - Toggle music mode
  72 * `MU_MOD` - Cycle through the music modes:
  73   * `CHROMATIC_MODE` - Chromatic scale, row changes the octave
  74   * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
  75   * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
  76   * `MAJOR_MODE` - Major scale
  77
  78 In music mode, the following keycodes work differently, and don't pass through:
  79
  80 * `LCTL` - start a recording
  81 * `LALT` - stop recording/stop playing
  82 * `LGUI` - play recording
  83 * `KC_UP` - speed-up playback
  84 * `KC_DOWN` - slow-down playback
  85
  86 By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this:
  87
  88     #define MUSIC_MASK keycode != KC_NO
  89
  90 Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
  91
  92 The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
  93
  94     #define PITCH_STANDARD_A 432.0f
  95
  96 You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller.  To disable it, add this to your `config.h`:
  97
  98     #define NO_MUSIC_MODE
  99
 100 ## MIDI Functionality
 101
 102 This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
 103
 104 <!-- FIXME: this formatting needs work
 105
 106 ## Audio
 107
 108 ```c
 109 #ifdef AUDIO_ENABLE
 110     AU_ON,
 111     AU_OFF,
 112     AU_TOG,
 113
 114     #ifdef FAUXCLICKY_ENABLE
 115         FC_ON,
 116         FC_OFF,
 117         FC_TOG,
 118     #endif
 119
 120     // Music mode on/off/toggle
 121     MU_ON,
 122     MU_OFF,
 123     MU_TOG,
 124
 125     // Music voice iterate
 126     MUV_IN,
 127     MUV_DE,
 128 #endif
 129 ```
 130
 131 ### Midi
 132
 133 #if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
 134     MI_ON,  // send midi notes when music mode is enabled
 135     MI_OFF, // don't send midi notes when music mode is enabled
 136 #endif
 137
 138 MIDI_TONE_MIN,
 139 MIDI_TONE_MAX
 140
 141 MI_C = MIDI_TONE_MIN,
 142 MI_Cs,
 143 MI_Db = MI_Cs,
 144 MI_D,
 145 MI_Ds,
 146 MI_Eb = MI_Ds,
 147 MI_E,
 148 MI_F,
 149 MI_Fs,
 150 MI_Gb = MI_Fs,
 151 MI_G,
 152 MI_Gs,
 153 MI_Ab = MI_Gs,
 154 MI_A,
 155 MI_As,
 156 MI_Bb = MI_As,
 157 MI_B,
 158
 159 MIDI_TONE_KEYCODE_OCTAVES > 1
 160
 161 where x = 1-5:
 162 MI_C_x,
 163 MI_Cs_x,
 164 MI_Db_x = MI_Cs_x,
 165 MI_D_x,
 166 MI_Ds_x,
 167 MI_Eb_x = MI_Ds_x,
 168 MI_E_x,
 169 MI_F_x,
 170 MI_Fs_x,
 171 MI_Gb_x = MI_Fs_x,
 172 MI_G_x,
 173 MI_Gs_x,
 174 MI_Ab_x = MI_Gs_x,
 175 MI_A_x,
 176 MI_As_x,
 177 MI_Bb_x = MI_As_x,
 178 MI_B_x,
 179
 180 MI_OCT_Nx 1-2
 181 MI_OCT_x 0-7
 182 MIDI_OCTAVE_MIN = MI_OCT_N2,
 183 MIDI_OCTAVE_MAX = MI_OCT_7,
 184 MI_OCTD, // octave down
 185 MI_OCTU, // octave up
 186
 187 MI_TRNS_Nx 1-6
 188 MI_TRNS_x 0-6
 189 MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
 190 MIDI_TRANSPOSE_MAX = MI_TRNS_6,
 191 MI_TRNSD, // transpose down
 192 MI_TRNSU, // transpose up
 193
 194 MI_VEL_x 1-10
 195 MIDI_VELOCITY_MIN = MI_VEL_1,
 196 MIDI_VELOCITY_MAX = MI_VEL_9,
 197 MI_VELD, // velocity down
 198 MI_VELU, // velocity up
 199
 200 MI_CHx 1-16
 201 MIDI_CHANNEL_MIN = MI_CH1
 202 MIDI_CHANNEL_MAX = MI_CH16,
 203 MI_CHD, // previous channel
 204 MI_CHU, // next channel
 205
 206 MI_ALLOFF, // all notes off
 207
 208 MI_SUS, // sustain
 209 MI_PORT, // portamento
 210 MI_SOST, // sostenuto
 211 MI_SOFT, // soft pedal
 212 MI_LEG,  // legato
 213
 214 MI_MOD, // modulation
 215 MI_MODSD, // decrease modulation speed
 216 MI_MODSU, // increase modulation speed
 217 #endif // MIDI_ADVANCED
 218
 219 -->