MOZZI

sound synthesis library for Arduino

Currently your Arduino can only beep like a microwave oven. Mozzi brings your Arduino to life by allowing it to produce much more complex and interesting growls, sweeps and chorusing atmospherics. These sounds can be quickly and easily constructed from familiar synthesis units like oscillators, delays, filters and envelopes.

You can use Mozzi to generate algorithmic music for an installation or performance, or make interactive sonifications of sensors, on a small, modular and super cheap Arduino, without the need for additional shields, message passing or external synths.

Here are some sounds of the example sketches which come with Mozzi:

Using a “Line” to sweep frequency:

Phase and amplitude modulation, with reverb:

A chordal wash of detuned oscillator pairs:

Waveshaping:

Samples sequenced on the fly:


Features

  • 16384 Hz sample rate or experimental 32768 Hz rate.
  • 8 bit or 14 bit audio output modes.
  • Variable control rate from 64 Hz up.
  • Useful basic audio toolkit: oscillators, samples, lines, envelopes, scheduling, filtering.
  • Fast ADC and other cpu-efficient code utilities to help keep audio running smoothly.
  • Example sketches for easy modification.
  • Readymade wavetables and a script to convert your own soundfiles for Mozzi.
  • Designed to be easy to use, open source and extendable.

Installation

Download Mozzi from the top of this page. Then, following the instructions from the Arduino libraries guide:

In the Arduino IDE, navigate to Sketch > Import Library. At the top of the drop down list, select the option to Add Library. Navigate to the .zip file’s location and open it. Return to the Sketch > Import Library menu. You should now see the library at the bottom of the drop-down menu. It is ready to be used in your sketch.


Quick Start

To hear Mozzi, connect a 3.5mm audio jack with the centre wire to the PWM output on Digital Pin 9* on Arduino, and the ground to the Ground on the Arduino. Use this as a line out which you can plug into your computer and listen to with a sound program like Audacity.
Try some examples from the File > Examples > Mozzi menu.
* The pin used by Mozzi for audio output depends on which board you have. These boards have been tested:

Board Output Pin
Arduino Uno …9
Arduino Duemilanove …9
Arduino Nano …9
Arduino Pro Mini …9
Arduino Leonardo …9
Ardweeny …9
Boarduino …9
Arduino Mega …11
Freetronics EtherMega …11
Teensy2 …B5
Teensy2++ …B5(25)


For more about audio output, including HIFI mode, read the Mozzi core module documentation.


Using Mozzi

Here’s a template for an empty Mozzi sketch:

Mozzi Skeleton
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#include <MozziGuts.h>   // at the top of your sketch

void setup() {
  startMozzi();
}

void updateControl(){
  // your control code
}

int updateAudio(){
  // your audio code which returns an int between -244 and 243
}

void loop() {
  audioHook();
}

There’s a detailed example explaining the different parts here.


Documentation

There’s documentation in the extras/doc folder in the Mozzi download and online.
There is practical help on the learn page on the Mozzi site.
Start or look up a topic on the users forum.
Also, feel free to submit any issues on the GitHub Mozzi site.
Look for code and usage changes here.


Caveats and Workarounds

  • Mozzi disables Arduino millis() micros() delay() and delayMicroseconds().

Instead, use Metronome() or EventDelay() for scheduling and mozziMicros() for timing.

  • analogRead() is disabled, replaced by mozziAnalogRead(), which works in the background instead of blocking the processor.

  • Mozzi disables analogWrite() on pins 5 and 6 (Timer 0), 9 and 10 (Timer 1) in STANDARD mode. In HIFI mode, pins 3 and 11 (Timer 2) are also out. Pin numbers vary between boards.

You can do PWM (analog write) on any digital pins by following this example.

Pause Mozzi

To restore Arduino time and PWM functions, you can use pauseMozzi() to suspend audio and control interrupts. Start again with unpauseMozzi().


If you enjoy using Mozzi for a project, or have extended it, we would be pleased to hear about it and provide support wherever possible. Contribute suggestions, improvements and bug fixes to the Mozzi wiki on Github, or Fork it to contribute directly to future developments.

Mozzi is a development of research into Mobile Sonification in the SweatSonics project.


Contributions / Included Dependencies

Modified versions of the following libraries are included in the Mozzi download:

TimerOne library
FrequencyTimer2 library - now a fork with support for ATmega32u4 processors