logo

qmk_firmware

custom branch of QMK firmware git clone https://anongit.hacktivis.me/git/qmk_firmware.git

audio.h (10371B)

    

  1. /* Copyright 2016-2020 Jack Humbert
  2.  * Copyright 2020 JohSchneider
  3.  *
  4.  * This program is free software: you can redistribute it and/or modify
  5.  * it under the terms of the GNU General Public License as published by
  6.  * the Free Software Foundation, either version 2 of the License, or
  7.  * (at your option) any later version.
  8.  *
  9.  * This program is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12.  * GNU General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU General Public License
  15.  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16.  */
  17. #pragma once
  19. #include <stdint.h>
  20. #include <stdbool.h>
  22. #include "compiler_support.h"
  23. #include "musical_notes.h"
  24. #include "song_list.h"
  25. #include "voices.h"
  27. #if defined(AUDIO_DRIVER_PWM)
  28. #    include "audio_pwm.h"
  29. #elif defined(AUDIO_DRIVER_DAC)
  30. #    include "audio_dac.h"
  31. #endif
  33. typedef union audio_config_t {
  34.     uint8_t raw;
  35.     struct {
  36.         bool    enable : 1;
  37.         bool    clicky_enable : 1;
  38.         bool    valid : 1;
  39.         uint8_t reserved : 5;
  40.     };
  41. } audio_config_t;
  43. STATIC_ASSERT(sizeof(audio_config_t) == sizeof(uint8_t), "Audio EECONFIG out of spec.");
  45. /*
  46.  * a 'musical note' is represented by pitch and duration; a 'musical tone' adds intensity and timbre
  47.  * https://en.wikipedia.org/wiki/Musical_tone
  48.  * "A musical tone is characterized by its duration, pitch, intensity (or loudness), and timbre (or quality)"
  49.  */
  50. typedef struct {
  51.     uint16_t time_started; // timestamp the tone/note was started, system time runs with 1ms resolution -> 16bit timer overflows every ~64 seconds, long enough under normal circumstances; but might be too soon for long-duration notes when the note_tempo is set to a very low value
  52.     float    pitch;        // aka frequency, in Hz
  53.     uint16_t duration;     // in ms, converted from the musical_notes.h unit which has 64parts to a beat, factoring in the current tempo in beats-per-minute
  54.     // float intensity;    // aka volume [0,1] TODO: not used at the moment; pwm drivers can't handle it
  55.     // uint8_t timbre;     // range: [0,100] TODO: this currently kept track of globally, should we do this per tone instead?
  56. } musical_tone_t;
  58. // public interface
  60. /**
  61.  * @brief Save the current choices to the eeprom
  62.  */
  63. void eeconfig_update_audio_current(void);
  65. /**
  66.  * @brief one-time initialization called by quantum/quantum.c
  67.  * @details usually done lazy, when some tones are to be played
  68.  *
  69.  * @post audio system (and hardware) initialized and ready to play tones
  70.  */
  71. void audio_init(void);
  72. void audio_startup(void);
  74. /**
  75.  * @brief en-/disable audio output, save this choice to the eeprom
  76.  */
  77. void audio_toggle(void);
  78. /**
  79.  * @brief enable audio output, save this choice to the eeprom
  80.  */
  81. void audio_on(void);
  82. /**
  83.  * @brief disable audio output, save this choice to the eeprom
  84.  */
  85. void audio_off(void);
  86. /**
  87.  * @brief query the if audio output is enabled
  88.  */
  89. bool audio_is_on(void);
  91. /**
  92.  * @brief start playback of a tone with the given frequency and duration
  93.  *
  94.  * @details starts the playback of a given note, which is automatically stopped
  95.  *          at the the end of its duration = fire&forget
  96.  *
  97.  * @param[in] pitch frequency of the tone be played
  98.  * @param[in] duration in milliseconds, use 'audio_duration_to_ms' to convert
  99.  *                     from the musical_notes.h unit to ms
  100.  */
  101. void audio_play_note(float pitch, uint16_t duration);
  102. // TODO: audio_play_note(float pitch, uint16_t duration, float intensity, float timbre);
  103. // audio_play_note_with_instrument ifdef AUDIO_ENABLE_VOICES
  105. /**
  106.  * @brief start playback of a tone with the given frequency
  107.  *
  108.  * @details the 'frequency' is put on-top the internal stack of active tones,
  109.  *          as a new tone with indefinite duration. this tone is played by
  110.  *          the hardware until a call to 'audio_stop_tone'.
  111.  *          should a tone with that frequency already be active, its entry
  112.  *          is put on the top of said internal stack - so no duplicate
  113.  *          entries are kept.
  114.  *          'hardware_start' is called upon the first note.
  115.  *
  116.  * @param[in] pitch frequency of the tone be played
  117.  */
  118. void audio_play_tone(float pitch);
  120. /**
  121.  * @brief stop a given tone/frequency
  122.  *
  123.  * @details removes a tone matching the given frequency from the internal
  124.  *          playback stack
  125.  *          the hardware is stopped in case this was the last/only frequency
  126.  *          being played.
  127.  *
  128.  * @param[in] pitch tone/frequency to be stopped
  129.  */
  130. void audio_stop_tone(float pitch);
  132. /**
  133.  * @brief play a melody
  134.  *
  135.  * @details starts playback of a melody passed in from a SONG definition - an
  136.  *          array of {pitch, duration} float-tuples
  137.  *
  138.  * @param[in] np note-pointer to the SONG array
  139.  * @param[in] n_count number of MUSICAL_NOTES of the SONG
  140.  * @param[in] n_repeat false for onetime, true for looped playback
  141.  */
  142. void audio_play_melody(float (*np)[][2], uint16_t n_count, bool n_repeat);
  144. /**
  145.  * @brief play a short tone of a specific frequency to emulate a 'click'
  146.  *
  147.  * @details constructs a two-note melody (one pause plus a note) and plays it through
  148.  *          audio_play_melody. very short durations might not quite work due to
  149.  *          hardware limitations (DAC: added pulses from zero-crossing feature;...)
  150.  *
  151.  * @param[in] delay in milliseconds, length for the pause before the pulses, can be zero
  152.  * @param[in] pitch
  153.  * @param[in] duration in milliseconds, length of the 'click'
  154.  */
  155. void audio_play_click(uint16_t delay, float pitch, uint16_t duration);
  157. /**
  158.  * @brief stops all playback
  159.  *
  160.  * @details stops playback of both a melody as well as single tones, resetting
  161.  *          the internal state
  162.  */
  163. void audio_stop_all(void);
  165. /**
  166.  * @brief query if one/multiple tones are playing
  167.  */
  168. bool audio_is_playing_note(void);
  170. /**
  171.  * @brief query if a melody/SONG is playing
  172.  */
  173. bool audio_is_playing_melody(void);
  175. // These macros are used to allow audio_play_melody to play an array of indeterminate
  176. // length. This works around the limitation of C's sizeof operation on pointers.
  177. // The global float array for the song must be used here.
  178. #define NOTE_ARRAY_SIZE(x) ((int16_t)(sizeof(x) / (sizeof(x[0]))))
  180. /**
  181.  * @brief convenience macro, to play a melody/SONG once
  182.  */
  183. #define PLAY_SONG(note_array) audio_play_melody(&note_array, NOTE_ARRAY_SIZE((note_array)), false)
  184. // TODO: a 'song' is a melody plus singing/vocals -> PLAY_MELODY
  185. /**
  186.  * @brief convenience macro, to play a melody/SONG in a loop, until stopped by 'audio_stop_all'
  187.  */
  188. #define PLAY_LOOP(note_array) audio_play_melody(&note_array, NOTE_ARRAY_SIZE((note_array)), true)
  190. // Tone-Multiplexing functions
  191. // this feature only makes sense for hardware setups which can't do proper
  192. // audio-wave synthesis = have no DAC and need to use PWM for tone generation
  193. #ifdef AUDIO_ENABLE_TONE_MULTIPLEXING
  194. #    ifndef AUDIO_TONE_MULTIPLEXING_RATE_DEFAULT
  195. #        define AUDIO_TONE_MULTIPLEXING_RATE_DEFAULT 0
  196. //       0=off, good starting value is 4; the lower the value the higher the cpu-load
  197. #    endif
  198. void audio_set_tone_multiplexing_rate(uint16_t rate);
  199. void audio_enable_tone_multiplexing(void);
  200. void audio_disable_tone_multiplexing(void);
  201. void audio_increase_tone_multiplexing_rate(uint16_t change);
  202. void audio_decrease_tone_multiplexing_rate(uint16_t change);
  203. #endif
  205. // Tempo functions
  207. void audio_set_tempo(uint8_t tempo);
  208. void audio_increase_tempo(uint8_t tempo_change);
  209. void audio_decrease_tempo(uint8_t tempo_change);
  211. // conversion macros, from 64parts-to-a-beat to milliseconds and back
  212. uint16_t audio_duration_to_ms(uint16_t duration_bpm);
  213. uint16_t audio_ms_to_duration(uint16_t duration_ms);
  215. void audio_startup(void);
  217. // hardware interface
  219. // implementation in the driver_avr/arm_* respective parts
  220. void audio_driver_initialize_impl(void);
  221. void audio_driver_start_impl(void);
  222. void audio_driver_stop_impl(void);
  224. /**
  225.  * @brief get the number of currently active tones
  226.  * @return number, 0=none active
  227.  */
  228. uint8_t audio_get_number_of_active_tones(void);
  230. /**
  231.  * @brief access to the raw/unprocessed frequency for a specific tone
  232.  * @details each active tone has a frequency associated with it, which
  233.  *          the internal state keeps track of, and is usually influenced
  234.  *          by various effects
  235.  * @param[in] tone_index, ranging from 0 to number_of_active_tones-1, with the
  236.  *            first being the most recent and each increment yielding the next
  237.  *            older one
  238.  * @return a positive frequency, in Hz; or zero if the tone is a pause
  239.  */
  240. float audio_get_frequency(uint8_t tone_index);
  242. /**
  243.  * @brief calculate and return the frequency for the requested tone
  244.  * @details effects like glissando, vibrato, ... are post-processed onto the
  245.  *          each active tones 'base'-frequency; this function returns the
  246.  *          post-processed result.
  247.  * @param[in] tone_index, ranging from 0 to number_of_active_tones-1, with the
  248.  *            first being the most recent and each increment yielding the next
  249.  *            older one
  250.  * @return a positive frequency, in Hz; or zero if the tone is a pause
  251.  */
  252. float audio_get_processed_frequency(uint8_t tone_index);
  254. /**
  255.  * @brief   update audio internal state: currently playing and active tones,...
  256.  * @details This function is intended to be called by the audio-hardware
  257.  *          specific implementation on a somewhat regular basis while a SONG
  258.  *          or notes (pitch+duration) are playing to 'advance' the internal
  259.  *          state (current playing notes, position in the melody, ...)
  260.  *
  261.  * @return true if something changed in the currently active tones, which the
  262.  *         hardware might need to react to
  263.  */
  264. bool audio_update_state(void);
  266. // legacy and back-warts compatibility stuff
  268. #define is_audio_on() audio_is_on()
  269. #define is_playing_notes() audio_is_playing_melody()
  270. #define is_playing_note() audio_is_playing_note()
  271. #define stop_all_notes() audio_stop_all()
  272. #define stop_note(f) audio_stop_tone(f)
  273. #define play_note(f, v) audio_play_tone(f)
  275. #define set_timbre(t) voice_set_timbre(t)
  276. #define set_tempo(t) audio_set_tempo(t)
  277. #define increase_tempo(t) audio_increase_tempo(t)
  278. #define decrease_tempo(t) audio_decrease_tempo(t)
  279. // vibrato functions are not used in any keyboards
  281. void audio_on_user(void);
  282. void audio_off_user(void);