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.
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:
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:
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)
32 You can override the default songs by doing something like this in your `config.h`:
36 #define STARTUP_SONG SONG(STARTUP_SOUND)
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).
42 To play a custom sound at a particular time, you can define a song like this (near the top of the file):
45 float my_song[][2] = SONG(QWERTY_SOUND);
48 And then play your song like this:
54 Alternatively, you can play it in a loop like this:
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.
62 The available keycodes for audio are:
64 * `AU_ON` - Turn audio mode on
65 * `AU_OFF` - Turn audio mode off
66 * `AU_TOG` - Toggle audio mode
70 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 #define DAC_SAMPLE_MAX 65535U
78 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.
80 Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
84 * `MU_ON` - Turn music mode on
85 * `MU_OFF` - Turn music mode off
86 * `MU_TOG` - Toggle music mode
87 * `MU_MOD` - Cycle through the music modes:
88 * `CHROMATIC_MODE` - Chromatic scale, row changes the octave
89 * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
90 * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
91 * `MAJOR_MODE` - Major scale
93 In music mode, the following keycodes work differently, and don't pass through:
95 * `LCTL` - start a recording
96 * `LALT` - stop recording/stop playing
97 * `LGUI` - play recording
98 * `KC_UP` - speed-up playback
99 * `KC_DOWN` - slow-down playback
101 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:
103 #define MUSIC_MASK keycode != KC_NO
105 Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
107 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`:
109 bool music_mask_user(uint16_t keycode) {
119 Things that return false are not part of the mask, and are always processed.
121 The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
123 #define PITCH_STANDARD_A 432.0f
125 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`:
127 #define NO_MUSIC_MODE
131 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.
133 * `CK_TOGG` - Toggles the status (will play sound if enabled)
134 * `CK_ON` - Turns on Audio Click (plays sound)
135 * `CK_OFF` - Turns off Audio Click (doesn't play sound)
136 * `CK_RST` - Resets the frequency to the default state (plays sound at default frequency)
137 * `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency)
138 * `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency)
141 The feature is disabled by default, to save space. To enable it, add this to your `config.h`:
146 You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values:
148 | Option | Default Value | Description |
149 |--------|---------------|-------------|
150 | `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. |
151 | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
152 | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
153 | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. |
154 | `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. |
159 ## MIDI Functionality
161 This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
166 |Key |Aliases |Description |
167 |----------------|---------|----------------------------------|
168 |`AU_ON` | |Audio mode on |
169 |`AU_OFF` | |Audio mode off |
170 |`AU_TOG` | |Toggles Audio mode |
171 |`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode |
172 |`CLICKY_UP` |`CK_UP` |Increases frequency of the clicks |
173 |`CLICKY_DOWN` |`CK_DOWN`|Decreases frequency of the clicks |
174 |`CLICKY_RESET` |`CK_RST` |Resets frequency to default |
175 |`MU_ON` | |Turns on Music Mode |
176 |`MU_OFF` | |Turns off Music Mode |
177 |`MU_TOG` | |Toggles Music Mode |
178 |`MU_MOD` | |Cycles through the music modes |
180 <!-- FIXME: this formatting needs work
190 #ifdef FAUXCLICKY_ENABLE
196 // Music mode on/off/toggle
201 // Music voice iterate
209 #if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
210 MI_ON, // send midi notes when music mode is enabled
211 MI_OFF, // don't send midi notes when music mode is enabled
217 MI_C = MIDI_TONE_MIN,
235 MIDI_TONE_KEYCODE_OCTAVES > 1
258 MIDI_OCTAVE_MIN = MI_OCT_N2,
259 MIDI_OCTAVE_MAX = MI_OCT_7,
260 MI_OCTD, // octave down
261 MI_OCTU, // octave up
265 MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
266 MIDI_TRANSPOSE_MAX = MI_TRNS_6,
267 MI_TRNSD, // transpose down
268 MI_TRNSU, // transpose up
271 MIDI_VELOCITY_MIN = MI_VEL_1,
272 MIDI_VELOCITY_MAX = MI_VEL_9,
273 MI_VELD, // velocity down
274 MI_VELU, // velocity up
277 MIDI_CHANNEL_MIN = MI_CH1
278 MIDI_CHANNEL_MAX = MI_CH16,
279 MI_CHD, // previous channel
280 MI_CHU, // next channel
282 MI_ALLOFF, // all notes off
285 MI_PORT, // portamento
286 MI_SOST, // sostenuto
287 MI_SOFT, // soft pedal
290 MI_MOD, // modulation
291 MI_MODSD, // decrease modulation speed
292 MI_MODSU, // increase modulation speed
293 #endif // MIDI_ADVANCED