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