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.
changeisafter - 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
Related Tools
- compare_to_reference – See the raw differences before matching
- compare_to_profile – Match against genre targets instead of a specific track
- analyze_spectrum – Verify EQ changes worked after applying
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.