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
   7 Timer 1:
   8 `#define B5_AUDIO`
   9 `#define B6_AUDIO`
  10 `#define B7_AUDIO`
  11
  12 Timer 3:
  13 `#define C4_AUDIO`
  14 `#define C5_AUDIO`
  15 `#define C6_AUDIO`
  16
  17 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:
  18
  19 ```
  20 STARTUP_SONG // plays when the keyboard starts up (audio.c)
  21 GOODBYE_SONG // plays when you press the RESET key (quantum.c)
  22 AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
  23 AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
  24 MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
  25 MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
  26 CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)
  27 GUITAR_SONG // plays when the guitar music mode is selected (process_music.c)
  28 VIOLIN_SONG // plays when the violin music mode is selected (process_music.c)
  29 MAJOR_SONG // plays when the major music mode is selected (process_music.c)
  30 ```
  31
  32 You can override the default songs by doing something like this in your `config.h`:
  33
  34 ```c
  35 #ifdef AUDIO_ENABLE
  36   #define STARTUP_SONG SONG(STARTUP_SOUND)
  37 #endif
  38 ```
  39
  40 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).
  41
  42 To play a custom sound at a particular time, you can define a song like this (near the top of the file):
  43
  44 ```c
  45 float my_song[][2] = SONG(QWERTY_SOUND);
  46 ```
  47
  48 And then play your song like this:
  49
  50 ```c
  51 PLAY_SONG(my_song);
  52 ```
  53
  54 Alternatively, you can play it in a loop like this:
  55
  56 ```c
  57 PLAY_LOOP(my_song);
  58 ```
  59
  60 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.
  61
  62 The available keycodes for audio are:
  63
  64 * `AU_ON` - Turn audio mode on
  65 * `AU_OFF` - Turn audio mode off
  66 * `AU_TOG` - Toggle audio mode
  67
  68
  69 ## Music Mode
  70
  71 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.
  72
  73 Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
  74
  75 Keycodes available:
  76
  77 * `MU_ON` - Turn music mode on
  78 * `MU_OFF` - Turn music mode off
  79 * `MU_TOG` - Toggle music mode
  80 * `MU_MOD` - Cycle through the music modes:
  81   * `CHROMATIC_MODE` - Chromatic scale, row changes the octave
  82   * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
  83   * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
  84   * `MAJOR_MODE` - Major scale
  85
  86 In music mode, the following keycodes work differently, and don't pass through:
  87
  88 * `LCTL` - start a recording
  89 * `LALT` - stop recording/stop playing
  90 * `LGUI` - play recording
  91 * `KC_UP` - speed-up playback
  92 * `KC_DOWN` - slow-down playback
  93
  94 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:
  95
  96     #define MUSIC_MASK keycode != KC_NO
  97
  98 Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
  99
 100 For a more advanced way to control which keycodes should still be processed, you can use `music_mask_kb(keycode)` in `<keyboard>.c` and `music_mask_user(keycode)` in your `keymap.c`:
 101
 102     bool music_mask_user(uint16_t keycode) {
 103       switch (keycode) {
 104         case RAISE:
 105         case LOWER:
 106           return false;
 107         default:
 108           return true;
 109       }
 110     }
 111
 112 Things that return false are not part of the mask, and are always processed.
 113
 114 The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
 115
 116     #define PITCH_STANDARD_A 432.0f
 117
 118 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`:
 119
 120     #define NO_MUSIC_MODE
 121
 122 ## Faux Click
 123
 124 This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly.
 125
 126 * `CK_TOGG` - Toggles the status (will play sound if enabled)
 127 * `CK_RST` - Resets the frequency to the default state
 128 * `CK_UP` - Increases the frequency of the clicks
 129 * `CK_DOWN` - Decreases the frequency of the clicks
 130
 131
 132 The feature is disabled by default, to save space.  To enable it, add this to your `config.h`:
 133
 134     #define AUDIO_CLICKY
 135
 136
 137 You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values:
 138
 139 | Option | Default Value | Description |
 140 |--------|---------------|-------------|
 141 | `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. |
 142 | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
 143 | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
 144 | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. |
 145 | `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical. |
 146
 147
 148
 149
 150 ## MIDI Functionality
 151
 152 This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
 153
 154
 155 ## Audio Keycodes
 156
 157 |Key             |Aliases  |Description                       |
 158 |----------------|---------|----------------------------------|
 159 |`AU_ON`         |         |Audio mode on                     |
 160 |`AU_OFF`        |         |Audio mode off                    |
 161 |`AU_TOG`        |         |Toggles Audio mode                |
 162 |`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode         |
 163 |`CLICKY_UP`     |`CK_UP`  |Increases frequency of the clicks |
 164 |`CLICKY_DOWN`   |`CK_DOWN`|Decreases frequency of the clicks |
 165 |`CLICKY_RESET`  |`CK_RST` |Resets frequency to default       |
 166 |`MU_ON`         |         |Turns on Music Mode               |
 167 |`MU_OFF`        |         |Turns off Music Mode              |
 168 |`MU_TOG`        |         |Toggles Music Mode                |
 169 |`MU_MOD`        |         |Cycles through the music modes    |
 170
 171 <!-- FIXME: this formatting needs work
 172
 173 ## Audio
 174
 175 ```c
 176 #ifdef AUDIO_ENABLE
 177     AU_ON,
 178     AU_OFF,
 179     AU_TOG,
 180
 181     #ifdef FAUXCLICKY_ENABLE
 182         FC_ON,
 183         FC_OFF,
 184         FC_TOG,
 185     #endif
 186
 187     // Music mode on/off/toggle
 188     MU_ON,
 189     MU_OFF,
 190     MU_TOG,
 191
 192     // Music voice iterate
 193     MUV_IN,
 194     MUV_DE,
 195 #endif
 196 ```
 197
 198 ### Midi
 199
 200 #if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
 201     MI_ON,  // send midi notes when music mode is enabled
 202     MI_OFF, // don't send midi notes when music mode is enabled
 203 #endif
 204
 205 MIDI_TONE_MIN,
 206 MIDI_TONE_MAX
 207
 208 MI_C = MIDI_TONE_MIN,
 209 MI_Cs,
 210 MI_Db = MI_Cs,
 211 MI_D,
 212 MI_Ds,
 213 MI_Eb = MI_Ds,
 214 MI_E,
 215 MI_F,
 216 MI_Fs,
 217 MI_Gb = MI_Fs,
 218 MI_G,
 219 MI_Gs,
 220 MI_Ab = MI_Gs,
 221 MI_A,
 222 MI_As,
 223 MI_Bb = MI_As,
 224 MI_B,
 225
 226 MIDI_TONE_KEYCODE_OCTAVES > 1
 227
 228 where x = 1-5:
 229 MI_C_x,
 230 MI_Cs_x,
 231 MI_Db_x = MI_Cs_x,
 232 MI_D_x,
 233 MI_Ds_x,
 234 MI_Eb_x = MI_Ds_x,
 235 MI_E_x,
 236 MI_F_x,
 237 MI_Fs_x,
 238 MI_Gb_x = MI_Fs_x,
 239 MI_G_x,
 240 MI_Gs_x,
 241 MI_Ab_x = MI_Gs_x,
 242 MI_A_x,
 243 MI_As_x,
 244 MI_Bb_x = MI_As_x,
 245 MI_B_x,
 246
 247 MI_OCT_Nx 1-2
 248 MI_OCT_x 0-7
 249 MIDI_OCTAVE_MIN = MI_OCT_N2,
 250 MIDI_OCTAVE_MAX = MI_OCT_7,
 251 MI_OCTD, // octave down
 252 MI_OCTU, // octave up
 253
 254 MI_TRNS_Nx 1-6
 255 MI_TRNS_x 0-6
 256 MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
 257 MIDI_TRANSPOSE_MAX = MI_TRNS_6,
 258 MI_TRNSD, // transpose down
 259 MI_TRNSU, // transpose up
 260
 261 MI_VEL_x 1-10
 262 MIDI_VELOCITY_MIN = MI_VEL_1,
 263 MIDI_VELOCITY_MAX = MI_VEL_9,
 264 MI_VELD, // velocity down
 265 MI_VELU, // velocity up
 266
 267 MI_CHx 1-16
 268 MIDI_CHANNEL_MIN = MI_CH1
 269 MIDI_CHANNEL_MAX = MI_CH16,
 270 MI_CHD, // previous channel
 271 MI_CHU, // next channel
 272
 273 MI_ALLOFF, // all notes off
 274
 275 MI_SUS, // sustain
 276 MI_PORT, // portamento
 277 MI_SOST, // sostenuto
 278 MI_SOFT, // soft pedal
 279 MI_LEG,  // legato
 280
 281 MI_MOD, // modulation
 282 MI_MODSD, // decrease modulation speed
 283 MI_MODSU, // increase modulation speed
 284 #endif // MIDI_ADVANCED
 285
 286 -->