<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_PIN_ALT_AS_NEGATIVE</span></span></code></pre></div><h3id="dac-additive"tabindex="-1">DAC (additive) <aclass="header-anchor"href="#dac-additive"aria-label="Permalink to "DAC (additive)""></a></h3><p>Another option, besides dac_basic (which produces sound through a square-wave), is to use the DAC to do additive wave synthesis. With a number of predefined wave-forms or by providing your own implementation to generate samples on the fly. To use this feature set <code>AUDIO_DRIVER = dac_additive</code> in your <code>rules.mk</code>, and select in <code>config.h</code> EITHER <code>#define AUDIO_PIN A4</code> or <code>#define AUDIO_PIN A5</code>.</p><p>The used waveform <em>defaults</em> to sine, but others can be selected by adding one of the following defines to <code>config.h</code>:</p><ul><li><code>#define AUDIO_DAC_SAMPLE_WAVEFORM_SINE</code></li><li><code>#define AUDIO_DAC_SAMPLE_WAVEFORM_TRIANGLE</code></li><li><code>#define AUDIO_DAC_SAMPLE_WAVEFORM_TRAPEZOID</code></li><li><code>#define AUDIO_DAC_SAMPLE_WAVEFORM_SQUARE</code></li></ul><p>Should you rather choose to generate and use your own sample-table with the DAC unit, implement <code>uint16_t dac_value_generate(void)</code> with your keyboard - for an example implementation see keyboards/planck/keymaps/synth_sample or keyboards/planck/keymaps/synth_wavetable</p><h3id="pwm-software"tabindex="-1">PWM (software) <aclass="header-anchor"href="#pwm-software"aria-label="Permalink to "PWM (software)""></a></h3><p>if the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative. Note that there is currently only one speaker/pin supported.</p><p>set in <code>rules.mk</code>:</p><p><code>AUDIO_DRIVER = pwm_software</code> and in <code>config.h</code>: <code>#define AUDIO_PIN C13</code> (can be any pin) to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software.</p><h4id="wiring-2"tabindex="-1">Wiring <aclass="header-anchor"href="#wiring-2"aria-label="Permalink to "Wiring""></a></h4><p>the usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground.</p><p>OR if you can chose to drive one piezo with two pins, for example <code>#define AUDIO_PIN B1</code>, <code>#define AUDIO_PIN_ALT B2</code> in <code>config.h</code>, with <code>#define AUDIO_PIN_ALT_AS_NEGATIVE</code> - then the red lead could go to B1, the black to B2.</p><h3id="pwm-hardware"tabindex="-1">PWM (hardware) <aclass="header-anchor"href="#pwm-hardware"aria-label="Permalink to "PWM (hardware)""></a></h3><p>STM32F1xx have to fall back to using PWM, but can do so in hardware; but again on currently only one speaker/pin.</p><p><code>AUDIO_DRIVER = pwm_hardware</code> in <code>rules.mk</code>, and in <code>config.h</code>: <code>#define AUDIO_PIN A8</code><code>#define AUDIO_PWM_DRIVER PWMD1</code><code>#define AUDIO_PWM_CHANNEL 1</code> (as well as <code>#define AUDIO_PWM_PAL_MODE 42</code> if you are on STM32F2 or larger) which will use Timer 1 to directly drive pin PA8 through the PWM hardware (TIM1_CH1 = PA8). Should you want to use the pwm-hardware on another pin and timer - be ready to dig into the STM32 data-sheet to pick the right TIMx_CHy and pin-alternate function.</p><h2id="tone-multiplexing"tabindex="-1">Tone Multiplexing <aclass="header-anchor"href="#tone-multiplexing"aria-label="Permalink to "Tone Multiplexing""></a></h2><p>Since most drivers can only render one tone per speaker at a time (with the one exception: arm dac-additive) there also exists a "workaround-feature" that does time-slicing/multiplexing - which does what the name implies: cycle through a set of active tones (e.g. when playing chords in Music Mode) at a given rate, and put one tone at a time out through the one/few speakers that are available.</p><p>To enable this fe
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_TONE_MULTIPLEXING_RATE_DEFAULT</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 10</span></span></code></pre></div><p>The audio core offers interface functions to get/set/change the tone multiplexing rate from within <code>keymap.c</code>.</p><h2id="songs"tabindex="-1">Songs <aclass="header-anchor"href="#songs"aria-label="Permalink to "Songs""></a></h2><p>There's a couple of different sounds that will automatically be enabled without any other configuration:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>STARTUP_SONG // plays when the keyboard starts up (audio.c)</span></span>
<spanclass="line"><span>GOODBYE_SONG // plays when you press the QK_BOOT key (quantum.c)</span></span>
<spanclass="line"><span>AG_NORM_SONG // plays when you press AG_NORM (quantum.c)</span></span>
<spanclass="line"><span>AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)</span></span>
<spanclass="line"><span>CG_NORM_SONG // plays when you press CG_NORM (quantum.c)</span></span>
<spanclass="line"><span>CG_SWAP_SONG // plays when you press CG_SWAP (quantum.c)</span></span>
<spanclass="line"><span>MUSIC_ON_SONG // plays when music mode is activated (process_music.c)</span></span>
<spanclass="line"><span>MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)</span></span>
<spanclass="line"><span>CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)</span></span>
<spanclass="line"><span>GUITAR_SONG // plays when the guitar music mode is selected (process_music.c)</span></span>
<spanclass="line"><span>VIOLIN_SONG // plays when the violin music mode is selected (process_music.c)</span></span>
<spanclass="line"><span>MAJOR_SONG // plays when the major music mode is selected (process_music.c)</span></span></code></pre></div><p>You can override the default songs by doing something like this in your <code>config.h</code>:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#ifdef</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_ENABLE</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#endif</span></span></code></pre></div><p>A full list of sounds can be found in <ahref="https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h"target="_blank"rel="noreferrer">quantum/audio/song_list.h</a> - feel free to add your own to this list! All available notes can be seen in <ahref="https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h"target="_blank"rel="noreferrer">quantum/audio/musical_notes.h</a>.</p><p>Additionally, if you with to maintain your own list of songs (such as ones that may be copyrighted) and not have them added to the repo, you can create a <code>user_song_list.h</code> file and place it in your keymap (or userspace) folder. This file will be automatically included, it just needs to exist.</p><p>To play a custom sound at a particular time, you can define a song like this (near the top of the file):</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">float</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> my_song</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">[]</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SONG</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(QWERTY_SOUND);</span></span></code></pre></div><p>And then play your song like this:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">PLAY_SONG</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(my_song);</span></span></code></pre></div><p>Alternatively, you can play it in a loop like this:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">PLAY_LOOP</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(my_song);</span></span></code></pre></div><p>It's advised that you wrap all audio features in <code>#ifdef AUDIO_ENABLE</code> / <code>#endif</code> to avoid causing problems when audio isn't built into the keyboard.</p><p>The available keycodes for audio are:</p><table><thead><tr><th>Key</th><th>Aliases</th><th>Description</th></tr></thead><tbody><tr><td><code>QK_AUDIO_ON</code></td><td><code>AU_ON</code></td><td>Turns on Audio Feature</td></tr><tr><td><code>QK_AUDIO_OFF</code></td><td><code>AU_OFF</code></td><td>Turns off Audio Feature</td></tr><tr><td><code>QK_AUDIO_TOGGLE</code></td><td><code>AU_TOGG</code></td><td>Toggles Audio state</td></tr></tbody></table><divclass="warning custom-block"><pclass="custom-block-title">WARNING</p><p>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.</p></div><h2id="audio-config"tabindex="-1">Audio Config <aclass="header-anchor"href="#audio-config"aria-label="Permalink to "Audio Config""></a></h2><table><thead><tr><th>Settings</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>AUDIO_PIN</code></td><td><em>Not defined</em></td><td>Configures the pin that the speaker is connected to.</td></tr><tr><td><code>AUDIO_PIN_ALT</code></td><td><em>Not defined</em></td><td>Configures the pin for a second speaker or second pin connected to one sp
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">void</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> audio_decrease_tempo</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">uint8_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> tempo_change</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><h2id="arm-audio-volume"tabindex="-1">ARM Audio Volume <aclass="header-anchor"href="#arm-audio-volume"aria-label="Permalink to "ARM Audio Volume""></a></h2><p>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 <code>AUDIO_DAC_SAMPLE_MAX</code> in your <code>config.h</code>:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_DAC_SAMPLE_MAX</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 4095</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">U</span></span></code></pre></div><p>the DAC usually runs in 12Bit mode, hence a volume of 100% = 4095U</p><p>Note: this only adjusts the volume aka 'works' if you stick to WAVEFORM_SQUARE, since its samples are generated on the fly - any other waveform uses a hardcoded/precomputed sample-buffer.</p><h2id="voices"tabindex="-1">Voices <aclass="header-anchor"href="#voices"aria-label="Permalink to "Voices""></a></h2><p>Aka "audio effects", different ones can be enabled by setting in <code>config.h</code> these defines: <code>#define AUDIO_VOICES</code> to enable the feature, and <code>#define AUDIO_VOICE_DEFAULT something</code> to select a specific effect for details see quantum/audio/voices.h and .c</p><p>Keycodes available:</p><table><thead><tr><th>Key</th><th>Aliases</th><th>Description</th></tr></thead><tbody><tr><td><code>QK_AUDIO_VOICE_NEXT</code></td><td><code>AU_NEXT</code></td><td>Cycles through the audio voices</td></tr><tr><td><code>QK_AUDIO_VOICE_PREVIOUS</code></td><td><code>AU_PREV</code></td><td>Cycles through the audio voices in reverse</td></tr></tbody></table><h2id="music-mode"tabindex="-1">Music Mode <aclass="header-anchor"href="#music-mode"aria-label="Permalink to "Music Mode""></a></h2><p>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 <code>0xFF</code> 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.</p><p>Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.</p><p>Keycodes available:</p><table><thead><tr><th>Key</th><th>Aliases</th><th>Description</th></tr></thead><tbody><tr><td><code>QK_MUSIC_ON</code></td><td><code>MU_ON</code></td><td>Turns on Music Mode</td></tr><tr><td><code>QK_MUSIC_OFF</code></td><td><code>MU_OFF</code></td><td>Turns off Music Mode</td></tr><tr><td><code>QK_MUSIC_TOGGLE</code></td><td><code>MU_TOGG</code></td><td>Toggles Music Mode</td></tr><tr><td><code>QK_MUSIC_MODE_NEXT</code></td><td><code>MU_NEXT</code></td><td>Cycles through the music modes</td></tr></tbody></table><p>Available Modes:</p><ul><li><code>CHROMATIC_MODE</code> - Chromatic scale, row changes the octave</li><li><code>GUITAR_MODE</code> - Chromatic scale, but the row changes the string (+5 st)</li><li><code>VIOLIN_MODE</code> - Chromatic scale, but the row changes the string (+7 st)</li><li><code>MAJOR_MODE</code> - Major scale</li></ul><p
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span></code></pre></div><p>Things that return false are not part of the mask, and are always processed.</p><h3id="music-map"tabindex="-1">Music Map <aclass="header-anchor"href="#music-map"aria-label="Permalink to "Music Map""></a></h3><p>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.</p><p>However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural.</p><p>To enable this feature, add <code>#define MUSIC_MAP</code> to your <code>config.h</code> file, and then you will want to add a <code>uint8_t music_map</code> to your keyboard's <code>c</code> file, or your <code>keymap.c</code>.</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"> uint8_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> music_map</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[MATRIX_ROWS][MATRIX_COLS] </span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> LAYOUT_ortho_4x12</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>You will want to use whichever <code>LAYOUT</code> 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.</p><p>You can look at the <ahref="https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29"target="_blank"rel="noreferrer">Planck Keyboard</a> as an example of how to implement this.</p><h2id="audio-click"tabindex="-1">Audio Click <aclass="header-anchor"href="#audio-click"aria-label="Permalink to "Audio Click""></a></h2><p>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.</p><p>Keycodes available:</p><table><thead><tr><th>Key</th><th>Aliases</th><th>Description</th></tr></thead><tbody><tr><td><code>QK_AUDIO_CLICKY_TOGGLE</code></td><td><code>CK_TOGG</code></td><td>Toggles Audio clicky mode</td></tr><tr><td><code>QK_AUDIO_CLICKY_ON</code></td><td><code>CK_ON</code></td><td>Turns on Audio clicky mode</td></tr><tr><td><code>QK_AUDIO_CLICKY_OFF</code></td><td><code>CK_OFF</code></td><td>Turns on Audio clicky mode</td></tr><tr><td><code>QK_AUDIO_CLICKY_UP</code></td><td><code>CK_UP</code></td><td>Increases frequency of the clicks</td></tr><tr><td><code>QK_AUDIO_CLICKY_DOWN</code></td><td><code>CK_DOWN</code></td><td>Decreases frequency of the clicks</td></tr><tr><td><code>QK_AUDIO_CLICKY_RESET</code></td><td><code>CK_RST</code></td><td>Resets frequency to default</td></tr></tbody></table><p>The feature is disabled by default, to save space. To enable it, add this to your <code>config.h</code>:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_CLICKY</span></span></code></pre></div><p>You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values:</p><table><thead><tr><th>Option</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><code>AUDIO_CLICKY_FREQ_DEFAULT</code></td><td>440.0f</td><td>Sets the default/starting audio frequency for the clicky sounds.</td></tr><tr><td><code>AUDIO_CLICKY_FREQ_MIN</code></td><td>65.0f</td><td>Sets the lowest frequency (under 60f are a bit buggy).</td></tr><tr><td><code>AUDIO_CLICKY_FREQ_MAX</code></td><td>1500.0f</td><td>Sets the highest frequency. Too high may result in coworkers attacking you.</td></tr><tr><td><code>AUDIO_CLICKY_FREQ_FACTOR</code></td><td>1.18921f</td><td>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.</td></tr><tr><td><code>AUDIO_CLICKY_FREQ_RANDOMNESS</code></td><td>0.05f</td><td>Sets a factor of randomness for the clicks, Setting this to <code>0f</code> will make each click identical, and <code>1.0f</code> will make this sound much like the 90's computer screen scrolling/typing effect.</td></tr><tr><td><code>AUDIO_CLICKY_DELAY_DURATION</code></td><td>1</td><td>An integer note duration where 1 is 1/16th of the tempo, or a sixty-fourth note (see <code>quantum/audio/musical_notes.h</code> 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.</td></tr></tbody></table><h2id="midi-functionality"tabindex="-1">MIDI Functionality <aclass="header-anchor"href="#midi-functionality"aria-label="Permalink to "MIDI Functionality""></a></h2><p>See <ahref="./midi">MIDI<
