Getting Started with MMMAudio¶
MMMAudio uses Mojo's Python interop to compile audio graphs directly in your Python programming environment.
Currently Mojo's compiler is MacOS(Apple Silicon) & Linux(x86) only. On Windows, follow the Getting Started with Windows/WSL Guide and return here to follow 3. and 4.
Please see the MMMAudio YouTube Playlist to view the available video tutorials about MMMAudio!
1. Clone the Repository¶
2. Setup the Python Virtual Environment (On Windows, follow the Getting Started with Windows/WSL Guide first, then come back here to get Python correctly configured)¶
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 - we will move to 0.26 soon.
2a. Further Setup of the Environment on MacOS (Apple Silicon Only - Mojo Does not and will not work on Intel Macs)¶
Use your package manager to install portaudio and hidapi as system-wide c libraries. On MacOS this is:
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:
if you have trouble installing/running pyaudio, try this:
1. do this
2. Then this uninstall and reinstall pyaudio (hidapi may be the same).
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.
Some examples are designed to run a complete script. These are all marked. In these cases, the script can be run by pressing the "play" button on the top right of VSCode or just running the script python example.py from inside your virtual environment.
Go to the Examples page to run an example!
4. Make Your Own Sounds¶
When running an example, the Mojo compiler considers the examples directory a "module". This is important because when you make your own directory of files and projects, that directory also needs to be a module.
For your directory to be considered a "module" by the mojo compiler, in addition to your .mojo and .py files, there also needs to be an empty __init__.mojo file in that directory. (See how the examples folder has this file and it is empty. It is there because it needs to be!)
The .gitignore file already ignores two directories, one called "mine" and one called "user_files", so if you make a directory called mine or user_files next to the examples directory, you can put all the .mojo and corresponding .py files in there you want (plus the __init__.mojo file) and git will never accidentally overwrite these directories.
To make a new MMMAudio project, a good approach is to copy and paste a .mojo and .py file pair from the examples directory to get you started. Then modify them!
Note
When running a MMMAudio program in your .py file, the MMMAudio(128, etc)
line has important information that must be correct for compilation
(notice this pattern in the examples):
1) The graph_name corresponds to:
- The name of the .mojo file to search for the audio graph
- AND the name of the struct within that file serving as the main audio graph
In the example below, the file "MyMojoFile.mojo" contains struct MyMojoFile.
This struct must have a .next function with no input arguments that outputs
a SIMD[DType.float64, N] vector of any size (typically N=2) or just a Float64.
2) The package_name corresponds to the folder containing your files:
- Files in MMMAudio/mine use package_name="mine"
- Files in MMMAudio/user_files use package_name="user_files"
- Your folder must be inside the MMMAudio directory and must contain the __init__.mojo file as explained above
This is how all the examples look, so just look at those for "inspiration."