{"id":13471333,"url":"https://github.com/sensorium/Mozzi","last_synced_at":"2025-03-26T13:31:01.614Z","repository":{"id":3451064,"uuid":"4504500","full_name":"sensorium/Mozzi","owner":"sensorium","description":"sound synthesis library for Arduino","archived":false,"fork":false,"pushed_at":"2024-10-22T16:19:04.000Z","size":372973,"stargazers_count":1078,"open_issues_count":57,"forks_count":186,"subscribers_count":67,"default_branch":"master","last_synced_at":"2024-10-30T02:59:32.192Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://sensorium.github.io/Mozzi/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sensorium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-05-31T06:22:50.000Z","updated_at":"2024-10-28T18:25:51.000Z","dependencies_parsed_at":"2023-02-19T09:50:26.550Z","dependency_job_id":"12f2e03e-2df3-4e17-b5a7-a276ec28e1c4","html_url":"https://github.com/sensorium/Mozzi","commit_stats":{"total_commits":941,"total_committers":25,"mean_commits":37.64,"dds":0.6068012752391073,"last_synced_commit":"93a51c0c04d4f8094131dab85cfd568875864f1b"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sensorium%2FMozzi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sensorium%2FMozzi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sensorium%2FMozzi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sensorium%2FMozzi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sensorium","download_url":"https://codeload.github.com/sensorium/Mozzi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245492724,"owners_count":20624380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T16:00:43.208Z","updated_at":"2025-03-26T13:31:01.600Z","avatar_url":"https://github.com/sensorium.png","language":"HTML","readme":"# Mozzi  \n\n### sound synthesis library for Arduino     \n\nCurrently your Arduino can only beep like a microwave oven. Mozzi brings\nyour Arduino to life by allowing it to produce much more complex and interesting\ngrowls, sweeps and chorusing atmospherics. These sounds can be quickly and easily\nconstructed from familiar synthesis units like oscillators, delays, filters and\nenvelopes.\n\nYou can use Mozzi to generate algorithmic music for an installation or\nperformance, or make interactive sonifications of sensors, on a small, modular\nand super cheap Arduino, without the need for additional shields, message\npassing or external synths.\n\n***\n\n## Features\n-    Available for a wide and growing range of MCUs, with and without inbuilt DACs: Arduino Uno R3 and R4, STM32, Teensy, ESP8266, ESP32, Raspberry Pi Pico, and more.\n-    Configurable sample rate, usually in powers of two (16384 Hz, or 32768 Hz).\n-    Variable control rate from 64 Hz upwards.\n-    Various inbuilt output modes, including 16 bit output to an external DAC.\n-    Allows interfacing to custom output routines, with examples for playing audio on external DAC modules, and even bluetooth.\n-    Useful basic audio toolkit: oscillators, samples, lines, envelopes, scheduling, filtering.\n-    Fast ADC and other cpu-efficient code utilities to help keep audio running smoothly.\n-    Example sketches for easy modification.\n-    Readymade wavetables and a script to convert your own soundfiles for Mozzi.\n-    Mozzi is designed to be easy to use, open source and extendable.\n\n***\n\n## Installation\nThe easiest installation option nowadays is to install Mozzi via the Library Manager in your Arduino application:\n_Arduino➞Sketch➞Include Library➞Library Manager_ type \"Mozzi\" into the search field, then click \"install\".\n\nFor other installation methods (e.g. the development version), see the [Download page](https://sensorium.github.io/Mozzi/download).\n\n## Quick Start\nTo hear Mozzi, wire a 3.5mm audio jack with the centre to the audio out pin for your Arduino as shown in the table below, and the shield to GND on the Arduino.\nPlug into your computer and listen with a sound program like [Audacity](https://audacity.sourceforge.net/). (Or connect any other high-impedance input, like an active speaker)\nTry some examples from the __File \u003e Examples \u003e Mozzi__ menu.\n\nFor more about audio output, including high quality output modes [Mozzi Output tutorial](https://sensorium.github.io/Mozzi/learn/output/).  \n\n### A note for users coming from Mozzi 1.x\nMozzi 2.0 brings a lot of changes under the hood, and is not 100% source compatible with earlier versions of Mozzi. Most sketches should continue to compile, but with\na lot of warnings. A few others will no longer work. See [Porting to Mozzi 2.0](https://sensorium.github.io/Mozzi/learn/porting/) for what to change.\nIf desparate, there is still a \"Mozzi_1\" branch in the git repository which contains the last stable version of Mozzi 1.x and packages for this version can be found on [Github](https://github.com/sensorium/Mozzi/releases/tag/1.1.2), but this will not get any new development. Users still on these versions are encouraged to migrate to Mozzi 2.\n\n## Supported boards, output modes and default pins\n\u003e Table is not necessarily complete. Abbreviations explained below the table. The default output mode is in bold for each row. If stereo is supported, in a mode, the cell PWM-1 has two numbers with the second pin number is given in parentheses (+X).\n\u003e Check the [hardware section of the API-documentation](https://sensorium.github.io/Mozzi/doc/html/hardware.html) for platform specific notes and (pin) configuration options.\n\n| **Board or family / Output mode** | PWM-1 | PWM-2 | PDM | inbuilt DAC | I2S DAC (native) |\n| ---------------------------------------------------- | ---------- | ---------- | ------- | ---------------- | ------------------------ |\n| *ATmega328/168*: Uno (R3), Nano, Pro Mini, Duemilanove, Leonardo, etc.  | **9 (+10)** | 9, 10 | | | |\n| *ATmega32U4*: Teensy, Teensy2, 2++ *B5/B6 correspond to pins 14/15 in Arduino* | **B5 (+B6)** | B5, B6 | | | |\n| *ATmega2560*: Arduino Mega, Freetronics EtherMega, etc.  | **11 (+12)** | 11, 12 |  |  |  |\n| *ATmega1284*: Sanguino  | **13 (+12)** | 13, 12 |  |  |  |\n| Teensy3.x - *note: DAC Pin number depends on model: A14, A12, or A21* |  |  |  | **DAC** |  |\n| Teensy4.x | **A8 (+A9)** |  |  |  |  |\n| *LGT8F328P*: \"Register clone\" of the ATmega328, uses the same code in Mozzi  | **9 (+10)** | 9, 10 |  |  |  |\n| *SAMD*: Arduino Nano 33 Iot, Adafruit Playground Express, Gemma M0 etc.  |  |  |  | **A0/Speaker** |  |\n| *Renesas Arduino Core*: Arduino Uno R4  |  |  |  | **A0** |  |\n| *Arduino MBED Core*: Arduino Giga (only model tested so far in this family)  |  |  | SERIAL2TX | **A13 (+A12)** |  |\n| *STM32 maple core*: Various STM32F1 and STM32F4 boards, \"Blue/Black Pill\"  | **PB8 (+PB9)** | PB8, PB9 |  |  |  |\n| *STM32duino (STM official) core*: Huge range of STM32Fx boards  | **PA8 (+PA9)** | PA8, PA9 |  |  |  |\n| *ESP8266*: ESP-01, Wemos D1 mini, etc. note: Beware of erratic pin labels |  |  | **GPIO2** |  | yes |\n| *ESP32: that has an external DAC (only ESP32) note: Beware of vastly different pin labels across board variants* | 15 (+16)  |  | yes | **GPIO25 (+GPIO26)** | yes |\n| *ESP32-S/C/H/P: that do not have an external DAC note: Beware of vastly different pin labels across board variants* | **15 (+16)**  |  | yes |  | yes |\n| *RP2040*: Raspberry Pi Pico and friends  | **0 (+1)** | 0, 1 |  |  | yes |\n\n\u003e - PWM-1: 1-pin PWM mode (`MOZZI_OUTPUT_PWM`)\n\u003e - PWM-2: 2-pin PWM mode (`MOZZI_OUTPUT_2PIN_PWM`)\n\u003e - PDM: Pulse density modulation, may be either `MOZZI_OUTPUT_PDM_VIA_SERIAL` or `MOZZI_OUTPUT_PDM_VIA_I2S`\n\u003e - inbuilt DAC: `MOZZI_OUTPUT_INTERNAL_DAC`\n\u003e - I2S DAC (native): native support for externally connected I2S DACs (`MOZZI_OUTPUT_I2S_DAC`). Since this requires several, often\n    configurable pins, and is never the default option, no pin numbers are shown in this table.\n\u003e - **All** platforms also support \"external\" output modes (`MOZZI_OUTPUT_EXTERNAL_TIMED` or `MOZZI_OUTPUT_EXTERNAL_CUSTOM`), which allow\n    for connecting DACs or other external circuitry.\n\n***\n\n## Using Mozzi\nHere's a template for an empty Mozzi sketch:\n\n```\n#include \u003cMozzi.h\u003e   // at the top of your sketch\n\nvoid setup() {\n\tstartMozzi();\n}\n\nvoid updateControl(){\n\t// your control code\n}\n\nAudioOutput_t updateAudio(){\n\tMonoOutput::from16Bit( [my_cool_sample] );\n}\n\nvoid loop() {\n\taudioHook();\n}\n```\n\nThere's a detailed example explaining the different parts [here](https://sensorium.github.io/Mozzi/learn/a-simple-sketch/).\n\n\n## Documentation\n\nFor getting started, browse the practical help on the [learn](https://sensorium.github.io/Mozzi/learn/) page on the Mozzi site.  \nAPI reference documentation is available in the doc folder in the Mozzi download and [online](http://sensorium.github.io/Mozzi/doc/html/index.html).  \nStart or look up a topic on the [users forum](https://groups.google.com/forum/#!forum/mozzi-users/).  \nAlso, feel free to submit any issues on the [GitHub Mozzi site](https://github.com/sensorium/Mozzi/issues/).  \nLook for code and usage changes [here](extras/NEWS.txt).  \nFor hardware specific details, including supported features, caveats, and hardware-dependent configuration options,\nrefer to the [Hardware Section of the API-Documentation](https://sensorium.github.io/Mozzi/doc/html/hardware.html).\n\n## Compatibiliy issues\n\n* In most setups, Mozzi claims one or two hardware timers. This may result in incompatibilities with certain libraries, and / or the ability to use timer-based functions such as `analogWrite()`. As the details on this\n  differ a lot between the supported boards, read up on the details - and available workarounds - in the [ardware Section of the API-Documentation](https://sensorium.github.io/Mozzi/doc/html/hardware.html).\n\n* There is also an example on emulating `analogWrite()` on any digitial pin in *Mozzi\u003eexamples\u003e11.Communication\u003eSinewave_PWM_pins_HIFI*.\n\n* The timers can be made available with `stopMozzi()`, which stops audio interrupts, until you call `startMozzi()`.\n\n* Note that it is of utmost importance to write non-blocking code, such that the\n  audio buffer never runs low. Hints on how to do this, including why, and how you\n  should avoid using `delay()`, `analogRead()`, and how to make your code run faster,\n  can be found at [on the learn pages](https://sensorium.github.io/Mozzi/learn/hints/).\n\n\n## Extending Mozzi\n\n### Using external chips to produce the sound\n\nExternal chips (DAC) can also be used on any platform which does not support natively the I2S protocol  using an user defined `audioOutput` function. This can allow a greater audio quality over the native ways to output the sound (PWM for AVR Arduinos and STM32 and 12 bit DAC for Teensy 3.*).\nExamples are provided for the MCP492X DAC (12 bit on SPI) and for the (PT8211) 16 bit stereo DAC using SPI port to emulate the I2S protocol. The latter should be compatible with any DAC using I2S.\n\n### Extending the library itself\n\nIf you enjoy using Mozzi for a project, or have made changes or otherwise extended it, we would be\npleased to hear about it and provide support wherever possible. Contribute\nsuggestions, improvements and bug fixes to the Mozzi wiki on Github, or\nFork it to contribute directly to future developments.\n\nMozzi is a development of research into Mobile Sonification in the\n[SweatSonics](http://stephenbarrass.wordpress.com/tag/sweatsonics/) project.\n\n***\n\n## Contributions / Included Dependencies  \nModified versions of the following libraries are included in the Mozzi download:  \n\n[TimerOne library](http://www.pjrc.com/teensy/td_libs_TimerOne.html)  \n[FrequencyTimer2 library](http://www.pjrc.com/teensy/td_libs_FrequencyTimer2.html) - now a [fork with support for ATmega32u4 processors](https://github.com/sensorium/FrequencyTimer2/)   \n\nMozzi has also drawn on and been influenced by (among many others):  \n\n[xorshift](http://www.jstatsoft.org/v08/i14/xorshift.pdf) random number generator, George Marsaglia, (2003)  \nead~.c puredata external (creb library) Copyright (c) 2000-2003 by Tom Schouten (GPL2)  \n[AF_precision_synthesis](http://adrianfreed.com/content/arduino-sketch-high-frequency-precision-sine-wave-tone-sound-synthesis)\nby Adrian Freed, 2009  \n[Resonant filter](http://www.musicdsp.org/archive.php?classid=3#259) posted to musicdsp.org by Paul Kellett,\nand fixed point version of the filter on [dave's blog of art and programming](http://www.pawfal.org/dave/blog/2011/09/)  \nState Variable filter pseudocode at [musicdsp.org](http://www.musicdsp.org/showone.php?id=23) and [here](http://www.musicdsp.org/showone.php?id=142)  \nVarious examples from [Pure Data](http://puredata.info/) by Miller Puckette  \n[Practical synthesis tutorials](http://www.obiwannabe.co.uk/) by Andy Farnell  \n  \n\n***\n\n## Use and Remix\nMozzi is licensed under a the LGPL version 2.1 or (at your option) any later version of the license.\n\nDisclaimer: This is a human-readable summary of (and not a substitute for) the license.\n- You may copy, distribute and modify the Mozzi library itself provided that you state modifications and license them under LGPL-2.1.\n\n- You may distribute *your own* source code which merely *uses* the Mozzi-API under any licence that you wish.\n\n- Regarding distribution of *binaries* (also inside a hardware project) that include Mozzi, the Arduino FAQ sums up the situation as follows:\n  \"Using the Arduino core and libraries for the firmware of a commercial product does not require you to release the source code for the firmware. The LGPL does, however, require you to make available object files that allow for the relinking of the firmware against updated versions of the Arduino core and libraries. Any modifications to the core and libraries must be released under the LGPL.\"\n\n- Note that using third-party libraries/code - including as shown in some of the Mozzi examples - may introduce additional restrictions.\n","funding_links":[],"categories":["HTML","Libraries","C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsensorium%2FMozzi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsensorium%2FMozzi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsensorium%2FMozzi/lists"}