[path: home/electronics/meap/documentation/software]

MEAP software reference

Mozzi

The core of MEAP's sound engine is the Mozzi library, which is very thoroughly documented on their website. All functions from the Mozzi library work in MEAP as do all Mozzi example programs (though you will need to fit them into the MEAP template program to talk to MEAP's audio codec).

meap_mozzi	modified Mozzi classes
meap_main	core MEAP class and its methods
meap_instruments	plug and play instruments
meap_stk	an in-progress port of the Synthesis Toolkit

MEAP extensions of Mozzi classes

The Mozzi library is designed to generate audio on very limited platforms such as the Arduino UNO and as such, the functions are designed to be as lightweight and efficient as possible. The ESP32-S3 chip used on MEAP boards is a comparatively more powerful chip and does not need to have these limitations so a few Mozzi functions have been modified to allow MEAP to take full advantage of them. It is recommended to use the MEAP function over the Mozzi function that it replaces.

mSample
mOscil

class: mSample

Description: A copy of Mozzi's Sample class with a few behind the scenes changes. mSample supports samples of arbitrary length unlike Sample. mSample can also be configured to use 8-bit or 16-bit samples while Sample can only use 8-bit samples. Aside from that, all class methods documented on Mozzi's website still apply.
Constructor arguments: (const T *TABLE_NAME)
- TABLE_NAME: the name of the array the mSample will be using. This can be found in the table ".h" file if you are using a table made for Mozzi by the int8_t2mozzi.py python script in Mozzi's python folder or the online tool linked below.
Template: template <uint64_t NUM_TABLE_CELLS, unsigned int UPDATE_RATE, class T = int8_t>
- NUM_TABLE_CELLS:This is defined in the table ".h" file the mSample will be using. The sound table can be arbitrary length for mSample. It's important that NUM_TABLE_CELLS is either a literal number (eg. "8192") or a defined macro, rather than a const or int, for the mSample to run fast enough.
- UPDATE_RATE: This will be AUDIO_RATE if the mSample is updated in updateAudio(), or CONTROL_RATE if it's updated each time updateControl() is called. It could also be a fraction of CONTROL_RATE if you are doing some kind of cyclic updating in updateControl(), for example, to spread out the processor load.
- T(default: int8_t): Bit-rate of the table being used, most likely int8_t or int16_t.
Source: mSample.h
Note:online tool for converting audio files to mSample arrays

Example declaration:

#include <tables/Glass_Piano_C.h>
mSample<Glass_Piano_C_NUM_CELLS, AUDIO_RATE, int16_t> my_sine(Glass_Piano_C_DATA);

class: mOscil

Description: A version of Mozzi's Oscil that has been modified to support 16-bit waveforms. All class methods from Oscil are directly compatible.
Constructor arguments: (const T *TABLE_NAME)
- TABLE_NAME: the name of the array the mOscil will be using. This can be found in the table ".h" file if you are using a table made for Mozzi by the int8_t2mozzi.py python script in Mozzi's python folder.
Template: <uint16_t NUM_TABLE_CELLS, uint32_t UPDATE_RATE, class T = int8_t>
- NUM_TABLE_CELLS: This is defined in the table ".h" file the mOscil will be using. It's important that it's a power of 2, and either a literal number (eg. "8192") or a defined macro, rather than a const or int, for the mOscil to run fast enough.
- UPDATE_RATE: This will be AUDIO_RATE if the mOscil is updated in updateAudio(), or CONTROL_RATE if it's updated each time updateControl() is called. It could also be a fraction of CONTROL_RATE if you are doing some kind of cyclic updating in updateControl(), for example, to spread out the processor load.
- T(default: int8_t): Bit-rate of the table being used, most likely int8_t or int16_t.
Source: mOscil.h

Example declaration:

#include <tables/sin8192_int8.h>
mOscil<SIN8192_NUM_CELLS, AUDIO_RATE, int8_t> my_sine(SIN8192_DATA);

meap_main: the core class and errata

Much of the MEAP library is packaged within the Meap class. This class handles communicating with MEAP's hardware: potentiometers, MIDI I/O etc. It also provides some general purpose functions that you may find useful. These functions are all part of the Meap class that is declared globally in all example MEAP programs so they must be accessed through that class (for example meap.irand(0, 1) rather than just irand(0, 1))

Structs:

method: int64_t Meap::irand(int64_t howsmall, int64_t howbig)

Description: Generates a random integer within a specified range, inclusive of the limit numbers.
Arguments:
- int64_t howsmall: lower limit of output range, inclusive.
- int64_t howbig: upper limit of output range, inclusive.
Return:
- int64_t: the random number
Source: Meap_classes.h

method: float Meap::frand()

Description: Generates a random floating point number between 0 and 1, inclusive, with four decimal points of precision
Return:
- float: the random number
Source: Meap_classes.h

method: StereoSample Meap::pan2(int64_t sample, uint8_t pos);

Description: Performs stereo equal-power panning
Arguments:
- int64_t sample: mono audio sample to be panned
- uint8_t pos: panning position between 0 and 255, with 0 corresponding to fully left, 127 in the center and 255 fully right
Return:
- StereoSample: Struct containing left and right output samples, accessed at .l and .r respectively
Source: Meap_classes.h

Example usage:

int64_t out_sample = my_osc.next(); // grab a sample from an oscillator
StereoSample panned_sample = meap.pan2(out_sample, 90); // pan sample slightly to the left
return StereoOutput::fromNBit(8, panned_sample.l, panned_sample.r); // send outputs to DAC

method: float Meap::midiPulseMicros(float tempo)

Description: Calculates the length (in microseconds) of a MIDI clock pulse (at 24PPQ) at a specified tempo
Arguments:
- float tempo: in beats per minute
Return:
- float: number of microseconds in one MIDI clock pulse at the specified tempo
Source: Meap_classes.h

method: float Meap::tempoToPeriod(float tempo)

Description: Calculates the length (in milliseconds) of a quarter note at a specified tempo
Arguments:
- float tempo: in beats per minute
Return:
- float: number of milliseconds in one quarter note at the specified tempo
Source: Meap_classes.h

method: void Meap::setCodecGain(uint16_t gain);

Description: Sets master volume of DAC output. Not recommended to be used for on the fly volume adjustments because audible glitches can occur when it changes.
Arguments:
- uint16_t gain: gain of DAC. Between 60 and 252, with 60 being the maximum volume and decreasing in 0.5dB steps as the number increases.
Source: Meap_classes.h