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 The feature is disabled by default, to save space.  To enable it, add this to your `config.h`:
 132
 133     #define AUDIO_CLICKY
 134
 135 Additionally, even when enabled, the feature is not enabled by default, so you would need to turn it on first.  And since we don't use EEPROM to store the setting (yet), you can default this to on by adding this to your `config.h`:
 136
 137     #define AUDIO_CLICKY_ON
 138
 139 You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values:
 140
 141 | Option | Default Value | Description |
 142 |--------|---------------|-------------|
 143 | `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. |
 144 | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
 145 | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
 146 | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. |
 147 | `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical. |
 148
 149
 150
 151
 152 ## MIDI Functionality
 153
 154 This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
 155
 156
 157 ## Audio Keycodes
 158
 159 |Key             |Aliases  |Description                       |
 160 |----------------|---------|----------------------------------|
 161 |`AU_ON`         |         |Audio mode on                     |
 162 |`AU_OFF`        |         |Audio mode off                    |
 163 |`AU_TOG`        |         |Toggles Audio mode                |
 164 |`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode         |
 165 |`CLICKY_UP`     |`CK_UP`  |Increases frequency of the clicks |
 166 |`CLICKY_DOWN`   |`CK_DOWN`|Decreases frequency of the clicks |
 167 |`CLICKY_RESET`  |`CK_RST` |Resets frequency to default       |
 168 |`MU_ON`         |         |Turns on Music Mode               |
 169 |`MU_OFF`        |         |Turns off Music Mode              |
 170 |`MU_TOG`        |         |Toggles Music Mode                |
 171 |`MU_MOD`        |         |Cycles through the music modes    |
 172
 173 <!-- FIXME: this formatting needs work
 174
 175 ## Audio
 176
 177 ```c
 178 #ifdef AUDIO_ENABLE
 179     AU_ON,
 180     AU_OFF,
 181     AU_TOG,
 182
 183     #ifdef FAUXCLICKY_ENABLE
 184         FC_ON,
 185         FC_OFF,
 186         FC_TOG,
 187     #endif
 188
 189     // Music mode on/off/toggle
 190     MU_ON,
 191     MU_OFF,
 192     MU_TOG,
 193
 194     // Music voice iterate
 195     MUV_IN,
 196     MUV_DE,
 197 #endif
 198 ```
 199
 200 ### Midi
 201
 202 #if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
 203     MI_ON,  // send midi notes when music mode is enabled
 204     MI_OFF, // don't send midi notes when music mode is enabled
 205 #endif
 206
 207 MIDI_TONE_MIN,
 208 MIDI_TONE_MAX
 209
 210 MI_C = MIDI_TONE_MIN,
 211 MI_Cs,
 212 MI_Db = MI_Cs,
 213 MI_D,
 214 MI_Ds,
 215 MI_Eb = MI_Ds,
 216 MI_E,
 217 MI_F,
 218 MI_Fs,
 219 MI_Gb = MI_Fs,
 220 MI_G,
 221 MI_Gs,
 222 MI_Ab = MI_Gs,
 223 MI_A,
 224 MI_As,
 225 MI_Bb = MI_As,
 226 MI_B,
 227
 228 MIDI_TONE_KEYCODE_OCTAVES > 1
 229
 230 where x = 1-5:
 231 MI_C_x,
 232 MI_Cs_x,
 233 MI_Db_x = MI_Cs_x,
 234 MI_D_x,
 235 MI_Ds_x,
 236 MI_Eb_x = MI_Ds_x,
 237 MI_E_x,
 238 MI_F_x,
 239 MI_Fs_x,
 240 MI_Gb_x = MI_Fs_x,
 241 MI_G_x,
 242 MI_Gs_x,
 243 MI_Ab_x = MI_Gs_x,
 244 MI_A_x,
 245 MI_As_x,
 246 MI_Bb_x = MI_As_x,
 247 MI_B_x,
 248
 249 MI_OCT_Nx 1-2
 250 MI_OCT_x 0-7
 251 MIDI_OCTAVE_MIN = MI_OCT_N2,
 252 MIDI_OCTAVE_MAX = MI_OCT_7,
 253 MI_OCTD, // octave down
 254 MI_OCTU, // octave up
 255
 256 MI_TRNS_Nx 1-6
 257 MI_TRNS_x 0-6
 258 MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
 259 MIDI_TRANSPOSE_MAX = MI_TRNS_6,
 260 MI_TRNSD, // transpose down
 261 MI_TRNSU, // transpose up
 262
 263 MI_VEL_x 1-10
 264 MIDI_VELOCITY_MIN = MI_VEL_1,
 265 MIDI_VELOCITY_MAX = MI_VEL_9,
 266 MI_VELD, // velocity down
 267 MI_VELU, // velocity up
 268
 269 MI_CHx 1-16
 270 MIDI_CHANNEL_MIN = MI_CH1
 271 MIDI_CHANNEL_MAX = MI_CH16,
 272 MI_CHD, // previous channel
 273 MI_CHU, // next channel
 274
 275 MI_ALLOFF, // all notes off
 276
 277 MI_SUS, // sustain
 278 MI_PORT, // portamento
 279 MI_SOST, // sostenuto
 280 MI_SOFT, // soft pedal
 281 MI_LEG,  // legato
 282
 283 MI_MOD, // modulation
 284 MI_MODSD, // decrease modulation speed
 285 MI_MODSU, // increase modulation speed
 286 #endif // MIDI_ADVANCED
 287
 288 -->