audio.md (22035B)
1 # Audio 2 3 Your keyboard can make sounds! If you've got a spare pin 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 To activate this feature, add `AUDIO_ENABLE = yes` to your `rules.mk`. 6 7 ## AVR based boards 8 On Atmega32U4 based boards, up to two simultaneous tones can be rendered. 9 With one speaker connected to a PWM capable pin on PORTC driven by timer 3 and the other on one of the PWM pins on PORTB driven by timer 1. 10 11 The following pins can be configured as audio outputs in `config.h` - for one speaker set either one out of: 12 13 * `#define AUDIO_PIN C4` 14 * `#define AUDIO_PIN C5` 15 * `#define AUDIO_PIN C6` 16 * `#define AUDIO_PIN B5` 17 * `#define AUDIO_PIN B6` 18 * `#define AUDIO_PIN B7` 19 20 and *optionally*, for a second speaker, one of: 21 * `#define AUDIO_PIN_ALT B5` 22 * `#define AUDIO_PIN_ALT B6` 23 * `#define AUDIO_PIN_ALT B7` 24 25 ### Wiring 26 per speaker is - for example with a piezo buzzer - the black lead to Ground, and the red lead connected to the selected AUDIO_PIN for the primary; and similarly with AUDIO_PIN_ALT for the secondary. 27 28 29 ## ARM based boards 30 for more technical details, see the notes on [Audio driver](../drivers/audio). 31 32 <!-- because I'm not sure where to fit this in: https://waveeditonline.com/ --> 33 ### DAC (basic) 34 Most STM32 MCUs have DAC peripherals, with a notable exception of the STM32F1xx series. Generally, the DAC peripheral drives pins A4 or A5. To enable DAC-based audio output on STM32 devices, add `AUDIO_DRIVER = dac_basic` to `rules.mk` and set in `config.h` either: 35 36 `#define AUDIO_PIN A4` or `#define AUDIO_PIN A5` 37 38 the other DAC channel can optionally be used with a secondary speaker, just set: 39 40 `#define AUDIO_PIN_ALT A4` or `#define AUDIO_PIN_ALT A5` 41 42 Do note though that the dac_basic driver is only capable of reproducing one tone per speaker/channel at a time, for more tones simultaneously, try the dac_additive driver. 43 44 #### Wiring: 45 for two piezos, for example configured as `AUDIO_PIN A4` and `AUDIO_PIN_ALT A5` would be: red lead to A4 and black to Ground, and similarly with the second one: A5 = red, and Ground = black 46 47 another alternative is to drive *one* piezo with both DAC pins - for an extra "push". 48 wiring red to A4 and black to A5 (or the other way round) and add `#define AUDIO_PIN_ALT_AS_NEGATIVE` to `config.h` 49 50 ##### Proton-C Example: 51 The Proton-C comes (optionally) with one 'builtin' piezo, which is wired to A4+A5. 52 For this board `config.h` would include these defines: 53 54 ```c 55 #define AUDIO_PIN A5 56 #define AUDIO_PIN_ALT A4 57 #define AUDIO_PIN_ALT_AS_NEGATIVE 58 ``` 59 60 ### DAC (additive) 61 Another option, besides dac_basic (which produces sound through a square-wave), is to use the DAC to do additive wave synthesis. 62 With a number of predefined wave-forms or by providing your own implementation to generate samples on the fly. 63 To use this feature set `AUDIO_DRIVER = dac_additive` in your `rules.mk`, and select in `config.h` EITHER `#define AUDIO_PIN A4` or `#define AUDIO_PIN A5`. 64 65 The used waveform *defaults* to sine, but others can be selected by adding one of the following defines to `config.h`: 66 67 * `#define AUDIO_DAC_SAMPLE_WAVEFORM_SINE` 68 * `#define AUDIO_DAC_SAMPLE_WAVEFORM_TRIANGLE` 69 * `#define AUDIO_DAC_SAMPLE_WAVEFORM_TRAPEZOID` 70 * `#define AUDIO_DAC_SAMPLE_WAVEFORM_SQUARE` 71 72 Should you rather choose to generate and use your own sample-table with the DAC unit, implement `uint16_t dac_value_generate(void)` with your keyboard - for an example implementation see keyboards/planck/keymaps/synth_sample or keyboards/planck/keymaps/synth_wavetable 73 74 75 ### PWM (software) 76 If the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative. 77 Note that there is currently only one speaker/pin supported. 78 79 To use this feature, set `AUDIO_DRIVER = pwm_software` in `rules.mk` and set `#define AUDIO_PIN C13` (can be any pin) in `config.h` to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software. 80 81 #### Wiring 82 The usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground. 83 84 OR if you can chose to drive one piezo with two pins, for example `#define AUDIO_PIN B1`, `#define AUDIO_PIN_ALT B2` in `config.h`, with `#define AUDIO_PIN_ALT_AS_NEGATIVE` - then the red lead could go to B1, the black to B2. 85 86 ### PWM (hardware) 87 STM32F1xx have to fall back to using PWM, but can do so in hardware; but again on currently only one speaker/pin. 88 89 `AUDIO_DRIVER = pwm_hardware` in `rules.mk`, and in `config.h`: 90 `#define AUDIO_PIN A8` 91 `#define AUDIO_PWM_DRIVER PWMD1` 92 `#define AUDIO_PWM_CHANNEL 1` 93 (as well as `#define AUDIO_PWM_PAL_MODE 42` if you are on STM32F2 or larger) 94 which will use Timer 1 to directly drive pin PA8 through the PWM hardware (TIM1_CH1 = PA8). 95 Should you want to use the pwm-hardware on another pin and timer - be ready to dig into the STM32 data-sheet to pick the right TIMx_CHy and pin-alternate function. 96 97 98 ## Tone Multiplexing 99 Since most drivers can only render one tone per speaker at a time (with the one exception: arm dac-additive) there also exists a "workaround-feature" that does time-slicing/multiplexing - which does what the name implies: cycle through a set of active tones (e.g. when playing chords in Music Mode) at a given rate, and put one tone at a time out through the one/few speakers that are available. 100 101 To enable this feature, and configure a starting-rate, add the following defines to `config.h`: 102 ```c 103 #define AUDIO_ENABLE_TONE_MULTIPLEXING 104 #define AUDIO_TONE_MULTIPLEXING_RATE_DEFAULT 10 105 ``` 106 107 The audio core offers interface functions to get/set/change the tone multiplexing rate from within `keymap.c`. 108 109 110 ## Songs 111 There's a couple of different sounds that will automatically be enabled without any other configuration: 112 ``` 113 STARTUP_SONG // plays when the keyboard starts up (audio.c) 114 GOODBYE_SONG // plays when you press the QK_BOOT key (quantum.c) 115 AG_NORM_SONG // plays when you press AG_NORM (quantum.c) 116 AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c) 117 CG_NORM_SONG // plays when you press CG_NORM (quantum.c) 118 CG_SWAP_SONG // plays when you press CG_SWAP (quantum.c) 119 MUSIC_ON_SONG // plays when music mode is activated (process_music.c) 120 MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c) 121 CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c) 122 GUITAR_SONG // plays when the guitar music mode is selected (process_music.c) 123 VIOLIN_SONG // plays when the violin music mode is selected (process_music.c) 124 MAJOR_SONG // plays when the major music mode is selected (process_music.c) 125 ``` 126 127 You can override the default songs by doing something like this in your `config.h`: 128 129 ```c 130 #ifdef AUDIO_ENABLE 131 # define STARTUP_SONG SONG(STARTUP_SOUND) 132 #endif 133 ``` 134 135 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). 136 137 Additionally, if you with to maintain your own list of songs (such as ones that may be copyrighted) and not have them added to the repo, you can create a `user_song_list.h` file and place it in your keymap (or userspace) folder. This file will be automatically included, it just needs to exist. 138 139 To play a custom sound at a particular time, you can define a song like this (near the top of the file): 140 141 ```c 142 float my_song[][2] = SONG(QWERTY_SOUND); 143 ``` 144 145 And then play your song like this: 146 147 ```c 148 PLAY_SONG(my_song); 149 ``` 150 151 Alternatively, you can play it in a loop like this: 152 153 ```c 154 PLAY_LOOP(my_song); 155 ``` 156 157 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. 158 159 The available keycodes for audio are: 160 161 |Key |Aliases |Description | 162 |-------------------------|---------|-------------------------------------------| 163 |`QK_AUDIO_ON` |`AU_ON` |Turns on Audio Feature | 164 |`QK_AUDIO_OFF` |`AU_OFF` |Turns off Audio Feature | 165 |`QK_AUDIO_TOGGLE` |`AU_TOGG`|Toggles Audio state | 166 167 ::: warning 168 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. 169 ::: 170 171 ## Audio Config 172 173 | Settings | Default | Description | 174 |----------------------------------|----------------------|---------------------------------------------------------------------------------------------| 175 |`AUDIO_PIN` | *Not defined* |Configures the pin that the speaker is connected to. | 176 |`AUDIO_PIN_ALT` | *Not defined* |Configures the pin for a second speaker or second pin connected to one speaker. | 177 |`AUDIO_PIN_ALT_AS_NEGATIVE` | *Not defined* |Enables support for one speaker connected to two pins. | 178 |`AUDIO_INIT_DELAY` | *Not defined* |Enables delay during startup song to accommodate for USB startup issues. | 179 |`AUDIO_ENABLE_TONE_MULTIPLEXING` | *Not defined* |Enables time splicing/multiplexing to create multiple tones simultaneously. | 180 |`AUDIO_POWER_CONTROL_PIN` | *Not defined* |Enables power control code to enable or cut off power to speaker (such as with PAM8302 amp). | 181 |`AUDIO_POWER_CONTROL_PIN_ON_STATE`| `1` |The state of the audio power control pin when audio is "on" - `1` for high, `0` for low. | 182 |`STARTUP_SONG` | `STARTUP_SOUND` |Plays when the keyboard starts up (audio.c) | 183 |`GOODBYE_SONG` | `GOODBYE_SOUND` |Plays when you press the QK_BOOT key (quantum.c) | 184 |`AG_NORM_SONG` | `AG_NORM_SOUND` |Plays when you press AG_NORM (process_magic.c) | 185 |`AG_SWAP_SONG` | `AG_SWAP_SOUND` |Plays when you press AG_SWAP (process_magic.c) | 186 |`CG_NORM_SONG` | `AG_NORM_SOUND` |Plays when you press CG_NORM (process_magic.c) | 187 |`CG_SWAP_SONG` | `AG_SWAP_SOUND` |Plays when you press CG_SWAP (process_magic.c) | 188 |`MUSIC_ON_SONG` | `MUSIC_ON_SOUND` |Plays when music mode is activated (process_music.c) | 189 |`MUSIC_OFF_SONG` | `MUSIC_OFF_SOUND` |Plays when music mode is deactivated (process_music.c) | 190 |`MIDI_ON_SONG` | `MUSIC_ON_SOUND` |Plays when midi mode is activated (process_music.c) | 191 |`MIDI_OFF_SONG` | `MUSIC_OFF_SOUND` |Plays when midi mode is deactivated (process_music.c) | 192 |`CHROMATIC_SONG` | `CHROMATIC_SOUND` |Plays when the chromatic music mode is selected (process_music.c) | 193 |`GUITAR_SONG` | `GUITAR_SOUND` |Plays when the guitar music mode is selected (process_music.c) | 194 |`VIOLIN_SONG` | `VIOLIN_SOUND` |Plays when the violin music mode is selected (process_music.c) | 195 |`MAJOR_SONG` | `MAJOR_SOUND` |Plays when the major music mode is selected (process_music.c) | 196 |`DEFAULT_LAYER_SONGS` | *Not defined* |Plays song when switched default layers with [`set_single_persistent_default_layer(layer)`](../ref_functions#setting-the-persistent-default-layer)(quantum.c). | 197 |`SENDSTRING_BELL` | *Not defined* |Plays chime when the "enter" ("\a") character is sent (send_string.c) | 198 199 ## Tempo 200 the 'speed' at which SONGs are played is dictated by the set Tempo, which is measured in beats-per-minute. Note lengths are defined relative to that. 201 The initial/default tempo is set to 120 bpm, but can be configured by setting `TEMPO_DEFAULT` in `config.c`. 202 There is also a set of functions to modify the tempo from within the user/keymap code: 203 ```c 204 void audio_set_tempo(uint8_t tempo); 205 void audio_increase_tempo(uint8_t tempo_change); 206 void audio_decrease_tempo(uint8_t tempo_change); 207 ``` 208 209 ## ARM Audio Volume 210 211 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 `AUDIO_DAC_SAMPLE_MAX` in your `config.h`: 212 213 ```c 214 #define AUDIO_DAC_SAMPLE_MAX 4095U 215 ``` 216 the DAC usually runs in 12Bit mode, hence a volume of 100% = 4095U 217 218 Note: this only adjusts the volume aka 'works' if you stick to WAVEFORM_SQUARE, since its samples are generated on the fly - any other waveform uses a hardcoded/precomputed sample-buffer. 219 220 ## Voices 221 Aka "audio effects", different ones can be enabled by setting in `config.h` these defines: 222 `#define AUDIO_VOICES` to enable the feature, and `#define AUDIO_VOICE_DEFAULT something` to select a specific effect 223 for details see quantum/audio/voices.h and .c 224 225 Keycodes available: 226 227 |Key |Aliases |Description | 228 |-------------------------|---------|-------------------------------------------| 229 |`QK_AUDIO_VOICE_NEXT` |`AU_NEXT`|Cycles through the audio voices | 230 |`QK_AUDIO_VOICE_PREVIOUS`|`AU_PREV`|Cycles through the audio voices in reverse | 231 232 ## Music Mode 233 234 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. 235 236 Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things. 237 238 Keycodes available: 239 240 |Key |Aliases |Description | 241 |-------------------------|---------|-------------------------------------------| 242 |`QK_MUSIC_ON` |`MU_ON` |Turns on Music Mode | 243 |`QK_MUSIC_OFF` |`MU_OFF` |Turns off Music Mode | 244 |`QK_MUSIC_TOGGLE` |`MU_TOGG`|Toggles Music Mode | 245 |`QK_MUSIC_MODE_NEXT` |`MU_NEXT`|Cycles through the music modes | 246 247 Available Modes: 248 * `CHROMATIC_MODE` - Chromatic scale, row changes the octave 249 * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st) 250 * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st) 251 * `MAJOR_MODE` - Major scale 252 253 In music mode, the following keycodes work differently, and don't pass through: 254 255 * `LCTL` - start a recording 256 * `LALT` - stop recording/stop playing 257 * `LGUI` - play recording 258 * `KC_UP` - speed-up playback 259 * `KC_DOWN` - slow-down playback 260 261 The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`: 262 263 ```c 264 #define PITCH_STANDARD_A 432.0f 265 ``` 266 267 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`: 268 269 ```c 270 #define NO_MUSIC_MODE 271 ``` 272 273 ### Music Mask 274 275 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: 276 277 ```c 278 #define MUSIC_MASK keycode != KC_NO 279 ``` 280 281 Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard! 282 283 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`: 284 285 ```c 286 bool music_mask_user(uint16_t keycode) { 287 switch (keycode) { 288 case RAISE: 289 case LOWER: 290 return false; 291 default: 292 return true; 293 } 294 } 295 ``` 296 297 Things that return false are not part of the mask, and are always processed. 298 299 ### Music Map 300 301 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. 302 303 However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural. 304 305 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`. 306 307 ```c 308 const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12( 309 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 310 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 311 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 312 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 313 ); 314 ``` 315 316 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. 317 318 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. 319 320 ## Audio Click 321 322 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. 323 324 Keycodes available: 325 326 |Key |Aliases |Description | 327 |-------------------------|---------|-------------------------------------------| 328 |`QK_AUDIO_CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode | 329 |`QK_AUDIO_CLICKY_ON` |`CK_ON` |Turns on Audio clicky mode | 330 |`QK_AUDIO_CLICKY_OFF` |`CK_OFF` |Turns on Audio clicky mode | 331 |`QK_AUDIO_CLICKY_UP` |`CK_UP` |Increases frequency of the clicks | 332 |`QK_AUDIO_CLICKY_DOWN` |`CK_DOWN`|Decreases frequency of the clicks | 333 |`QK_AUDIO_CLICKY_RESET` |`CK_RST` |Resets frequency to default | 334 335 The feature is disabled by default, to save space. To enable it, add this to your `config.h`: 336 337 ```c 338 #define AUDIO_CLICKY 339 ``` 340 341 You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: 342 343 | Option | Default Value | Description | 344 |--------|---------------|-------------| 345 | `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. | 346 | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). | 347 | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the highest frequency. Too high may result in coworkers attacking you. | 348 | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. This is a multiplicative factor. The default steps the frequency up/down by a musical minor third. | 349 | `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. | 350 | `AUDIO_CLICKY_DELAY_DURATION` | 1 | An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see `quantum/audio/musical_notes.h` for implementation details). The main clicky effect will be delayed by this duration. Adjusting this to values around 6-12 will help compensate for loud switches. | 351 352 ## MIDI Functionality 353 354 See [MIDI](midi) 355 356 ## Audio Keycodes 357 358 |Key |Aliases |Description | 359 |-------------------------|---------|-------------------------------------------| 360 |`QK_AUDIO_ON` |`AU_ON` |Turns on Audio Feature | 361 |`QK_AUDIO_OFF` |`AU_OFF` |Turns off Audio Feature | 362 |`QK_AUDIO_TOGGLE` |`AU_TOGG`|Toggles Audio state | 363 |`QK_AUDIO_CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode | 364 |`QK_AUDIO_CLICKY_ON` |`CK_ON` |Turns on Audio clicky mode | 365 |`QK_AUDIO_CLICKY_OFF` |`CK_OFF` |Turns on Audio clicky mode | 366 |`QK_AUDIO_CLICKY_UP` |`CK_UP` |Increases frequency of the clicks | 367 |`QK_AUDIO_CLICKY_DOWN` |`CK_DOWN`|Decreases frequency of the clicks | 368 |`QK_AUDIO_CLICKY_RESET` |`CK_RST` |Resets frequency to default | 369 |`QK_MUSIC_ON` |`MU_ON` |Turns on Music Mode | 370 |`QK_MUSIC_OFF` |`MU_OFF` |Turns off Music Mode | 371 |`QK_MUSIC_TOGGLE` |`MU_TOGG`|Toggles Music Mode | 372 |`QK_MUSIC_MODE_NEXT` |`MU_NEXT`|Cycles through the music modes | 373 |`QK_AUDIO_VOICE_NEXT` |`AU_NEXT`|Cycles through the audio voices | 374 |`QK_AUDIO_VOICE_PREVIOUS`|`AU_PREV`|Cycles through the audio voices in reverse |