Skip to content

Automated Reference Matching

Matches your audio to reference spectral, loudness, and width characteristics via Matchering. Analyzes the differences and produces a processed output file that closes the gap.

Requires the phantom-audio[matching] extra. Add it with: uv tool install "phantom-audio[matching]" --python 3.13 --force

Parameters

Parameter Type Default Description
target_path string required Path to your audio file (the one to be processed)
reference_path string required Path to reference track
output_path string required Path to write the matched output file. Confined to PHANTOM_OUTPUT_DIR (default ~/.phantom/output) -- paths outside that directory are rejected.

Example Output

Illustrative summary; MCP responses use structured JSON.

$ match_to_reference my-mix.wav reference.wav matched-output.wav

Match to Reference: my-mix.wav vs reference.wav

Loudness (before -> after): Integrated: -14.2 -> -11.8 LUFS (change +2.4) True peak: -3.1 -> -1.4 dBTP (change +1.7)

Spectral change (before -> after, dB): 31 Hz: -8.2 -> -7.9 (+0.3) 62 Hz: -5.4 -> -5.1 (+0.3) 125 Hz: -3.1 -> -2.6 (+0.5) 250 Hz: -1.8 -> -0.3 (+1.5) 500 Hz: -0.6 -> -0.4 (+0.2) 1 kHz: 0.0 -> 0.0 (0.0) 2 kHz: +0.4 -> +1.2 (+0.8) 4 kHz: +1.1 -> +1.9 (+0.8) 8 kHz: +2.0 -> +3.5 (+1.5) 16 kHz: +3.4 -> +4.9 (+1.5)

Output: matched-output.wav

What the Numbers Mean

match_to_reference doesn’t hand back recommendations — it runs Matchering against the reference, measures the target before processing and the output after, and reports the diff.

  • Loudness (before/after/change) — Integrated LUFS and true peak measured on the target before Matchering runs, then again on the written output. change is after - before.

  • Spectral change (before/after/change, per octave band) — The same before/after/change pattern, in dB, for each of the 10 octave bands from 31 Hz to 16 kHz. Positive change means Matchering added energy in that band; negative means it cut.

  • No width field — Matchering does adjust stereo width as part of its processing, but the response doesn’t report a before/after width comparison — only loudness and spectral change come back in adjustments.

Example Prompts

Full match

Match my mix to this reference track and show me what changed

Check the result

Run match_to_reference against this commercial track and tell me how the loudness and spectral balance shifted

Compare first

Compare my mix to this reference before matching, so I know what Matchering is about to change

Pro tip

match_to_reference makes one pass — loudness, spectral balance, and width are all processed together via Matchering, and there’s no parameter to run just one of them. If you want to see the gap before committing to a full match, run compare_to_reference first.