Installation

Python version: 3.10, 3.11, 3.12, 3.13

Choose the installation that fits your use case:

I want to…	Install
Get started quickly — test with recorded audio or MIDI files	`pip install pymatchmaker`
Use a locally connected microphone or MIDI keyboard	`pip install pymatchmaker[devices]`
Develop or contribute to matchmaker	`pip install -e ".[dev]"` (see below)

Option 1: Base install

pip install pymatchmaker

Supports simulation mode: run online alignment against recorded audio or MIDI performance files.

Note: Requires Fluidsynth to be installed on your system:
conda install -c conda-forge fluidsynth

Option 2: Live device support

pip install pymatchmaker[devices]

Adds PyAudio and python-rtmidi for real-time input from a locally connected microphone or MIDI keyboard.

Note: pyaudio requires PortAudio to be installed on your system:
conda install -c conda-forge fluidsynth portaudio

Option 3: Development install (from source)

For contributors or anyone who wants to modify the source code. Requires conda.

# Clone the repository
git clone https://github.com/pymatchmaker/matchmaker.git
cd matchmaker

# Create and activate a conda environment
conda create -n matchmaker python=3.12
conda activate matchmaker

# Install system dependencies
conda install -c conda-forge gcc=12.1.0 glib fluidsynth portaudio

# Install matchmaker in editable mode with all dev dependencies (includes [devices])
pip install -e ".[dev]"

Note: partitura will download MuseScore_General.sf3 (a free soundfont) on first use. This may take a moment.

Known Setup Issues

Missing Visual C++ build tools (on Windows)

Download vs_BuildTools.exe from https://visualstudio.microsoft.com/visual-cpp-build-tools/ and run:

vs_buildtools.exe --norestart --passive --downloadThenInstall --includeRecommended --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Workload.MSBuildTools

Issues with Fluidsynth and pyfluidsynth on Windows

On Windows, pyfluidsynth expects fluidsynth.exe to be located in C:\tools\bin (some users report C:\tools\fluidsynth\bin):

Download the ZIP for your Windows version from https://github.com/FluidSynth/fluidsynth/releases/latest
Extract the contents to C:\tools (or wherever pyfluidsynth expects the executable).

Using Fluidsynth installed from Homebrew on macOS

We recommend installing Fluidsynth via conda in a dedicated environment. If you use the Homebrew-installed Fluidsynth instead, you may encounter ImportError("Couldn't find the FluidSynth library.") with pyfluidsynth. See this Stack Overflow answer for a fix.