 |
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 | STANDARD 0 |
| Used to set AUDIO_MODE to STANDARD, STANDARD_PLUS, or HIFI. 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 0 |
Used to set AUDIO_MODE to STANDARD, STANDARD_PLUS, or HIFI.
Use #define AUDIO_MODE STANDARD_PLUS in Mozzi/config.h to select this output configuration, which is nearly 9 bit sound (-244 to 243) at 16384 Hz sample rate (AUDIO_RATE) and 32768 Hz PWM rate. It uses Timer 1 for PWM and the sample updating routine (as an interrupt).
STANDARD is obsolete now, replaced by STANDARD_PLUS which is the default audio mode. STANDARD mode uses 16384 Hz PWM rate with an output interrupt at the same frequency. Some people can hear the PWM carrier frequency as an annoying whine.
STANDARD_PLUS mode uses 32768 Hz PWM rate, so the PWM carrier is out of hearing range. In this mode every alternate interrupt is used for the sample update (unless you /#define AUDIO_RATE 32768 in mozzi_config.h), which makes it slightly less efficient than STANDARD, but almost always better.
Advantages: Only uses one timer for audio, and one output pin. Disadvantages: low dynamic range.
Below is a list of the Digital Pins used by Mozzi for STANDARD and STANDARD_PLUS audio out on different boards. Those which have been tested and reported to work have an x. Feedback about others is welcome.
x....9........Arduino Uno
x....9........Arduino Duemilanove
x....9........Arduino Nano
x....9........Arduino Leonardo
x....9........Ardweeny
x....9........Boarduino
x...11.......Freetronics EtherMega *broken since Jan 2015
x...11.......Arduino Mega *broken since Jan 2015
....14........Teensy
x..B5........Teensy2
x..B5(25)..Teensy2++
x..A14.....Teensy 3.0, 3.1 and 3.2
....13 .......Sanguino
On Teensy 3.* STANDARD and STANDARD_PLUS are the same, providing 16384Hz sample rate and 12 bit resolution on pin A14/ADC. The Teensy 3.* DAC output does not rely on PWM.
On AVR, there is the possibility to use an external DAC in order to have an Audio output which does not rely on PWM. For now, this is only implemented for MCP49XX DAC, you can enable this in mozzi_config.h. Please see details in AudioConfigExternalDAC.h. Used to set AUDIO_MODE to HIFI.
Use #define AUDIO_MODE HIFI in Mozzi/config.h to set the audio mode to HIFI for output 14 bit sound at 16384 Hz sample rate and 125kHz PWM rate. The high PWM rate of HIFI mode places the carrier frequency beyond audible range.
Also, 14 bits of dynamic range in HIFI mode provides more definition than the nearly 9 bits in STANDARD_PLUS mode. HIFI mode takes about the same amount of processing time as STANDARD_PLUS mode, and should sound clearer and brighter. However, it requires an extra timer to be used on the Arduino, which could increase the chances of conflicts with other libraries or processes if they rely on Timer 2.
Timer 1 is used to provide the PWM output at 125kHz. Timer 2 generates an interrupt at AUDIO_RATE 16384 Hz, which sets the Timer1 PWM levels. HIFI mode uses 2 output pins, and sums their outputs with resistors, so is slightly less convenient for rapid prototyping where you could listen to STANDARD_PLUS mode by connecting the single output pin directly to a speaker or audio input (though a resistor of about 100 ohms is recommended).
The resistors needed for HIFI output are 3.9k and 499k, with 0.5% or better tolerance. If you can only get 1% resistors, use a multimeter to find the most accurate. Use two 1M resistors in parallel if you can't find 499k.
On 328 based Arduino boards, output is on Timer1, with the high byte on Pin 9 and low byte on Pin 10. Add the signals through a 3.9k resistor on high byte pin (9) and 499k resistor on low byte pin (10). Also, a 4.7nF capacitor is recommended between the summing junction of the resistors and ground.
This dual PWM technique is discussed on http://www.openmusiclabs.com/learning/digital/pwm-dac/dual-pwm-circuits/ Also, there are higher quality output circuits are on the site.
Advantages: should be higher quality sound than STANDARD_PLUS mode. Doesn't need a notch filter on the audio signal (like STANDARD which is now obsolete) because the carrier frequency is out of hearing range.
Disadvantages: requires 2 pins, 2 resistors and a capacitor, so it's not so quick to set up compared to a rough, direct single-pin output in STANDARD_PLUS mode.
Pins and where to put the resistors on various boards for HIFI mode. Boards tested in HIFI mode have an x, though most of these have been tested in STANDARD_PLUS mode and there's no reason for them not to work in HIFI (unless the pin number is wrong or something). Any reports are welcome.
resistor.....3.9k......499k
x................9..........10...............Arduino Uno
x................9..........10...............Arduino Duemilanove
x................9..........10...............Arduino Nano
x................9..........10...............Arduino Leonardo
x................9..........10...............Ardweeny
x................9..........10...............Boarduino
x...............11.........12...............Freetronics EtherMega
.................11.........12...............Arduino Mega
.................14.........15...............Teensy
.............B5(14)...B6(15)...........Teensy2
x...........B5(25)...B6(26)...........Teensy2++
.................13.........12...............Sanguino
HIFI is not available/not required on Teensy 3.* or ARM.
Definition at line 155 of file MozziGuts.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 382 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).
Definition at line 845 of file MozziGuts.cpp.
|
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).
Definition at line 858 of file MozziGuts.cpp.
| 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. |
Definition at line 782 of file MozziGuts.cpp.
| 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.
Definition at line 797 of file MozziGuts.cpp.
| 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