Matcherer: A Matchering Fork

This is a fork of the Matchering 2.0 library created by @sergree.

It adds two main features beyond the original functionality:

1. Mid/Side (M/S) Impulse Response (IR) Export

   • Generate separate Mid and Side FIR filter files (as WAV IRs).
   • Use them in any convolution reverb plugin for exact frequency matching (manually routing Mid and Side as needed).
   • By design, these are separate mono IRs, one for Mid and one for Side.

2. Stem/Secondary Processing

   • Use the analysis from a full track to process your stems or other secondary files.
   • Save the analysis (FIR, amplitude, limiter) to JSON to reapply later without re-running the entire matching.

Table of Contents

1. Overview of Added Features
2. Installation
3. Usage
   • 1) Single/Directory Matching
   • 2) Stem Mode
   • 3) Reusing a Saved Analysis
4. About M/S IR Export
5. Differences from Upstream
6. Credits & License

---

Overview of Added Features

Mid/Side IR Generation

When you run the script, it produces two separate FIR coefficient files and also writes them as mono .wav IRs:

• *_Mid_FIR.wav
  • Contains the FIR for the mid channel.
• *_Side_FIR.wav
  • Contains the FIR for the side channel.

You can load these into your DAW’s convolution reverb plugin (or any IR loader) to replicate the exact equalization that Matchering computed. However, you must manually handle Mid (L+R) and Side (L−R) routing to apply them properly. A single “stereo IR” is not generated by default, but you can experiment with combining them if your plugin/DAW workflow allows stereo M/S IR processing.

Stem/Secondary Processing

Often, you may want to match a full track (like the entire mix) to a reference, then apply that exact same EQ/amplitude/limiter to one or more stems (like vocals, bass, guitar, etc.). This fork allows two scenarios:

1. Immediate Stem Processing – Provide a main target and reference, plus a list of stems. The script will:

   • Analyze the main target vs. reference.
   • Apply the resulting analysis to the main target and all your stems.

2. Saved & Reused Analysis – Save the analysis to JSON using --analysis-file "my_analysis.json". Later, load that same analysis with --reuse-analysis to process new files or stems without re-analyzing the reference.

---

Installation

1. Clone this fork of Matchering:

   git clone https://github.com/suprduprnatural/matcherer.git
   cd matchering-fork

2. Install in your Python environment:

   python -m venv venv
   source venv/bin/activate   # or venv\Scripts\activate on Windows
   pip install --upgrade pip
   pip install --upgrade .

3. System Dependencies:

   • libsndfile (on Linux: sudo apt-get update && sudo apt-get install libsndfile1)
   • (Optional) FFmpeg for loading MP3s, etc.

For further details, see the original Matchering README.

Usage

Your main entry point is matcherer.py in this fork, which is similar to the official Matchering CLI but with extra options:

python matcherer.py [TARGET] [REFERENCE] [OPTIONS]

1) Single/Directory Matching

• TARGET can be a single file or a directory of audio files (e.g., .wav, .mp3, etc.).
• REFERENCE can also be a single file or a directory.

When both are directories, the script will generate all possible combinations. If you have multiple combos, it will ask to confirm.

Common Options:

• -b, --bit-depths => Comma-separated bit depths to export: 16, 24, float
• -o, --output => Output folder for matched files
• -p, --plot-fir => Also generate PNG plots of the FIR frequency response
• -A, --analysis-file => JSON file path for saving/loading analysis
• -r, --reuse-analysis => Skip analysis and reuse an existing JSON file

Example:

# Single-file matching with 16-bit WAV output
python matcherer.py mySong.wav reference.wav \
   --bit-depths 16 \
   --output matched_output

2) Stem Mode

Use -s or --stems to specify one or more stems. For example:

python matcherer.py target_main.wav reference_main.wav \
   -s "vocal_stem.wav,bass_stem.wav,drum_stem.wav" \
   --bit-depths float,16 \
   --output stems_matched

Flow:

1. Analyzes target_main.wav vs. reference_main.wav.
2. Saves FIR data + IR WAVs in stems_matched/.
3. Applies the same analysis to target_main.wav in multiple bit depths.
4. Applies the same analysis to each provided stem.

3) Reusing a Saved Analysis

If you already saved an analysis (e.g., my_analysis.json), you can skip re-analysis for new tracks. For instance:

# First run: Save analysis
python matcherer.py mySong.wav reference.wav \
   --analysis-file my_analysis.json

# Second run: Reuse analysis on different stems
python matcherer.py vocals.wav reference.wav \
   --analysis-file my_analysis.json \
   --reuse-analysis

Note: The reference path must remain consistent (or at least the same sample rate, etc.) for the analysis to be valid.

About M/S IR Export

During processing, the script writes out:

1. *_Mid_FIR.wav
2. *_Side_FIR.wav

Both are single-channel 32-bit float WAVs. These are the exact FIR filters determined by Matchering for the Mid and Side channels. To use them:

1. Create a Mid/Side matrix in your DAW and insert a convolution plugin on the mid and side channels.
2. For the Mid channel, load *_Mid_FIR.wav.
3. For the Side channel/s, load *_Side_FIR.wav.
4. Make sure each IR is only affecting its respective M or S channel.
5. Recombine the M/S channels into stereo and enjoy your M/S FIR affected audio.

Differences from Upstream

• Mid/Side IR Outputs (WAV format) for each matched track.
• Stem Mode to process multiple stems using a single analysis pass.
• Analysis Export/Import for reapplying the same FIR/amplitude/limiter.
• matcherer.py script includes advanced CLI options (bit depth selections, plotting, etc.).

Other internal changes:

• Enhanced logging (log_info/log_warning) with timestamps.
• Frequency response plots (via matplotlib) when --plot-fir is set.

For the original library’s usage and license info, see Matchering 2.0.

Credits & License

• Original: @sergree – Matchering 2.0
• License: GPL v3 (same as upstream).