🎚️ Open Source Audio Matching and Mastering


Buy Me A Coffee

Matchering 2.0

License PyPI Version PyPI Python Versions Mentioned in Awesome Python Code style: black

Matching + Mastering = ❤️

Matchering 2.0 is a novel Containerized Web Application and Python Library for audio matching and mastering.

It follows a simple idea - you take TWO audio files and feed them into Matchering:

  • TARGET (the track you want to master, you want it to sound like the reference)
  • REFERENCE (another track, like some kind of "wet" popular song, you want your target to sound like it)

Our algorithm matches both of these tracks and provides you the mastered TARGET track with the same RMS, FR, peak amplitude and stereo width as the REFERENCE track has.

You can try out Matchering yourself without having to install it, thanks to the hosting provided by Moises.ai.

Watch the video:

Matchering 2.0 Promo Video

So Matchering 2.0 will make your song sound the way you want! It opens up a wide range of opportunities:

  • You can make your music instantly sound like your favorite artist's music
  • You can make all the tracks on your new album sound the same very quickly
  • You can find new aspects of your sound in experiments
  • You can do everything as you want! Because of Your References, Your Rules.™ (just a little nostalgic note) 🤭

Matchering WEB GIF Animation

Differences from the previous major version:

  • Completely rewritten in Python 3, based on open source tech stack (no more MATLAB)
  • Our own open source brickwall limiter was implemented for it
  • Processing speed and accuracy have been increased
  • Now it is the library that can be connected to everything in the Python world

Installation and Usage

If you are a music producer or an audio engineer, choose the Docker Image.

If you are a developer, choose the Python Library.

Docker Image - The Easiest Way

Matchering 2.0 works on all major platforms using Docker.

Choose yours





If you need to update the version of the installed Docker Image, follow these instructions.

Python Library - For Developers


4 GB RAM machine with Python 3.6.0 or higher is required


Matchering 2.0 depends on the SoundFile library, which depends on the system library libsndfile. On Windows and macOS, it installs automatically. On Linux, you need to install libsndfile using your distribution's package manager, for example:

sudo apt update && sudo apt -y install libsndfile1


On some Linux distributions, python3-pip is not installed by default. For example use this command on Ubuntu Linux to fix this:

sudo apt -y install python3-pip

Matchering Python Package

Finally, install our matchering package:

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

# Windows
python -m pip install -U matchering

(Optional) FFmpeg

If you would like to enable MP3 loading support, you need to install the FFmpeg library. For example use this command on Ubuntu Linux:

sudo apt -y install ffmpeg

Or follow these instructions: Windows, macOS.

Quick Example

import matchering as mg

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

    # The track you want to master
    # Some "wet" reference track
    # Where and how to save your results

You can find more examples in the examples directory.

Or you can use premade Matchering 2.0 Command Line Application: matchering-cli.

A Coffee

If our package saved your time or money, you may:

Buy Me A Coffee

Thank you!


  • python version

    python version

    Create a python re-write of matchering, because matlab is not that easy to acquire for normal user.


    • simplified error messages and display messages
    • no explicit memory cleaning operation, but done by in-place operation and python own garbage collection
    • vectorized rms calculation
    • display rms coefficient in db scale
    • replace smoothing operation with average filter when filtering match fft . May change to 'loess' method in the future
    • no limiter. I haven't add the limiter function yet, but this can be easily done in the future

    Have run this script on my laptop very smoothly, but I can't compare the differences cuz I currently don't have matlab installed device (the last time I use matlab was in college lol).

    opened by yoyololicon 34


    Request Method: | GET -- | -- 3.0.2 RuntimeError Error opening './media/goody/mastered/my_song_master_16bit.wav': System error. /home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python3.6/site-packages/soundfile.py in _error_check, line 1357 /home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/bin/python 3.6.9 ['/home/goodness/Documents/django_dev/MeshakProj', '/home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python36.zip', '/home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python3.6', '/home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python3.6/lib-dynload', '/usr/lib/python3.6', '/home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python3.6/site-packages'] Thu, 30 Jan 2020 10:52:20 +0100

    opened by GoodnessEzeokafor 8
  • OSError: sndfile library not found

    OSError: sndfile library not found

    Get this error when running heroku run python manage.py makemigrations Heroku Deployment it works fine locally

    opened by GoodnessEzeokafor 8
  • Any plan on create a demo site with matchering?

    Any plan on create a demo site with matchering?

    Thanks for your hard working on containerize the whole project ! I want to say congrats to everyone who have participated in it, thank you :clap: I would also like to ask is there any plan on create a demo site so everyone can access the serverce ?

    BTW I have run it on a private docker server and it works well, but the loading time is a little bit long though (~= 10 seconds).

    opened by yoyololicon 6
  • DOCKER_MACOS.md may be outdated

    DOCKER_MACOS.md may be outdated

    DOCKER_MACOS.md guide may be outdated / incorrect. If you have some macOS device, feel free to update this guide.

    Thank you.

    help wanted 
    opened by sergree 5
  • Target audio stream error

    Target audio stream error

    I followed the Python instructions, but I'm getting a "ERROR: Unknown audio stream in target file" - what is wrong? They're wav :(

    opened by Raprodent 5
  • GET request possible for usage with Docker image?

    GET request possible for usage with Docker image?

    Hi, I would like to automate some tasks to process our rehearsel recordings (ideation for new songs). I currently use the docker image and I wondered whether it would be possible to make a GET request to the site supplying reference and target files/filepaths and receive the resulting file (or automatically put it into a shared folder). E.g. just call

    I know I could use the python version and the CLI but I would like to keep the docker version for simplicity.

    More background: I mainly use the same 3 reference tracks from our own album and this way I could create a script to copy the recordings from the SD card, show a simple GUI to select the reference track for each recording and provide the names, call matchering, convert the resulting audio file to mp3 and copy it to our band sharing file space.

    opened by boriswerner 5
  • 4001: Audio stream error in the TARGET file

    4001: Audio stream error in the TARGET file

    Request Method: | GET -- | -- 3.0.2 ModuleError 4001: Audio stream error in the TARGET file /home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python3.6/site-packages/matchering/loader.py in load, line 42 /home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/bin/python 3.6.9 ['/home/goodness/Documents/django_dev/MeshakProj', '/home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python36.zip', '/home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python3.6', '/home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python3.6/lib-dynload', '/usr/lib/python3.6', '/home/goodness/.local/share/virtualenvs/MeshakProj--GI6wqXg/lib/python3.6/site-packages'] Thu, 30 Jan 2020 09:19:52 +0100

    opened by GoodnessEzeokafor 4
  • Getting the mastered track

    Getting the mastered track

    Hello i'm back again is there a way to get the mastered tracks outside the mg.process function

    opened by GoodnessEzeokafor 4
  • matchering.log.exceptions.ModuleError: 4002: Track length is exceeded in the TARGET file

    matchering.log.exceptions.ModuleError: 4002: Track length is exceeded in the TARGET file


    I'm trying to use matchering to master a song but ran into an error.

    Loading and analysis
    Loading the TARGET file: 'target.wav'...
    The TARGET file is loaded
    TARGET audio length: 99615480 samples (0:37:38)
    Traceback (most recent call last):
      File "master.py", line 9, in <module>
      File "/Users/highcenoid/Documents/TCSP/mastered/env/lib/python3.7/site-packages/matchering/core.py", line 53, in process
        target, target_sample_rate = check(target, target_sample_rate, config, 'target')
      File "/Users/highcenoid/Documents/TCSP/mastered/env/lib/python3.7/site-packages/matchering/checker.py", line 102, in check
      File "/Users/highcenoid/Documents/TCSP/mastered/env/lib/python3.7/site-packages/matchering/checker.py", line 57, in __check_length
        raise ModuleError(error_code_max)
    matchering.log.exceptions.ModuleError: 4002: Track length is exceeded in the TARGET file
    At first I just loaded the target and reference files, then I cut the reference file to be exactly as long as the target but was still getting the error.
    opened by reyesvicente 3
  • How to work with mp3s?

    How to work with mp3s?

    Hello guys! matchering is an amazing lib, thank you very much!

    I wanna try to play around with some mp3 files in matchering but can't find any documentation about it

    I want to upload a target and reference (both mp3) and extract the mastered target as mp3 as well. Is it possible? where can I find information about the python syntax to make it possible?

    Thank you!

    opened by nothingcomeseasy 3
  • Need Surround (vs. Stereo) configs

    Need Surround (vs. Stereo) configs

    Please consider supporting more than stereo, e.g. 12 channels for Dolby Atmos 7.1.4 etc.

    reference track can still be stereo

    opened by dts350z 2
  • Generate Presets for future uses

    Generate Presets for future uses

    First I wanted to say that Matchering 2.0 is probably the best tool I've ever used in a while.

    But I have a question - would it be possible to make it so that after matchering a track (say: use unmastered instrumental version of a song + the mastered original song as reference) we could save the preset (all the effects) used to master the instrumental so that we can then later upload the individual stems of that song and master them the same way? Uploading the stems individually and using the original mastered song as a reference would yield much different results than if we were able to keep the effects used in the previous matchering.

    I hope that made any sense, and I would love it if it's possible for you (or anyone) to implement this.

    opened by lucellent 1
  • [Discussion] Desktop Application 🖥

    [Discussion] Desktop Application 🖥

    I've been looking into different technologies for making Rust desktop applications because that's personally something I want to get into. I think that Flutter is one of the most promising GUI frameworks around right now, and I just yesterday discovered nativeshell which is a way to build desktop applications with Rust and Flutter. I was thinking about what might be a good demo application for me to build using nativeview and then I thought of Matchering.

    If I get the time, I might try to make a native desktop application for Matching, but I've still got to figure out the best way to embed Matching in a desktop application without requring Python to be installed. I heard that you had experimented with a Rust version of matchering, which would be the easiest way to get matchering embedded, but if that isn't ready yet then that won't be an option.

    The other option is to embed the Python interpreter in Rust. This should work, and I've done it before in smaller use-cases, I just have to look into it more.

    I wanted to open this issue to start the discussion and ask whether or not the Rust version of matchering is anywhere close to usable or if I should just try to embed the Python interpreter.

    opened by zicklag 2
  • Clips on final result

    Clips on final result

    Hi sergree, I have noticed that sometimes, for instance when the target audio has bad resolution, the final result has clips. I really appreciate your work and I have seen your video tutorial on 'How it Works'. Correct me if I am wrong, your procedure of chopping the audio seems to me related to the fact that you have fixed the FFT number of samples in order to compute the mid FIR filters. This procedure resembles to me as trying to mimic the STFT algorithm. Since you have fixed the FFT number of samples you probably do convolutions on the chopped audio samples that you used to compute the FFTs or to the full audio file performing a zero padding technique . This procedure it's probably the cause of the clips in the final result. Why you don't consider the Gabor transform instead? Setting the standard deviation of the Gaussian and the number of centers in order to control time-frequency resolution. This procedure is done to the full audio and should not be affected by the picket fence effect. If the problem is the efficiency of the algorithm you should look for a GPU implementation. Best regards

    opened by nicolasegala 1
  • Potential Bug Risks and Anti-Patterns

    Potential Bug Risks and Anti-Patterns


    Hi 👋 I ran the DeepSource static analyzer on the forked copy of this repo and found some interesting code quality issues which are available here.

    The Static Code Analysis Tool found potential bugs and anti-patterns in the Code, that can be detrimental at a later point in time with respect to the Project. DeepSource helps you to automatically find and fix issues in your code during code reviews. This tool looks for anti-patterns, bug risks, performance problems, and raises issues.

    Some of the notable issues are :

    • f-string used without any expression here
    • Unnecessary delete statement in a local scope here
    • Function/method with an empty body here

    There are plenty of other issues in relation to Bug Discovery and Anti-Patterns which you would be interested to take a look at. If you would like to integrate DeepSource to autofix some of the common occurring issues, I can help you set that up :)

    opened by powerexploit 2
  • Hardware assisted virtualization and data execution protection must be enabled

    Hardware assisted virtualization and data execution protection must be enabled

    Hi, I get this error, but I do have virtualization turned on Because I'm running VMware and Bluestacks on my own computer https://imgur.com/a/DMgrSjn

    opened by johnnygodsa 1
  • dithering about

    dithering about

    Hi @sergree ! I would like to propose the enhancement of a dithering option for anyone downsampling. This is a necessary final mastering touch for anyone who uses 24/32/ bit mixes and masters down to 16 or 24. It takes care of harshness added by aliasing when downsampling. This might be something to consider as an automatic addition in the web UI w/ option to turn it off, like with the limiter. There are great open source dithers from Chris Johnson at AirWindows. I don't actually use these because I have some nice proprietary ones I paid for already, but Chris's stuff is top notch. Look at this quick guide first to narrow down the field (he has a bunch of special purpose dithers along with a few general ones). On the page, leave the first search box empty, then for the next three dropdowns pick "type", "mastering", and "dithers". This will give you a quick short guide, then look up Chris's in depth description for the ones you think might be useful. I hope this is a welcome suggestion!

    opened by rcrath 2
  • Matchering as Plugin?

    Matchering as Plugin?


    i love Matchering but it would be so great, if you could use it as a plugin in the masterbus of the daw. I use Linux and Mixbus 32 Software. Is this planned in the future?

    Best wishes Daniel

    help wanted 
    opened by basementmedia2 2
  • Improve our brickwall limiter

    Improve our brickwall limiter

    While our EQ matching is a strong point of Matchering, our blackwall limiter remains to be a bottlneck.

    Received this feedback recently: YT Review

    I completely agree with our user, I also sometimes got similar results when the reference was very, very loud.

    Here is our limiter code.

    Here are its tests.

    It already shows good results, which are very close to the proprietary quality, but, apparently, something is missing. The community would be very grateful if there was a contributor who can bring the quality of our brickwall limiter even higher.


    help wanted 
    opened by sergree 13
  • 2.0.3(Nov 10, 2020)

    Long time no see, time to update.

    • (Docker) Windows 10 Home support
    • (Core) Ubuntu 20.04 support
    • Dependencies update: everything should be more stable and faster now
    • Description & installation instructions update
    • Black code formatting

    Yes, I have some plans and small prototypes of Rust native binaries, but so far everything is very vague.

    Source code(tar.gz)
    Source code(zip)
  • 2.0.2(Feb 10, 2020)

  • 2.0.1(Feb 10, 2020)

  • 2.0.0(Jan 12, 2020)

    Matchering 2.0 initial release!

    Differences from the previous major MATLAB version:

    • Completely rewritten in Python 3, based on open source tech stack (no more MATLAB)
    • Our own open source brickwall limiter was implemented for it
    • Processing speed and accuracy have been increased
    • Now it is the library that can be connected to everything in the Python world

    Differencies from the @yoyololicon version:

    • Modular architecture
    • PyPI library
    • Fixed some inaccuracies and errors in the algorithm
    • MP3 support with FFmpeg
    Source code(tar.gz)
    Source code(zip)
Sergey Grishakov
Audio Mastering Robin Hood
Sergey Grishakov
Python library for audio and music analysis

librosa A python package for music and audio analysis. Documentation See https://librosa.org/doc/ for a complete reference manual and introductory tut

librosa 4.9k Jan 15, 2022
All-In-One Digital Audio Workstation and Plugin Suite

How to install Windows Mac OS X Fedora Ubuntu How to Build Debian and Ubuntu Fedora All Other Linux Distros Mac OS X Windows What is MusiKernel? MusiK

j3ffhubb 111 Sep 18, 2021
Audio Editor

Audacity is an easy-to-use, multi-track audio editor and recorder for Windows, Mac OS X, GNU/Linux and other operating systems. Developed by a group o

Audacity 7k Jan 20, 2022
The fre:ac audio converter project

fre:ac - free audio converter fre:ac is a free and open source audio converter. It supports audio CD ripping and tag editing and converts between vari

Robert Kausch 683 Jan 22, 2022
GNOME audio player for transcription

Parlatype For a screenshot, an overview what Parlatype actually is and packages please visit https://www.parlatype.org. The following instructions are

Gabor Karsay 132 Jan 20, 2022
A cross-browser javascript wrapper for the html5 audio tag

audio.js audiojs is a drop-in javascript library that allows HTML5's <audio> tag to be used anywhere. It uses native <audio> where available and falls

Anthony Kolber 2.1k Jan 11, 2022
Javascript audio library for the modern web.

Description howler.js is an audio library for the modern web. It defaults to Web Audio API and falls back to HTML5 Audio. This makes working with audi

James Simpson 19.6k Jan 17, 2022
Sound Processing Language for Web Audio

CoffeeCollider CoffeeCollider is a language for real time audio synthesis and algorithmic composition in HTML5. The concept of this project is designe

mohayonao 213 Dec 18, 2021
IanniX is a graphical open-source sequencer, based on Iannis Xenakis works, for digital art. IanniX syncs via Open Sound Control (OSC) events and curves to your real-time environment.

About IanniX IanniX is a graphical open-source sequencer, based on Iannis Xenakis works, for digital art. IanniX syncs via Open Sound Control (OSC) ev

Buzzing Light 259 Jan 4, 2022
MuseScore is an open source and free music notation software. For support, contribution, bug reports, visit MuseScore.org. Fork and make pull requests!

Music notation and composition software MuseScore is an open source and free music notation software. For support, contribution, and bug reports visit

MuseScore 6.7k Jan 14, 2022
Open source sheet music

The Mutopia Project The Mutopia Project offers sheet music based on editions in the public domain. All sheet music is written in LilyPond by volunteer

null 195 Dec 22, 2021
A Music programming language. Translates source code into MIDI. Includes a player. Supports MIDI-Karaoke. Includes a MIDI analyzer.

Get Started | Features | Screenshots | Programming | CLI | Contribute | License Midica is an interpreter for a Music Programming Language. It translat

Jan Trukenmüller 51 Nov 27, 2021
Music player and music library manager for Linux, Windows, and macOS

Quod Libet: an audio library, manager & player Quod Libet is a cross-platform audio / music management program. It provides many ways to view your loc

Quod Libet 1.1k Jan 10, 2022
🎵 Music notation engraving library for MEI with MusicXML and Humdrum support and various toolkits (JavaScript, Python)

Verovio is a fast, portable and lightweight library for engraving Music Encoding Initiative (MEI) digital scores into SVG images. Verovio also contain

RISM Digital Center 442 Jan 10, 2022
music library manager and MusicBrainz tagger

beets Beets is the media library management system for obsessive music geeks. The purpose of beets is to get your music collection right once and for

beetbox 10.6k Jan 23, 2022
Small, fast and powerful console music player for Unix-like operating systems.

Warning: cmus is not actively maintained. For details, please see #856 cmus — C* Music Player https://cmus.github.io/ Copyright © 2004-2008 Timo Hirvo

C* Music Player 4.5k Jan 16, 2022
A GTK3 app for finding and listening to internet radio stations.

The successor of Gradio is Shortwave. Get more information here: https://gitlab.gnome.org/World/Shortwave Gradio A GTK3 app for finding and listening

Häcker Felix 334 Oct 9, 2021
Full-featured CD/DVD/Blu-ray burning and ripping application

K3b Version 18.04.0 Thanx for downloading K3b - The CD Kreator These are the features so far: - the most userfriendly interface ever ;-) - thema

KDE GitHub Mirror 78 Jan 13, 2022
🎵 A simple, clean and cross-platform music player

Museeks A simple, clean and cross-platform music player. (museeks.io) Features Museeks aims to be a simple and easy to use music player with a clean U

Pierre de la Martinière 1.1k Jan 10, 2022