Mozzi  version v1.1.0
sound synthesis library for Arduino
Core


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 >
mozzi_pgm_read_wrapper (const T *address)
 Helper function to FLASH_OR_RAM_READ(). More...
 
template<typename 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
 

Detailed Description


Core definitions and functions.

The bones of every Mozzi sketch.

Macro Definition Documentation

◆ AUDIO_MODE

#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.

Note
Teensy 3.* plays 12 bit audio in STANDARD or STANDARD_PLUS modes, and has no HIFI mode.

Definition at line 27 of file mozzi_config.h.

◆ AUDIO_RATE

#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.

◆ CONSTTABLE_STORAGE

#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.

◆ STANDARD_PWM_RESOLUTION [1/2]

#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.

◆ STANDARD_PWM_RESOLUTION [2/2]

#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.

◆ STEREO_HACK

#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.

◆ USE_AUDIO_INPUT

#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.

Function Documentation

◆ audioHook()

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.

◆ audioTicks()

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).

Returns
the number of audio ticks since the program began.

◆ FLASH_OR_RAM_READ()

template<typename T >
T FLASH_OR_RAM_READ ( T *  address)
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.

See also
CONSTTABLE_STORAGE .

Definition at line 46 of file mozzi_pgmspace.h.

◆ mozzi_pgm_read_wrapper()

template<typename T >
T mozzi_pgm_read_wrapper ( const T *  address)
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.

◆ mozziMicros()

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).

Returns
the approximate number of microseconds since the program began.

◆ startMozzi()

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.

Parameters
control_rate_hzSets 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.
Note
startMozzi calls setupMozziADC(), which calls setupFastAnalogRead() and adcDisconnectAllDigitalIns(), which disables digital inputs on all analog input pins. All in mozzi_analog.h and easy to change if you need to (hack). They are all called automatically and hidden away because it keeps things simple for a STANDARD_PLUS set up, but if it turns out to be confusing, they might need to become visible again.

◆ stopMozzi()

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.

◆ unPauseMozzi()

void unPauseMozzi ( )

Obsolete function, use startMozzi() instead.

Restores Mozzi audio and control interrupts, if they have been temporarily disabled with pauseMozzi().

◆ 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().

Variable Documentation

◆ audio_out_1

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().

Returns
an audio sample. In STANDARD modes this is between -244 and 243 inclusive. In HIFI mode, it's a 14 bit number between -16384 and 16383 inclusive.