🎚️ 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
  • [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 ankitdobhal 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
  • Possibility of controlling the final mix

    Possibility of controlling the final mix

    Thanks for your work it works well. You have thought about putting controls to regulate the percentage of the target, for example of the eq and the stereo field. regards

    opened by Sonidocreativo 6
  • 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
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 2k Sep 9, 2021
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 619 Sep 24, 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 6.4k Sep 17, 2021
Ear-bending noises and music

Cecilia5 - the audio processing toolbox Cecilia is an audio signal processing environment. Cecilia lets you create your own GUI (grapher, sliders, tog

Olivier Bélanger 128 Sep 12, 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 47 Sep 17, 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 73 Sep 18, 2021
Python CD-DA ripper preferring accuracy over speed

Whipper Whipper is a Python 3 (3.6+) CD-DA ripper based on the morituri project (CDDA ripper for *nix systems aiming for accuracy over speed). It star

null 554 Sep 19, 2021
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.8k Sep 25, 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 1k Sep 16, 2021
Fork of the original rubyripper from code.google.com/p/rubyripper + some bugs fixes

Historical note Introduction Secure rip method How to install MacOS Support FAQ Running all tests Historical note This is an unofficial fork of the or

null 91 Aug 11, 2021
The git repository of the advanced drum machine

Hydrogen drum machine Hydrogen is an advanced drum machine for GNU/Linux, Mac and Windows. It's main goal is to bring professional yet simple and intu

Hydrogen 702 Sep 15, 2021
Mopidy is an extensible music server written in Python

Mopidy Mopidy is an extensible music server written in Python. Mopidy plays music from local disk, Spotify, SoundCloud, Google Play Music, and more. Y

Mopidy 7.2k Sep 17, 2021
Typographic Beat-Oriented Notation for music

tbon Typographic Beat-Oriented Notation for music Tbon aims to be the fastest way to enter pitches, rhythms, meter and dynamic levels from a computer

null 11 Jan 23, 2020
Bule-ish CD ripper

cyanrip Fully featured CD ripping program able to take out most of the tedium. Fully accurate, has advanced features most rippers don't, yet has no bl

Lynne 57 Jun 30, 2021
OpenSheetMusicDisplay renders sheet music in MusicXML format in your web browser based on VexFlow. OSMD is brought to you by PhonicScore.com.

OpenSheetMusicDisplay (OSMD) A MusicXML renderer for the Browser opensheetmusicdisplay.org About OSMD • Demo • Key Features • Limitations • How to Use

Open Sheet Music Display 800 Sep 15, 2021
LibreTime: Radio Broadcast & Automation Platform

LibreTime makes it easy to run your own online or terrestrial radio station. It is a community managed fork of the AirTime project. It is managed by a

LibreTime: Radio Broadcast & Automation Platform 515 Sep 17, 2021
🐦 A personal music streaming server that works.

koel Intro Koel (also stylized as koel, with a lowercase k) is a simple web-based personal audio streaming service written in Vue on the client side a

Koel 12.8k Sep 17, 2021
Mixxx is Free DJ software that gives you everything you need to perform live mixes.

Mixxx Mixxx is Free DJ software that gives you everything you need to perform live DJ mixes. Mixxx works on GNU/Linux, Windows, and macOS. Quick Start

Mixxx DJ Software 2.4k Sep 17, 2021