qmk

QMK Firmware
git clone git://git.z3bra.org/qmk.git
Log | Files | Refs | Submodules | LICENSE

feature_audio.md (11742B)


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