 |
Mozzi
version 2016-12-11-17:03
sound synthesis library for Arduino
|
|
|
Mozzi
version 2016-12-11-17:03
sound synthesis library for Arduino
|
|
Core definitions and functions. More...
Macros | |
| #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) |
| #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 | CONTROL_RATE 64 |
| Control rate setting. More... | |
| #define | STANDARD 0 |
| Used to set AUDIO_MODE to STANDARD, STANDARD_PLUS, or HIFI. More... | |
Functions | |
| 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 | pauseMozzi () |
| Stops audio and control interrupts and restores the timers to the values they had before Mozzi was started. More... | |
| void | unPauseMozzi () |
| Restores Mozzi audio and control interrupts, if they have been temporarily disabled with pauseMozzi(). More... | |
| void | updateAudio () |
| This is where you put your audio code. 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 funcitions like micros() which are disabled by Mozzi when it takes over Timer 0 for control interrupts. More... | |
| unsigned long | mozziMicros () |
| A replacement for Arduino micros() which is disabled by Mozzi which takes over Timer 0 for control interrupts. More... | |
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 CONTROL_RATE 64 |
Control rate setting.
Mozzi's CONTROL_RATE sets how many times per second updateControl() is called. It can be any power of 2 greater than 64, and the largest value where it starts to become impractical is around 1024. 64, 128, 256 and sometimes 512 are all usable values. Try to keep it as low as you can, for efficiency, though higher rates can sometimes give smoother results, avoiding the need to interpolate sensitive variables at audio rate in updateAudio(). CONTROL_RATE has a default of 64 Hz, but it can be changed at the top of your sketch, after the #includes, for example: #define CONTROL_RATE 256
Definition at line 38 of file MozziGuts.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 to 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.....Teensy3.1
....13 .......Sanguino
On Teensy 3.1 STANDARD and STANDARD_PLUS are the same, providing 16384Hz sample rate and 12 bit resolution on pin A14/ADC. The Teensy 3.1 DAC output does not rely on PWM.
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 https://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.1.
Definition at line 140 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 94 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 229 of file MozziGuts.cpp.
| unsigned long audioTicks | ( | ) |
An alternative for Arduino time funcitions like micros() which are disabled by Mozzi when it takes over Timer 0 for control interrupts.
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 629 of file MozziGuts.cpp.
| unsigned long mozziMicros | ( | ) |
A replacement for Arduino micros() which is disabled by Mozzi which takes over Timer 0 for control interrupts.
mozziMicros is updated each time an audio sample is output, so the resolution is 1/AUDIO_RATE (61 microseconds when AUDIO_RATE is 16384 Hz).
Definition at line 635 of file MozziGuts.cpp.
| void pauseMozzi | ( | ) |
Stops audio and control interrupts and restores the timers to the values they had before Mozzi was started.
This will enable the standard Arduino time functions millis(), micros(), delay(), and delayMicroseconds(). 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, pauseMozzi 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, so for example the control interrupt (Timer 0) could be suspended while audio continues.
Definition at line 550 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.
In STANDARD_PLUS and HIFI modes, Mozzi uses Timer 0 for control interrupts, disabling Arduino delay(), millis(), micros() and delayMicroseconds(). 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 537 of file MozziGuts.cpp.
| void unPauseMozzi | ( | ) |
Restores Mozzi audio and control interrupts, if they have been temporarily disabled with pauseMozzi().
This once more takes over Timer 0, and stops the Arduino time functions millis(), micros(), delay(), and delayMicroseconds() from working.
Definition at line 589 of file MozziGuts.cpp.
| void updateAudio | ( | ) |
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().
| 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().
1.8.12