I Built an Open-Source Adaptive Mastering Tool for AI Music

Mastering gets described as the final polish.

That is true. But it also makes it sound simpler than it really is.

Turn up the loudness. Add some EQ. Compress it. Throw a limiter on the end. Done.

Not quite. 😄

A good mastering chain should first answer a much more important question:

What does this track actually need?

That question is the reason I built Adaptive Master.

It is a local, open-source mastering engine written in Python. I originally built it around the problems I kept hearing in AI-generated music, especially Suno exports, but the engine works with regular stereo mixes too.

The project is available on GitHub under the MIT license, so you can use it, study it, modify it, break it, improve it, or build something completely different on top of it.

GitHub: github.com/alesmcgregor/Mastering

The basic idea: measure first, process second

I didn't want another mastering script that blindly applies the same EQ curve and limiter settings to every song.

A piano ballad and a dense electronic track are not the same signal.

So Adaptive Master starts with analysis.

It measures things like:

The spectral analysis also avoids a common stereo-analysis mistake: simply summing left and right channels.

Instead, channel power is measured separately before being averaged. That means an out-of-phase stereo signal doesn't magically disappear from the analysis.

This matters more than it sounds.

The mastering flow

The engine follows a pretty simple philosophy:

1. Analyze the original track.

2. Build a processing plan from the measurements.

3. Apply only the processing that was actually triggered.

4. Measure the final WAV again and verify that the result still respects the technical limits.

So the mastering chain is not completely fixed.

If the low-mids are fine, there is no reason to attack them.

If the stereo image is already healthy, there is no reason to widen it.

If the track is already dense, pushing it harder into a limiter probably won't make it better.

Sometimes the smartest DSP decision is doing almost nothing.

Suno Adaptive

The profile I use most for AI-generated material is called Suno Adaptive.

Its normal loudness target is adaptive rather than fixed. The engine chooses roughly between -14 and -12 LUFS depending on the source dynamics.

The true-peak ceiling is -1 dBTP, and limiter pressure is intentionally restricted instead of chasing the loudness target at any cost.

That last part is important.

If reaching a target means destroying the dynamics, the engine is allowed to stay quieter.

Because LUFS is a measurement.

It is not a high score.

A few things happening under the hood

There are some small corrective tools inside the chain that only activate when the analysis says they are needed.

Short clipping repair

If the engine detects consecutive near-full-scale samples, it can repair very short clipped regions.

The repair is intentionally limited to roughly 3 milliseconds and uses slope-aware cubic interpolation.

This isn't magic restoration.

Once information has genuinely been destroyed by clipping, no algorithm knows what the original waveform really looked like.

This feature is more like smoothing a small damaged edge than rebuilding the whole painting.

Dynamic mud control

When the 120–400 Hz area becomes congested, the engine can reduce that band dynamically instead of applying a permanent EQ cut.

The channels are linked, so the stereo balance isn't pulled around independently.

Maximum reduction is intentionally small — around 1.2 dB.

That is a recurring theme in this project:

small corrections > dramatic corrections

Harshness control

Suno Adaptive can also watch the roughly 2.5–8 kHz region for aggressive peaks.

Again, this isn't a static treble cut.

Reduction appears when the problem appears and disappears when it doesn't.

The correction is capped at roughly 1.4 dB.

I would rather leave a little imperfection than flatten the personality of a track.

Stereo shaping

Stereo widening is another thing I wanted to treat carefully.

The engine first checks stereo correlation and Side/Mid energy.

Only a track that is unusually narrow and phase-safe becomes a candidate for widening.

Even then, the change is small: roughly 5–8% on the upper Side information.

The low end below roughly 90 Hz stays centered.

Because making everything "super wide" is a very quick way to make something sound impressive for ten seconds and weird everywhere else.

Reference mastering — but with a leash

Reference tracks are useful.

Services such as Songmastr take a strongly reference-driven approach. Songmastr is built around Matchering and describes matching properties such as frequency response, RMS, peak level and stereo width to the supplied reference.

Adaptive Master supports references too, but I intentionally made the behavior more conservative.

When you provide a reference track, the engine compares broad tonal regions and applies only about 35% of the difference, within strict gain limits.

It also limits the reference-derived loudness target to a safe range.

Why?

Because I don't necessarily want:

"Make my track become this track."

I want:

"Show me where my track is very different from this reference, then move it carefully in that direction."

A reference is a compass, not a photocopier.

And yes, reference choice matters. Comparing a minimal instrumental to a vocal-heavy commercial pop master can give you completely misleading information. Songmastr makes the same practical point in its own reference guidance.

The profiles

You can keep things simple or experiment.

The commercial-service-inspired profiles are not copies of proprietary algorithms.

Their internal DSP parameters are not public.

They are independent profiles based on publicly described behavior and my own calibration.

What happens at the end?

After EQ, optional dynamic processing and gain staging, the signal reaches a true-peak brickwall limiter.

But processing doesn't stop there.

The rendered result is independently measured again using 4× oversampling.

If the reconstructed true peak still exceeds the intended ceiling, the output level is corrected before export.

Then the master is written as a 24-bit WAV with TPDF dither.

Alongside the audio file, Adaptive Master creates a JSON report containing the before measurements, processing decisions, render information, final measurements and warnings.

So instead of:

"The AI mastered it."

you can actually inspect what happened.

I like that much better.

Installing it

The project currently has the smoothest setup experience on Windows.

You need Git and Python available on your computer.

Open a terminal and clone the repository:

git clone https://github.com/alesmcgregor/Mastering.git
cd Mastering

On Windows, run:

setup.bat

The setup script creates a local Python virtual environment and installs the pinned dependencies from requirements.txt.

The project currently uses:

NumPy · Spotify Pedalboard · pyloudnorm · SciPy · Flask · Waitress

After installation, start the web interface:

web.bat

Your browser should open:

http://127.0.0.1:8765

The server listens only on localhost, so the mastering interface isn't exposed publicly by default. Uploaded audio stays in the local project workspace rather than being sent to an external mastering API.

That was important to me.

Your unfinished music can stay on your machine.

Using the command line

The browser interface is easier, but the CLI is useful for automation.

Basic mastering:

master.bat "C:\Music\track.wav"

Suno Adaptive:

master.bat "C:\Music\track.wav" --profile suno-adaptive

With a reference:

master.bat "C:\Music\track.wav" --profile suno-adaptive --reference "C:\Music\reference.wav"

You can also run analysis without creating a master:

.venv\Scripts\python.exe master.py "C:\Music\track.wav" --analyze-only

That generates a report showing the measurements and the mastering plan the engine would have chosen.

For me, this is also a useful way to learn mastering.

You can see the numbers, listen to the track, make a hypothesis, process it and compare the result.

The web interface

The local web app adds a friendlier workflow around the same engine.

You can drag in a song, optionally add a reference, choose a profile, change intensity and tonal direction, and override LUFS or true-peak targets if you know exactly what you want.

After processing, the interface gives you before/after measurements and an Original/Mastered A/B comparison.

The application also limits processing to one mastering job at a time while keeping the interface responsive through its local job queue.

No cloud account.

No upload queue somewhere on the internet.

Just localhost and your CPU doing the work.

My laptop may complain occasionally, but at least it knows why. 🙂

One important limitation

Mastering cannot fix everything.

A stereo WAV does not contain the original vocal stem, kick stem, guitar stem and synthesizer channels.

If the vocal is buried six decibels too low, mastering doesn't suddenly gain access to the mixer.

If clipping destroyed information, that information isn't hiding somewhere waiting to be recovered.

And an algorithm cannot perfectly understand the artistic intention of every genre from one stereo file.

That is why Adaptive Master deliberately avoids overly surgical decisions.

It measures what it can measure.

It makes bounded decisions.

And then you still use your ears.

That last step remains undefeated.

Open source means this isn't finished

Adaptive Master is licensed under MIT.

That means the project isn't supposed to be a closed black box.

Fork it.

Read the DSP.

Test it on weird material.

Build another profile.

Improve the measurements.

Find something I did badly and send a better implementation.

There are already automated tests covering things such as true-peak ceilings, short-clip repair, stereo behavior, dense-source protection, 24-bit output, reference handling and profile controls.

But technical tests cannot prove that something sounds good.

Music still needs humans for that part.

And honestly, I hope it stays that way.

Project: Adaptive Master
Source: github.com/alesmcgregor/Mastering
License: MIT