DEV Community

Oren MixDiagnose
Oren MixDiagnose

Posted on • Originally published at mixdiagnose.com

I Built a CLI That Scores Your Mix 0-100 From the Terminal

#python #audio #cli #tools

I Built a CLI That Scores Your Mix 0–100 From the Terminal

If you've ever finished a mix and wondered "is this actually good?" — you're not alone. We open reference tracks, check LUFS meters, squint at spectrograms, and still second-guess ourselves. So I built mixdiagnose — a Python CLI that analyzes your audio mix and gives you a 0–100 Mix Score, LUFS measurements, frequency issue detection, and actionable fix recommendations. All from the terminal.

Installation 

pip install mixdiagnose
Enter fullscreen mode Exit fullscreen mode

That's it. No DAW plugins, no GUI, no account required.

Quick Start

Analyze a single mix:

mixdiagnose analyze my-mix.wav
Enter fullscreen mode Exit fullscreen mode

You'll get output like:

────────────────────────────────────────
  MixDiagnose Report — my-mix.wav
────────────────────────────────────────

  Mix Score: 78/100

  Loudness:
    Integrated LUFS:  -14.2
    True Peak:         -0.8 dBTP
    Dynamic Range:     9.4 DR

  Frequency Analysis:
    ✓ Low-end balanced
    ⚠ Excessive energy around 3 kHz — vocal harshness likely
    ✓ High frequencies clean

  Recommendations:
    1. Reduce 2–4 kHz by ~2 dB to tame harshness
    2. Mix is slightly below streaming target (-14 LUFS).
       Consider gentle limiter to reach -14 LUFS.
    3. True peak is within safe range. No changes needed.

────────────────────────────────────────
Enter fullscreen mode Exit fullscreen mode

Batch Processing

Working on an album? Analyze an entire folder of mixes in one command:

mixdiagnose analyze ./album-mixes/ --batch
Enter fullscreen mode Exit fullscreen mode

This processes every .wav, .mp3, .flac, and .aiff file in the directory and outputs a comparative summary:

Batch Summary — 10 files
──────────────────────────────────────────────
File                    Score   LUFS    Top Issue
──────────────────────────────────────────────
track-01.wav             82    -14.0   None
track-02.wav             71    -16.3   Low-end muddy
track-03.wav             88    -14.1   None
track-04.wav             65    -18.0   Dynamic range too high
...
──────────────────────────────────────────────
Average Score: 76.4 / 100
──────────────────────────────────────────────
Enter fullscreen mode Exit fullscreen mode

You can also export results to JSON for integration into your workflow:

mixdiagnose analyze ./album-mixes/ --batch --export results.json
Enter fullscreen mode Exit fullscreen mode

The Mix Score Formula

The Mix Score isn't a random number — it's a weighted composite of the metrics that actually matter in a professional mix:

Mix Score =
  (Loudness Score × 0.25) +
  (Frequency Balance Score × 0.30) +
  (Dynamic Range Score × 0.20) +
  (Stereo Width Score × 0.15) +
  (Spectral Cleanliness Score × 0.10)
Enter fullscreen mode Exit fullscreen mode

What each component measures:

Component Weight What It Checks
Loudness Score 25% Integrated LUFS proximity to target (-14 LUFS for streaming, -9 LUFS for club), true peak compliance
Frequency Balance 30% Low/mid/high energy distribution, presence of frequency gaps or buildups, comparison to ideal curves
Dynamic Range 20% DR rating, crest factor, transient preservation
Stereo Width 15% Side-channel energy, stereo image consistency, mono compatibility
Spectral Cleanliness 10% Unwanted noise, resonance peaks, boxiness, harshness

Each sub-score is normalized to 0–100, then combined with the weights above. The result is a single number that gives you a quick gut-check on your mix quality.

CI/CD Integration

Because mixdiagnose is a CLI, you can drop it into any pipeline. For example, here's a GitHub Actions snippet that checks your mix on every push:

- name: Analyze mix
  run: |
    pip install mixdiagnose
    mixdiagnose analyze ./mixes/master.wav --min-score 70
Enter fullscreen mode Exit fullscreen mode

The --min-score flag exits with code 1 if the score falls below the threshold, making it perfect for automated quality gates.

Available Commands 

# Analyze a single file
mixdiagnose analyze <file>

# Batch analyze a directory
mixdiagnose analyze <dir> --batch

# Export results to JSON
mixdiagnose analyze <file> --export results.json

# Set a minimum acceptable score (exit 1 if below)
mixdiagnose analyze <file> --min-score 75

# Compare your mix against a reference track
mixdiagnose compare my-mix.wav reference.wav

# View help
mixdiagnose --help
Enter fullscreen mode Exit fullscreen mode

Why a CLI?

I wanted something that:

  • Runs anywhere — no OS-specific GUI, no DAW dependency
  • Integrates into scripts and CI/CD pipelines
  • Outputs machine-readable results (JSON export)
  • Is fast — analyze a 4-minute track in seconds
  • Stays opinionated — a single score is easier to reason about than 15 separate meters

Links

Install It 

pip install mixdiagnose
Enter fullscreen mode Exit fullscreen mode

Run it on your latest mix. See what score you get. Then read the recommendations and go back to your DAW with a concrete plan instead of a vague feeling.

Happy mixing. 🎧

Top comments (0)