X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=docs%2Ffeature_audio.md;h=38861e8c14dffafb019a95ea1bc06e81a90117df;hb=e3621c162c32dd12ede78f6e2936724fc1dabcf1;hp=c142ff69c25ab2938dcc8f7bc1bf3f2960320fd6;hpb=9d1a08e38ac9937cff4e61abfd0acc26ad5fdf4a;p=qmk_firmware.git diff --git a/docs/feature_audio.md b/docs/feature_audio.md index c142ff69c..38861e8c1 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -1,6 +1,18 @@ # Audio -Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), 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. +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. + +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: + +Timer 1: +`#define B5_AUDIO` +`#define B6_AUDIO` +`#define B7_AUDIO` + +Timer 3: +`#define C4_AUDIO` +`#define C5_AUDIO` +`#define C6_AUDIO` 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: @@ -47,9 +59,25 @@ PLAY_LOOP(my_song); 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. -## Music mode +The available keycodes for audio are: + +* `AU_ON` - Turn Audio Feature on +* `AU_OFF` - Turn Audio Feature off +* `AU_TOG` - Toggle Audio Feature state + +!> 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. + +## ARM Audio Volume + +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`: + +```c +#define DAC_SAMPLE_MAX 65535U +``` -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. +## Music Mode + +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. Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things. @@ -78,13 +106,78 @@ By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less th Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard! +For a more advanced way to control which keycodes should still be processed, you can use `music_mask_kb(keycode)` in `.c` and `music_mask_user(keycode)` in your `keymap.c`: + + bool music_mask_user(uint16_t keycode) { + switch (keycode) { + case RAISE: + case LOWER: + return false; + default: + return true; + } + } + +Things that return false are not part of the mask, and are always processed. + The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`: #define PITCH_STANDARD_A 432.0f -## MIDI functionalty +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`: + + #define NO_MUSIC_MODE + +## Audio Click + +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. + +* `CK_TOGG` - Toggles the status (will play sound if enabled) +* `CK_ON` - Turns on Audio Click (plays sound) +* `CK_OFF` - Turns off Audio Click (doesn't play sound) +* `CK_RST` - Resets the frequency to the default state (plays sound at default frequency) +* `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency) +* `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency) + + +The feature is disabled by default, to save space. To enable it, add this to your `config.h`: + + #define AUDIO_CLICKY + + +You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: + +| Option | Default Value | Description | +|--------|---------------|-------------| +| `AUDIO_CLICKY_FREQ_DEFAULT` | 440.0f | Sets the default/starting audio frequency for the clicky sounds. | +| `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). | +| `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. | +| `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. | +| `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. | + + + + +## MIDI Functionality + +This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile. + + +## Audio Keycodes -This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile. +|Key |Aliases |Description | +|----------------|---------|----------------------------------| +|`AU_ON` | |Audio mode on | +|`AU_OFF` | |Audio mode off | +|`AU_TOG` | |Toggles Audio mode | +|`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode | +|`CLICKY_UP` |`CK_UP` |Increases frequency of the clicks | +|`CLICKY_DOWN` |`CK_DOWN`|Decreases frequency of the clicks | +|`CLICKY_RESET` |`CK_RST` |Resets frequency to default | +|`MU_ON` | |Turns on Music Mode | +|`MU_OFF` | |Turns off Music Mode | +|`MU_TOG` | |Toggles Music Mode | +|`MU_MOD` | |Cycles through the music modes |