Deploying Matchering

Introduction

Matchering is an open-source audio mastering application that uses intelligent audio processing to master your tracks to professional standards. By analyzing a reference track that you like, Matchering automatically adjusts your audio’s frequency balance, dynamics, and loudness to match professional quality.

Built with Python and powered by sophisticated audio processing algorithms, Matchering provides an accessible way to achieve professional-sounding masters without expensive software or years of audio engineering experience. It’s the perfect tool for musicians, podcasters, and content creators who want polished audio.

Key highlights of Matchering:

Reference-Based Mastering: Match your track’s sound to any professional reference
Automatic Processing: Intelligent algorithms handle the technical details
High-Quality Output: Produces broadcast-ready, professional masters
Multiple Formats: Supports WAV, FLAC, AIFF, and other common formats
Web Interface: User-friendly web UI for easy uploading and processing
REST API: Integrate mastering into your workflow programmatically
Batch Processing: Process multiple tracks efficiently
Preview Mode: Listen before committing to the final master
Open Source: GPLv3 licensed with active development
No Subscription: Self-hosted means no recurring fees

This guide walks through deploying Matchering on Klutch.sh using Docker, configuring the web interface, and mastering your first tracks.

Why Deploy Matchering on Klutch.sh

Deploying Matchering on Klutch.sh provides several advantages:

Remote Access: Master tracks from any device with a web browser.

Processing Power: Leverage cloud resources for CPU-intensive audio processing.

Always Available: Your mastering service runs 24/7 without managing servers.

HTTPS by Default: Secure file uploads with automatic SSL certificates.

Scalable Resources: Allocate CPU based on your processing needs.

Team Access: Share your mastering service with collaborators.

Prerequisites

Before deploying Matchering on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Matchering configuration
Basic familiarity with Docker concepts
Audio files to master and reference tracks

Understanding Matchering Architecture

Matchering consists of two main components:

Core Library: The Python audio processing engine that performs the actual mastering. It analyzes both the target and reference tracks, then applies intelligent processing to match characteristics.

Web Application: A Flask-based web interface that provides file upload, processing status, and download functionality.

Processing Pipeline:

Upload target track (your unmastered audio)
Upload reference track (professionally mastered track you want to match)
Matchering analyzes both tracks
Applies EQ, compression, and limiting
Outputs a mastered version of your track

Preparing Your Repository

To deploy Matchering on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

matchering-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM sergree/matchering-web:latest

# Environment configuration
ENV HOST=0.0.0.0
ENV PORT=8360

# Expose the web interface port
EXPOSE 8360

Alternative: Core Library Only

If you only need the API without the web interface:

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    ffmpeg \
    libsndfile1 \
    && rm -rf /var/lib/apt/lists/*

# Install matchering
RUN pip install matchering

# Create working directory
WORKDIR /app

# Copy your custom processing script
COPY process.py /app/

# Expose API port if using custom API
EXPOSE 8000

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
__pycache__/
*.pyc
*.wav
*.mp3
*.flac

Deploying Matchering on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Matchering deployment configuration"
git remote add origin https://github.com/yourusername/matchering-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “matchering” or “audio-mastering”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Matchering Dockerfile.

Configure HTTP Traffic

Matchering serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8360 (Matchering web’s default port)

Allocate Sufficient Resources

Audio processing is CPU-intensive. Allocate:

At least 2 vCPUs recommended
2+ GB RAM for processing
Increase for batch processing or longer tracks

Attach Persistent Volume (Optional)

For keeping processed files:

Mount Path	Recommended Size	Purpose
`/app/uploads`	10 GB	Temporary file storage
`/app/results`	10 GB	Processed audio files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Start the Matchering container
Provision an HTTPS certificate

Access Matchering

Once deployment completes, access your instance at https://your-app-name.klutch.sh.

Using Matchering Web Interface

Mastering Your First Track

Navigate to your Matchering instance
Upload your target track (the unmastered audio you want to process)
Upload your reference track (a professionally mastered track you want to match)
Click Process or Master
Wait for processing to complete
Download your mastered track

Choosing a Reference Track

The reference track significantly affects your results:

Good Reference Choices:

Professionally mastered commercial releases
Tracks in the same genre as your target
Songs with the tonal balance you want
High-quality files (WAV, FLAC preferred)

Avoid:

Poorly mastered tracks
Heavily distorted or clipped audio
Tracks with very different instrumentation
Low-quality MP3s

Supported Formats

Input Formats:

WAV (recommended)
FLAC
AIFF
MP3
OGG

Output Formats:

WAV (16-bit, 24-bit)
FLAC

Understanding the Processing

What Matchering Does

Analysis: Examines frequency spectrum, dynamics, and loudness of both tracks
EQ Matching: Adjusts your track’s frequency balance to match the reference
Dynamic Processing: Applies compression to match the reference’s dynamics
Loudness Matching: Uses limiting to achieve similar loudness levels
Clipping Prevention: Ensures no digital distortion in the output

Processing Parameters

Matchering automatically determines:

EQ curve adjustments
Compression ratio and threshold
Limiting ceiling
Overall gain

Limitations

Be aware of what Matchering cannot do:

Fix poor mixing decisions
Add instruments or elements
Remove noise or artifacts
Fundamentally change the character of a track

API Integration

REST API

Matchering provides an API for programmatic access:

import requests

# Upload and process
files = {
    'target': open('my_track.wav', 'rb'),
    'reference': open('reference.wav', 'rb')
}

response = requests.post(
    'https://your-app-name.klutch.sh/api/master',
    files=files
)

# Download result
result_url = response.json()['result_url']

Python Library

Use Matchering directly in Python:

import matchering as mg

mg.process(
    target='my_track.wav',
    reference='reference.wav',
    results=[
        mg.pcm16('my_track_master_16bit.wav'),
        mg.pcm24('my_track_master_24bit.wav'),
    ]
)

Production Best Practices

Audio Quality Tips

Use High-Quality Source Files: Better input = better output
Match Genres: Use reference tracks from the same genre
Avoid Over-Limiting: If your source is already limited, results may suffer
Compare A/B: Always compare the master to the original

Resource Management

Process One at a Time: For best results, avoid concurrent processing
Use Adequate Resources: Allocate enough CPU for smooth processing
Clean Up Files: Remove processed files to save storage

Workflow Integration

Batch Processing: Set up scripts for processing multiple tracks
Quality Control: Always review masters before finalizing
Keep Originals: Never delete your unmastered source files

Troubleshooting Common Issues

Processing Fails

Symptoms: Error message during processing.

Solutions:

Verify both files are valid audio formats
Check file sizes aren’t too large
Ensure files aren’t corrupted
Check sufficient disk space
Review logs for specific errors

Poor Results

Symptoms: Master doesn’t sound good.

Solutions:

Try a different reference track
Ensure reference is actually well-mastered
Check your source isn’t already heavily processed
Verify files are similar in genre/style

Slow Processing

Symptoms: Processing takes very long.

Solutions:

Increase CPU allocation
Use shorter tracks for testing
Check for resource contention
Consider smaller file sizes

Cannot Upload Files

Symptoms: Upload fails or times out.

Solutions:

Check file size limits
Verify stable network connection
Try smaller files first
Ensure supported format

Alternative Audio Tools

If Matchering doesn’t fit your needs, consider:

LANDR: Commercial AI mastering service
Auphonic: Podcast and spoken word processing
Ardour: Full DAW for manual mastering
Audacity: Free audio editor

Additional Resources

Conclusion

Deploying Matchering on Klutch.sh gives you a powerful, accessible audio mastering tool that produces professional results without expensive software or extensive training. By leveraging reference-based processing, you can achieve the sound quality you want with just two audio files.

Whether you’re a musician finishing an album, a podcaster polishing episodes, or a content creator needing professional audio, Matchering provides an efficient path to broadcast-quality masters. With Klutch.sh handling the infrastructure, you can focus on creating great audio while your mastering service handles the technical heavy lifting.

Take your audio to the next level with self-hosted, AI-powered mastering that you control.