summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJack Humbert <jack.humb@gmail.com>2017-07-21 13:30:57 -0400
committerJack Humbert <jack.humb@gmail.com>2017-07-23 14:59:29 -0400
commit9abbbe70890ee0a0c619411c76a2c7b82b1b49d5 (patch)
treef9c304b7eca97a91b271c3fd4be3ea0e41884b9f
parentf407f3e8deea433ae4bca61f17d8ed8ed208bb27 (diff)
update audio documentation
-rw-r--r--docs/modding_your_keyboard.md59
1 files changed, 23 insertions, 36 deletions
diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md
index 29b0b3b0fb..ab40bdf93c 100644
--- a/docs/modding_your_keyboard.md
+++ b/docs/modding_your_keyboard.md
@@ -1,61 +1,48 @@
## Audio output from a speaker
-Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any 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 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.
-If you add this to your `rules.mk`:
+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:
```
-AUDIO_ENABLE = yes
+STARTUP_SONG // plays when the keyboard starts up (audio.c)
+GOODBYE_SONG // plays when you press the RESET key (quantum.c)
+AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
+AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
+MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
+MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
```
-there's a couple different sounds that will automatically be enabled without any other configuration:
+You can override the default songs by doing something like this in your `config.h`:
-
-If you want to implement something custom, you can
-
-```
+```c
#ifdef AUDIO_ENABLE
- #include "audio.h"
+ #define STARTUP_SONG SONG(STARTUP_SOUND)
#endif
```
-Then, lower down the file:
-
-```
-float tone_startup[][2] = {
- ED_NOTE(_E7 ),
- E__NOTE(_CS7),
- E__NOTE(_E6 ),
- E__NOTE(_A6 ),
- M__NOTE(_CS7, 20)
-};
-```
-
-This is how you write a song. Each of these lines is a note, so we have a little ditty composed of five notes here.
+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).
-Then, we have this chunk:
+To play a custom sound at a particular time, you can define a song like this (near the top of the file):
+```c
+float my_song[][2] = SONG(QWERTY_SOUND);
```
-float tone_qwerty[][2] = SONG(QWERTY_SOUND);
-float tone_dvorak[][2] = SONG(DVORAK_SOUND);
-float tone_colemak[][2] = SONG(COLEMAK_SOUND);
-float tone_plover[][2] = SONG(PLOVER_SOUND);
-float tone_plover_gb[][2] = SONG(PLOVER_GOODBYE_SOUND);
-float music_scale[][2] = SONG(MUSIC_SCALE_SOUND);
-float goodbye[][2] = SONG(GOODBYE_SOUND);
-```
+And then play your song like this:
-Wherein we bind predefined songs (from [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h)) into named variables. This is one optimization that helps save on memory: These songs only take up memory when you reference them in your keymap, because they're essentially all preprocessor directives.
+```c
+PLAY_SONG(my_song);
+```
-So now you have something called `tone_plover` for example. How do you make it play the Plover tune, then? If you look further down the keymap, you'll see this:
+Alternatively, you can play it in a loop like this:
-```
-PLAY_SONG(tone_plover); // song name
+```c
+PLAY_LOOP(my_song);
```
-This is inside one of the macros. So when that macro executes, your keyboard plays that particular chime.
+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