From fe113ebad56e758d635724dc35f2a4e26a6985ee Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 21 Jul 2017 01:02:32 -0400 Subject: start updating audio docs --- docs/modding_your_keyboard.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 44e6e6e72a..30ff4f91af 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -41,7 +41,8 @@ Wherein we bind predefined songs (from [quantum/audio/song_list.h](https://githu 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: ``` -PLAY_NOTE_ARRAY(tone_plover, false, 0); // Signature is: Song name, repeat, rest style +PLAY_NOTE_ARRAY(tone_plover, false, LEGATO); // song name, repeat, rest style +PLAY_SONG(tone_plover); // song name (repeat is false, rest is STACCATO) ``` This is inside one of the macros. So when that macro executes, your keyboard plays that particular chime. -- cgit v1.2.3 From f407f3e8deea433ae4bca61f17d8ed8ed208bb27 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 21 Jul 2017 13:18:36 -0400 Subject: remove unneccesary headers --- docs/modding_your_keyboard.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 30ff4f91af..29b0b3b0fb 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -1,12 +1,23 @@ ## 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 `#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 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. -The audio code lives in [quantum/audio/audio.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/audio.h) and in the other files in the audio directory. It's enabled by default on the Planck [stock keymap](https://github.com/qmk/qmk_firmware/blob/master/keyboards/planck/keymaps/default/keymap.c). Here are the important bits: +If you add this to your `rules.mk`: ``` -#include "audio.h" +AUDIO_ENABLE = yes +``` + +there's a couple different sounds that will automatically be enabled without any other configuration: + + +If you want to implement something custom, you can + +``` +#ifdef AUDIO_ENABLE + #include "audio.h" +#endif ``` Then, lower down the file: @@ -41,14 +52,11 @@ Wherein we bind predefined songs (from [quantum/audio/song_list.h](https://githu 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: ``` -PLAY_NOTE_ARRAY(tone_plover, false, LEGATO); // song name, repeat, rest style -PLAY_SONG(tone_plover); // song name (repeat is false, rest is STACCATO) +PLAY_SONG(tone_plover); // song name ``` This is inside one of the macros. So when that macro executes, your keyboard plays that particular chime. -"Rest style" in the method signature above (the last parameter) specifies if there's a rest (a moment of silence) between the notes. - ## 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. -- cgit v1.2.3 From 9abbbe70890ee0a0c619411c76a2c7b82b1b49d5 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 21 Jul 2017 13:30:57 -0400 Subject: update audio documentation --- docs/modding_your_keyboard.md | 59 +++++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 36 deletions(-) (limited to 'docs/modding_your_keyboard.md') 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 -- cgit v1.2.3 From 6bdf7482b151446c8b4e442de6fadb1395dc4dae Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Sat, 22 Jul 2017 17:12:02 -0400 Subject: update audio/music documentation --- docs/modding_your_keyboard.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index ab40bdf93c..5613bf5253 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -12,6 +12,10 @@ 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) +CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c) +GUITAR_SONG // plays when the guitar music mode is selected (process_music.c) +VIOLIN_SONG // plays when the violin music mode is selected (process_music.c) +MAJOR_SONG // plays when the major music mode is selected (process_music.c) ``` You can override the default songs by doing something like this in your `config.h`: @@ -55,6 +59,11 @@ Keycodes available: * `MU_ON` - Turn music mode on * `MU_OFF` - Turn music mode off * `MU_TOG` - Toggle music mode +* `MU_MOD` - Cycle through the music modes: + * `CHROMATIC_MODE` - Chromatic scale, row changes the octave + * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st) + * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st) + * `MAJOR_MODE` - Major scale In music mode, the following keycodes work differently, and don't pass through: @@ -64,6 +73,12 @@ In music mode, the following keycodes work differently, and don't pass through: * `KC_UP` - speed-up playback * `KC_DOWN` - slow-down playback +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: + + #define MUSIC_MASK keycode != KC_NO + +Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard! + ## MIDI functionalty This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile. -- cgit v1.2.3 From cefc09ae7dd88cd6b92412881888404da1abdfcb Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Mon, 24 Jul 2017 12:44:03 -0400 Subject: adds option for alt pitch standards --- docs/modding_your_keyboard.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/modding_your_keyboard.md') diff --git a/docs/modding_your_keyboard.md b/docs/modding_your_keyboard.md index 5613bf5253..a58fbd52b2 100644 --- a/docs/modding_your_keyboard.md +++ b/docs/modding_your_keyboard.md @@ -79,6 +79,10 @@ 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! +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 This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile. -- cgit v1.2.3