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 Feature on
  65 * `AU_OFF` - Turn Audio Feature off
  66 * `AU_TOG` - Toggle Audio Feature state
  67
  68 !> These keycodes turn all of the audio functionality on and off.  Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely.
  69
  70 ## ARM Audio Volume
  71
  72 For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `DAC_SAMPLE_MAX` in your `config.h`:
  73
  74 ```c
  75 #define DAC_SAMPLE_MAX 65535U
  76 ```
  77
  78 ## Music Mode
  79
  80 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.
  81
  82 Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
  83
  84 Keycodes available:
  85
  86 * `MU_ON` - Turn music mode on
  87 * `MU_OFF` - Turn music mode off
  88 * `MU_TOG` - Toggle music mode
  89 * `MU_MOD` - Cycle through the music modes:
  90   * `CHROMATIC_MODE` - Chromatic scale, row changes the octave
  91   * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
  92   * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
  93   * `MAJOR_MODE` - Major scale
  94
  95 In music mode, the following keycodes work differently, and don't pass through:
  96
  97 * `LCTL` - start a recording
  98 * `LALT` - stop recording/stop playing
  99 * `LGUI` - play recording
 100 * `KC_UP` - speed-up playback
 101 * `KC_DOWN` - slow-down playback
 102
 103 The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
 104
 105     #define PITCH_STANDARD_A 432.0f
 106
 107 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`:
 108
 109     #define NO_MUSIC_MODE
 110
 111 ### Music Mask
 112
 113 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:
 114
 115     #define MUSIC_MASK keycode != KC_NO
 116
 117 Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
 118
 119 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`:
 120
 121     bool music_mask_user(uint16_t keycode) {
 122       switch (keycode) {
 123         case RAISE:
 124         case LOWER:
 125           return false;
 126         default:
 127           return true;
 128       }
 129     }
 130
 131 Things that return false are not part of the mask, and are always processed.
 132
 133 ### Music Map
 134
 135 By default, the Music Mode uses the columns and row to determine the scale for the keys. For a board that uses a rectangular matrix that matches the keyboard layout, this is just fine.  However, for boards that use a more complicated matrix (such as the Planck Rev6, or many split keyboards) this would result in a very skewed experience.
 136
 137 However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural.
 138
 139 To enable this feature, add `#define MUSIC_MAP` to your `config.h` file, and then you will want to add a `uint8_t music_map` to your keyboard's `c` file, or your `keymap.c`.
 140
 141 ```c
 142 const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12(
 143         36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47,
 144         24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35,
 145         12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
 146          0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11
 147 );
 148 ```
 149
 150 You will want to use whichever `LAYOUT` macro that your keyboard uses here.  This maps it to the correct key location.  Start in  the bottom left of the keyboard layout, and  move to the right, and then upwards.  Fill in all the entries until you have a complete matrix.
 151
 152 You can look at the [Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) as an example of how to implement this.
 153
 154 ## Audio Click
 155
 156 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.
 157
 158 * `CK_TOGG` - Toggles the status (will play sound if enabled)
 159 * `CK_ON` - Turns on Audio Click (plays sound)
 160 * `CK_OFF` - Turns off Audio Click (doesn't play sound)
 161 * `CK_RST` - Resets the frequency to the default state (plays sound at default frequency)
 162 * `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency)
 163 * `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency)
 164
 165
 166 The feature is disabled by default, to save space.  To enable it, add this to your `config.h`:
 167
 168     #define AUDIO_CLICKY
 169
 170
 171 You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values:
 172
 173 | Option | Default Value | Description |
 174 |--------|---------------|-------------|
 175 | `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. |
 176 | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
 177 | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
 178 | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. |
 179 | `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. |
 180
 181
 182
 183
 184 ## MIDI Functionality
 185
 186 This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile.
 187
 188
 189 ## Audio Keycodes
 190
 191 |Key             |Aliases  |Description                       |
 192 |----------------|---------|----------------------------------|
 193 |`AU_ON`         |         |Audio mode on                     |
 194 |`AU_OFF`        |         |Audio mode off                    |
 195 |`AU_TOG`        |         |Toggles Audio mode                |
 196 |`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode         |
 197 |`CLICKY_UP`     |`CK_UP`  |Increases frequency of the clicks |
 198 |`CLICKY_DOWN`   |`CK_DOWN`|Decreases frequency of the clicks |
 199 |`CLICKY_RESET`  |`CK_RST` |Resets frequency to default       |
 200 |`MU_ON`         |         |Turns on Music Mode               |
 201 |`MU_OFF`        |         |Turns off Music Mode              |
 202 |`MU_TOG`        |         |Toggles Music Mode                |
 203 |`MU_MOD`        |         |Cycles through the music modes    |
 204
 205 <!-- FIXME: this formatting needs work
 206
 207 ## Audio
 208
 209 ```c
 210 #ifdef AUDIO_ENABLE
 211     AU_ON,
 212     AU_OFF,
 213     AU_TOG,
 214
 215     #ifdef FAUXCLICKY_ENABLE
 216         FC_ON,
 217         FC_OFF,
 218         FC_TOG,
 219     #endif
 220
 221     // Music mode on/off/toggle
 222     MU_ON,
 223     MU_OFF,
 224     MU_TOG,
 225
 226     // Music voice iterate
 227     MUV_IN,
 228     MUV_DE,
 229 #endif
 230 ```
 231
 232 ### Midi
 233
 234 #if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
 235     MI_ON,  // send midi notes when music mode is enabled
 236     MI_OFF, // don't send midi notes when music mode is enabled
 237 #endif
 238
 239 MIDI_TONE_MIN,
 240 MIDI_TONE_MAX
 241
 242 MI_C = MIDI_TONE_MIN,
 243 MI_Cs,
 244 MI_Db = MI_Cs,
 245 MI_D,
 246 MI_Ds,
 247 MI_Eb = MI_Ds,
 248 MI_E,
 249 MI_F,
 250 MI_Fs,
 251 MI_Gb = MI_Fs,
 252 MI_G,
 253 MI_Gs,
 254 MI_Ab = MI_Gs,
 255 MI_A,
 256 MI_As,
 257 MI_Bb = MI_As,
 258 MI_B,
 259
 260 MIDI_TONE_KEYCODE_OCTAVES > 1
 261
 262 where x = 1-5:
 263 MI_C_x,
 264 MI_Cs_x,
 265 MI_Db_x = MI_Cs_x,
 266 MI_D_x,
 267 MI_Ds_x,
 268 MI_Eb_x = MI_Ds_x,
 269 MI_E_x,
 270 MI_F_x,
 271 MI_Fs_x,
 272 MI_Gb_x = MI_Fs_x,
 273 MI_G_x,
 274 MI_Gs_x,
 275 MI_Ab_x = MI_Gs_x,
 276 MI_A_x,
 277 MI_As_x,
 278 MI_Bb_x = MI_As_x,
 279 MI_B_x,
 280
 281 MI_OCT_Nx 1-2
 282 MI_OCT_x 0-7
 283 MIDI_OCTAVE_MIN = MI_OCT_N2,
 284 MIDI_OCTAVE_MAX = MI_OCT_7,
 285 MI_OCTD, // octave down
 286 MI_OCTU, // octave up
 287
 288 MI_TRNS_Nx 1-6
 289 MI_TRNS_x 0-6
 290 MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
 291 MIDI_TRANSPOSE_MAX = MI_TRNS_6,
 292 MI_TRNSD, // transpose down
 293 MI_TRNSU, // transpose up
 294
 295 MI_VEL_x 1-10
 296 MIDI_VELOCITY_MIN = MI_VEL_1,
 297 MIDI_VELOCITY_MAX = MI_VEL_9,
 298 MI_VELD, // velocity down
 299 MI_VELU, // velocity up
 300
 301 MI_CHx 1-16
 302 MIDI_CHANNEL_MIN = MI_CH1
 303 MIDI_CHANNEL_MAX = MI_CH16,
 304 MI_CHD, // previous channel
 305 MI_CHU, // next channel
 306
 307 MI_ALLOFF, // all notes off
 308
 309 MI_SUS, // sustain
 310 MI_PORT, // portamento
 311 MI_SOST, // sostenuto
 312 MI_SOFT, // soft pedal
 313 MI_LEG,  // legato
 314
 315 MI_MOD, // modulation
 316 MI_MODSD, // decrease modulation speed
 317 MI_MODSU, // increase modulation speed
 318 #endif // MIDI_ADVANCED
 319
 320 -->