Matchering 2.0: reference-matched mastering as a Python library, Docker image or ComfyUI node

The problem Matchering solves: making one track sound like another

Most mastering tools ask you to make decisions. Matchering asks you for a second file instead. The README frames the whole project around two inputs: a TARGET, described as the track you want to master, and a REFERENCE, described as another track you want your target to sound like. The output is the target with the same RMS, frequency response, peak amplitude and stereo width as the reference.

That framing is the useful part. A producer finishing an album has a concrete problem: eight mixes that drifted apart across weeks of work. If one of them already sounds right, it becomes the reference, and the rest get pulled toward it. The README lists exactly this case, plus making a track sound like a favorite artist's music and running experiments to find new aspects of your own sound.

The audience is split three ways in the README itself. Music producers and audio engineers are pointed at the desktop app or the ComfyUI node. AI mastering startups are pointed at the Docker image. Developers are pointed at the Python library. Those are not marketing tiers; they are genuinely different integration surfaces with different amounts of work behind them.

One caution about the reference. The README quotes a review by Benn Jordan in which the top-line claim, that Matchering beats other AI tools, carries a parenthetical note: by carefully selecting a proper song as reference. The tool is only as good as the file you hand it.

How the matching works, and what it deliberately does not do

The library depends on numpy, scipy, soundfile, resampy and statsmodels, per requirements.txt. That stack tells you what kind of processing this is: spectral analysis and statistical fitting in Python, not a neural network. The README notes that version 2.0 was completely rewritten in Python 3 on an open source stack, with no more MATLAB, and that the project implemented its own open source Hyrax brickwall limiter for it.

The data flow is one shot. You supply a target path, a reference path, and a list of output specifications. The library loads both, measures the reference's level, spectral balance, peak behaviour and stereo width, applies the corresponding corrections to the target, runs the limiter, and writes the files you asked for. There is no iterative pass, no feedback loop, and no model to train.

Because the matching targets are aggregate statistics, the algorithm cannot know that your second verse is too loud relative to your first. It equalizes the whole file toward the reference. That is a real design boundary, not a defect, but it decides which jobs this tool is right for.

The limiter is the part worth reading about before you trust the output. LIMITER_TEST.md exists in the repository root, which suggests the maintainer treated limiter behaviour as something that needed its own verification notes rather than a footnote. LOG_CODES.md similarly documents the log messages the library emits, which is where you find out why a run failed.

Installing matchering and running your first match

The README states the requirement plainly: a 4 GB RAM machine with Python 3.8.0 or higher. On Linux you need libsndfile from your distribution's package manager before anything else, because SoundFile depends on it. Windows and macOS install it automatically.

sudo apt update && sudo apt -y install libsndfile1

If python3-pip is missing on your distribution, the README gives this for Ubuntu:

sudo apt -y install python3-pip

Then the package itself. The README splits the command by platform, and the difference is only the interpreter name.

# Linux / macOS
python3 -m pip install -U matchering

# Windows
python -m pip install -U matchering

MP3 loading is optional and depends on FFmpeg. Without it, work in WAV. With it, the README points at FFmpeg's own install instructions for Windows and macOS, or this on Ubuntu:

sudo apt -y install ffmpeg

The quick example from the README is the shortest path to a result. It masters my_song.wav toward some_popular_song.wav and writes two files at different bit depths.

import matchering as mg

# Sending all log messages to the default print function
# Just delete the following line to work silently
mg.log(print)

mg.process(
    # The track you want to master
    target="my_song.wav",
    # Some "wet" reference track
    reference="some_popular_song.wav",
    # Where and how to save your results
    results=[
        mg.pcm16("my_song_master_16bit.wav"),
        mg.pcm24("my_song_master_24bit.wav"),
    ],
)

Keeping mg.log(print) is worth it on a first run, because the library is otherwise silent and a failed match looks identical to a successful one until you open the file. The examples directory holds five more scripts: basic.py, advanced_results.py, advanced_text_output.py, edited_config.py and with_preview.py. The names map to what they do, and edited_config.py is the one to read if the default matching is close but not right. If you would rather not write Python at all, the README points to a premade matchering-cli command line application and an enhanced fork at kubinka0505/matchering-cli.

Where the reference-matching approach falls short

The most common failure is a bad reference, and it is not a subtle one. If your reference is a loud, heavily limited modern pop master, Matchering will push your acoustic ballad toward that same loudness and spectral tilt. The algorithm has no opinion about whether that is musically appropriate. The README's own quoted review hedges the strongest claim in the project on exactly this point.

Second, the output is a single processed file. If the match overshoots on one section, you cannot ask the library to fix that section. You either change the reference, adjust configuration through the mechanism shown in edited_config.py, or finish the job in a DAW. Matchering is not a replacement for a mastering chain you can automate and revise.

Third, the resource floor is real. A 4 GB RAM machine is the stated minimum, and the dependency list is numpy, scipy, soundfile, resampy and statsmodels. This is not a lightweight utility you drop into a constrained container without thinking about memory.

Fourth, the project's release history deserves a look before you plan around it. The most recent release listed is 2.0.6 from 2022-10-19. The repository's last push was on 2026-07-08, so work is happening, but it is not shipping as tagged releases. If your integration depends on pinned versions and changelogs, plan for the fact that the version number has not moved in years even though the repository has.

Finally, if your goal is to fix a specific problem, such as harsh cymbals or a boomy low end, Matchering is the wrong instrument. It will not isolate that problem. It will move the whole file toward the reference's statistics, and you may end up with a different set of issues.

Matchering against a traditional mastering chain

The honest alternative is not another matching tool. It is a conventional mastering chain: EQ, multiband compression, saturation and a limiter, applied by hand or through presets in a DAW.

The difference in approach is what each one uses as its target. A traditional chain is driven by your ears and your decisions, section by section. Matchering is driven by measurements taken from a second file. That means the traditional chain can fix a problem in one chorus without touching anything else, while Matchering cannot. In exchange, the traditional chain gives you no guarantee that two tracks will end up at the same loudness and spectral balance, which is precisely the guarantee Matchering provides by construction.

For an album where consistency matters more than per-track surgery, the reference approach wins on time. For a single track where you know exactly what is wrong, the manual chain wins on precision. The two are not exclusive; a reasonable workflow is to run Matchering first and then correct in a DAW, though at that point you are paying for both.

Within the project's own ecosystem, the alternative surfaces are the Docker image and the ComfyUI node rather than competing algorithms. The Docker image is aimed at AI mastering startups per the README, with separate setup documents for Windows, macOS and Linux, plus a dedicated updating guide. The ComfyUI node lives in a separate repository, ComfyUI-Matchering, maintained by MuziekMagie. If you want Matchering inside a node graph rather than a Python script, that is the route, and it is a different codebase with its own maintenance.

Licence, upgrades and what GPL-3.0 means for your integration

Matchering is GPL-3.0, confirmed both in the repository metadata and in setup.py, where the license field reads GPLv3 and the classifier is GNU General Public License v3 (GPLv3). The README links the desktop integration through UVR5, a separate application, and the Docker image is distributed as part of this project.

The practical question for a startup is whether you are distributing Matchering or merely using it internally. Calling the library from a script you run on your own machines is a different situation from shipping it inside a product you hand to customers. This article cannot give you legal advice, and the GPL text is the authority, not a README badge. If your business model depends on keeping your mastering pipeline closed, treat the licence as a blocking question to resolve before writing integration code, not after.

Upgrade cost is low on the surface and awkward underneath. The package installs with a pip upgrade, and the Docker image has a documented updating procedure in DOCKER_UPDATING.md. But the newest tagged release is 2.0.6 from 2022-10-19, while the repository's last push was on 2026-07-08. Anyone installing from PyPI gets the 2022 build; anyone wanting current code has to track the branch. That gap is the main operational risk in depending on this project, and it is worth deciding which of the two you are standardising on before you build around it.

Editorial conclusion

Adopt Matchering if you already have a reference track you trust and you need the same treatment applied across a batch of mixes, or if you are embedding mastering into a Python pipeline. Avoid it if you have no reference, if you need per-element control over compression and EQ moves, or if GPL-3.0 does not fit how you ship your own product. Before committing, run the quick example on one real pair of files, listen to the result rather than reading the metrics, and check the LIMITER_TEST.md and LOG_CODES.md files in the repository so you know what the limiter and the log output are telling you.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. sergree/matchering on GitHub