 |
Mozzi
version v1.1.0
sound synthesis library for Arduino
|
|
|
Mozzi
version v1.1.0
sound synthesis library for Arduino
|
|
Core definitions and functions.
More...
Macros | |
| #define | AUDIO_MODE STANDARD_PLUS |
| AUDIO_MODE holds the audio mode setting. More... | |
| #define | AUDIO_RATE 16384 |
| Holds the audio rate setting. More... | |
| #define | USE_AUDIO_INPUT false |
| Whether or not to use audio input. More... | |
| #define | AUDIO_INPUT_PIN 0 |
| This sets which analog input channel to use for audio input, if you have #define USE_AUDIO_INPUT true in mozz_config.h. | |
| #define | STEREO_HACK false |
| This sets an option for stereo output, a hack which requires variables audio_signal_1 and audio_signal_2 to be set in updateAudio(), instead of returning a single audio value as is usual for standard mono. More... | |
| #define | CONSTTABLE_STORAGE(X) const X __attribute__((section(".progmem.data"))) |
| Declare a variable such that it will be stored in flash memory, instead of RAM, on platforms where this is reasonably possible (i.e. More... | |
| #define | AUDIO_BIAS ((uint16_t) 2048) |
| #define | STANDARD_PWM_RESOLUTION 488 |
| This is the dynamic range of Mozzi's audio output in STANDARD mode. More... | |
| #define | STANDARD_PWM_RESOLUTION 488 |
| This is the dynamic range of Mozzi's audio output in STANDARD mode. More... | |
| #define | AUDIO_BIAS ((uint16_t) 2048) |
Functions | |
| template<typename T > | |
| T | mozzi_pgm_read_wrapper (const T *address) |
| Helper function to FLASH_OR_RAM_READ(). More... | |
| template<typename T > | |
| T | FLASH_OR_RAM_READ (T *address) |
| Read a value from flash or RAM. More... | |
| void | startMozzi (int control_rate_hz=CONTROL_RATE) |
| Sets up the timers for audio and control rate processes, storing the timer registers so they can be restored when Mozzi stops. More... | |
| void | stopMozzi () |
| Stops audio and control interrupts and restores the timers to the values they had before Mozzi was started. More... | |
| void | pauseMozzi () |
| Obsolete function, use stopMozzi() instead. | |
| void | unPauseMozzi () |
| Obsolete function, use startMozzi() instead. More... | |
| void | updateControl () |
| This is where you put your control code. More... | |
| void | audioHook () |
| This is required in Arduino's loop(). More... | |
| unsigned long | audioTicks () |
| An alternative for Arduino time functions like micros() and millis(). More... | |
| unsigned long | mozziMicros () |
| An alternative for Arduino time functions like micros() and millis(). More... | |
Variables | |
| int | audio_out_1 |
| This is where you put your audio code. More... | |
| int | audio_out_2 |
Core definitions and functions.
The bones of every Mozzi sketch.
| #define AUDIO_MODE STANDARD_PLUS |
AUDIO_MODE holds the audio mode setting.
Select STANDARD (depreciated), STANDARD_PLUS or HIFI audio output mode in the Mozzi/mozzi_config.h file with #define AUDIO_MODE STANDARD_PLUS or #define AUDIO_MODE HIFI. In Mozzi/config.h, comment one of these options in and the others out to set the audio mode.
In STANDARD_PLUS mode the sample resolution is 488, which provides some headroom above the 8 bit table resolution currently used by the oscillators. You can look at utility/TimerOne library for more info about how interrupt rate and pwm resolution relate.
HIFI audio mode enables much higher quality output by combining signals from pins 9 and 10. For HIFI mode, edit Mozzi/mozzi_config.h to contain #define AUDIO_MODE HIFI, and comment out #define AUDIO_MODE STANDARD and #define AUDIO_MODE STANDARD_PLUS.
Definition at line 27 of file mozzi_config.h.
| #define AUDIO_RATE 16384 |
Holds the audio rate setting.
AUDIO_RATE can be #defined as 16384 or 32768 Hertz in Mozzi/mozzi_config.h.
Mozzi's original audio mode, now called STANDARD, uses 16384 Hz, chosen as a compromise between the sample rate (interrupt rate) and sample bitdepth (pwm width), which are interdependent due to the way pulse wave modulation is used to generate the sound output. An AUDIO_RATE of 32768 Hz works in STANDARD_PLUS and HIFI modes. Of course, doubling the sample rate halves the amount of time available to calculate the each sample, so it may only be useful for relatively simple sketches. The increased frequency response can also make unwanted artefacts of low resolution synthesis calculations more apparent, so it's not always a bonus.
Another factor which is important for Mozzi's operation is that with AUDIO_RATE being a power of two, some internal calculations can be highly optimised for speed.
In STANDARD and STANDARD_PLUS modes, the sample resolution is 488, which provides some headroom above the 8 bit table resolution currently used by the oscillators. You can look at the TimerOne library for more info about how interrupt rate and pwm resolution relate.
HIFI audio mode enables much higher quality output by combining signals from pins 9 and 10. For HIFI mode, edit Mozzi/mozzi_config.h to contain #define AUDIO_MODE HIFI, and comment out #define AUDIO_MODE STANDARD and #define AUDIO_MODE STANDARD_PLUS.
Definition at line 61 of file mozzi_config.h.
| #define CONSTTABLE_STORAGE | ( | X | ) | const X __attribute__((section(".progmem.data"))) |
Declare a variable such that it will be stored in flash memory, instead of RAM, on platforms where this is reasonably possible (i.e.
not on ESP8266, where random location flash memory access is too slow). To read the variable in a cross-platform compatible way, use FLASH_OR_RAM_READ().
Definition at line 56 of file mozzi_pgmspace.h.
| #define STANDARD_PWM_RESOLUTION 488 |
This is the dynamic range of Mozzi's audio output in STANDARD mode.
It is equal to Timer1.pwmPeriod calculated for interrupt rate 16384. It's included in the documentation because it's a slightly unusual number and useful to know about when you're writing sketches.
Definition at line 11 of file AudioConfigStandardPlus.h.
| #define STANDARD_PWM_RESOLUTION 488 |
This is the dynamic range of Mozzi's audio output in STANDARD mode.
It is equal to Timer1.pwmPeriod calculated for interrupt rate 16384. It's included in the documentation because it's a slightly unusual number and useful to know about when you're writing sketches.
Definition at line 11 of file AudioConfigStandard9bitPwm.h.
| #define STEREO_HACK false |
This sets an option for stereo output, a hack which requires variables audio_signal_1 and audio_signal_2 to be set in updateAudio(), instead of returning a single audio value as is usual for standard mono.
You need to have #define STEREO_HACK true in mozzi_config.h
Definition at line 90 of file mozzi_config.h.
| #define USE_AUDIO_INPUT false |
Whether or not to use audio input.
Put #define USE_AUDIO_INPUT false in Mozzi/mozzi_config.h to enable audio input on analog pin AUDIO_INPUT_PIN, otherwise make it false, to save resources.
Definition at line 71 of file mozzi_config.h.
| void audioHook | ( | ) |
This is required in Arduino's loop().
If there is room in Mozzi's output buffer, audioHook() calls updateAudio() once and puts the result into the output buffer. Also, if #define USE_AUDIO_INPUT true is in Mozzi/mozzi_config.h, audioHook() takes care of moving audio input from the input buffer so it can be accessed with getAudioInput() in your updateAudio() routine. If other functions are called in loop() along with audioHook(), see if they can be called less often by moving them into updateControl(), to save processing power. Otherwise it may be most efficient to calculate a block of samples at a time by putting audioHook() in a loop of its own, rather than calculating only 1 sample for each time your other functions are called.
Definition at line 371 of file MozziGuts.cpp.
| unsigned long audioTicks | ( | ) |
An alternative for Arduino time functions like micros() and millis().
This is slightly faster than micros(), and also it is synchronized with the currently processed audio sample (which, due to the audio output buffer, could diverge up to 256/AUDIO_RATE seconds from the current time). audioTicks() is updated each time an audio sample is output, so the resolution is 1/AUDIO_RATE microseconds (61 microseconds when AUDIO_RATE is 16384 Hz).
|
inline |
Read a value from flash or RAM.
The specified address is read from flash, if T is const, and const tables are stored in flash on this platform (i.e. not on ESP8266). It is read from RAM, if T is not-const or tables are always stored in RAM on this platform.
Definition at line 46 of file mozzi_pgmspace.h.
|
inline |
Helper function to FLASH_OR_RAM_READ().
You do not want to call this, directly.
Definition at line 21 of file mozzi_pgmspace.h.
| unsigned long mozziMicros | ( | ) |
An alternative for Arduino time functions like micros() and millis().
This is slightly faster than micros(), and also it is synchronized with the currently processed audio sample (which, due to the audio output buffer, could diverge up to 256/AUDIO_RATE seconds from the current time). audioTicks() is updated each time an audio sample is output, so the resolution is 1/AUDIO_RATE microseconds (61 microseconds when AUDIO_RATE is 16384 Hz).
| void startMozzi | ( | int | control_rate_hz = CONTROL_RATE | ) |
Sets up the timers for audio and control rate processes, storing the timer registers so they can be restored when Mozzi stops.
startMozzi() goes in your sketch's setup() routine.
Contrary to earlier versions of Mozzi, this version does not take over Timer 0, and thus Arduino functions delay(), millis(), micros() and delayMicroseconds() remain usable in theory. That said, you should avoid these functions, as they are slow (or even blocking). For measuring time, refer to mozziMircos(). For delaying events, you can use Mozzi's EventDelay() unit instead (not to be confused with AudioDelay()).
In STANDARD mode, startMozzi() starts Timer 1 for PWM output and audio output interrupts, and in STANDARD_PLUS and HIFI modes, Mozzi uses Timer 1 for PWM and Timer2 for audio interrupts.
The audio rate defaults to 16384 Hz, but you can experiment with 32768 Hz by changing AUDIO_RATE in mozzi_config.h.
| control_rate_hz | Sets how often updateControl() is called. It must be a power of 2. If no parameter is provided, control_rate_hz is set to CONTROL_RATE, which has a default value of 64 (you can re-#define it in your sketch). The practical upper limit for control rate depends on how busy the processor is, and you might need to do some tests to find the best setting. |
| void stopMozzi | ( | ) |
Stops audio and control interrupts and restores the timers to the values they had before Mozzi was started.
This could be useful when using sensor libraries which depend on the same timers as Mozzi.
A potentially better option for resolving timer conflicts involves using non-blocking methods, such as demonstrated by the twowire_nonblock code in the forked version of Mozzi on github, so sound production can continue while reading sensors.
As it is, stopMozzi restores all the Timers used by Mozzi to their previous settings. Another scenario which could be easily hacked in MozziGuts.cpp could involve individually saving and restoring particular Timer registers depending on which one(s) are required for other tasks.
| void unPauseMozzi | ( | ) |
Obsolete function, use startMozzi() instead.
Restores Mozzi audio and control interrupts, if they have been temporarily disabled with pauseMozzi().
| void updateControl | ( | ) |
This is where you put your control code.
You need updateControl() somewhere in your sketch, even if it's empty. updateControl() is called at the control rate you set in startMozzi(). To save processor load, avoid any calculations here which could be done in setup().
| int audio_out_1 |
This is where you put your audio code.
updateAudio() has to keep up with the AUDIO_RATE of 16384 Hz, so to keep things running smoothly, avoid doing any calculations here which could be done in setup() or updateControl().
1.8.14