Getting Started with MMMAudio

Mojo's Python interop is still getting smoothed out so things will likely change.

Here is what works now. The instructions are aimed at and have been tested on MacOS (currently Mojo's compiler is MacOS & Linux only).

1. Clone the Repository

git clone https://github.com/spluta/MMMAudio.git

2. Setup the Environment

cd into the root of the downloaded repository, set up your virtual environment, and install required libraries. this should work with python 3.12 and 3.13. If you find it does or doesn't work with other versions let us know.

depending on your system set up, you may need to explicitly specify the Python version here, eg: 'python3.13 -m venv venv'

python -m venv venv 
source venv/bin/activate

pip install numpy scipy librosa pyautogui torch mido python-osc python-rtmidi matplotlib PySide6

install modular's max/mojo library the main branch is tied to Mojo 0.25.6.1

pip install mojo==0.25.6.1

2a. Setup the Environment on MacOS

Use your package manager to install portaudio and hidapi as system-wide c libraries. On MacOS this is:

brew install portaudio
brew install hidapi

MMMAudio uses pyAudio (portaudio) for audio input/output and hid for HID control.

Then install pyaduio and hid in your virtual environment with your venv activated:

pip install hid pyaudio

if you have trouble installing/running pyaudio, try this: 1. do this 2. Then this uninstall and reinstall pyaudio (hidapi may be the same).

2b. Setup the Environment on Windows/WSL2 with Ubuntu

Here are some hints to get the audio samples running under Windows/WSL2. I used the Unbuntu distro, but if you adapt the package manager, it will also work on other distributions.

Use your package manager to install portaudio and hidapi as system-wide c libraries. On MacOS this is:

sudo apt update
sudo apt install libportaudio2 portaudio19-dev
sudo apt install libhidapi-hidraw0 libhidapi-dev
sudo apt install pulseaudio

Use your package manager to install ALSA runtime and ASLA utilities as system-wide c libraries. On Ubuntu this is:

sudo apt install alsa-utils
sudo apt install libasound2-dev

Verify the installation. You should see a version number

aplay --version
pkg-config --modversion alsa

To make the Windows audio devices "visible" inside WSL2, please install and configure PulseAudio bridge as follows:

Use youe packagemanger to install PulseAudio. On Ubuntu this is:

sudo apt install pulseaudio alsa-utils

Create a sound config rc file in your user home directory with the follwing content: ~/.asoundrc

pcm.!default {
    type pulse
}
ctl.!default {
    type pulse
}

Start pulseaudio and verify that the WSLg PulseAudio server is reachable:

pulseaudio --start
ls -l /mnt/wslg/PulseServer

Check also that PortAudio detects PulseAudio

pactl info

Now run your MMMAudio script WITHOUT running pulseaudio --start and enjoy the sound:

python3 examples/DefaultGraph.py

3. Run an Example

The best way to run MMMAudio is in REPL mode in your editor.

to set up the python REPL correctly in VSCode: with the entire directory loaded into a workspace, go to View->Command Palette->Select Python Interpreter. Make sure to select the version of python that is in your venv directory, not the system-wide version. Then it should just work.

Before you run the code in a new REPL, make sure to close all terminal instances in the current workspace. This will ensure that a fresh REPL environment is created.

Go to the Examples page to run an example!