Phantom

Phantom measures audio and gives an AI assistant evidence to work with. Analyze a mix or a folder of stems, compare it with a reference, and investigate loudness, tonal balance, stereo behavior, phase, and frequency masking.

Use it as a command-line tool, a Python library, or an MCP server. The Claude Code plugin adds five skills for interpreting the measurements and planning a mix. Separate Reaper and Ableton MCP integrations let an assistant work inside your DAW.

Documentation · Getting started · Tool reference · Releases

Start with one file

Phantom supports macOS and Linux with Python 3.10–3.13. The commands below use 3.13. Windows is not supported: the Essentia dependency has no Windows wheel. A replacement backend is tracked in issue #52.

Install uv, then:

uv tool install phantom-audio --python 3.13
phantom analyze mix.wav
phantom analyze mix.wav --json
phantom compare mix.wav --reference reference.wav
phantom doctor

The CLI works without an AI assistant. First use may run setup to configure the MCP server and Claude Code plugin; you can also run phantom setup explicitly.

For an assistant, try: “Analyze these stems. Prioritize technical problems, explain the measurements, and tell me what you would check by listening before changing anything.”

What you can do

• Check a recording before mixing. Look for digital clipping, DC offset, mains hum, noise, and stereo polarity problems. Batch diagnostics also report differing sample rates.
• Compare a mix with a reference. Measure loudness, relative octave-band balance, dynamics, and stereo differences. Nine genre profiles provide starting targets when you do not have a reference file.
• Find competing stems. Rank pairs by weighted octave-band overlap to decide where to investigate masking. The score is a heuristic; it does not establish that one instrument is inaudible.
• Try corrective processing. With the processing extra, apply EQ and other Pedalboard operations or use recipes for selected detected problems. fix_audio reports before/after findings, including regressions.
• Read meters from Phantom Studio. read_live_metrics reads local snapshots from the separate Studio preview plugin. Studio is not included in this package.

The measurements support an engineering decision. They cannot decide whether distortion is intentional, whether a reference suits a song, or whether a change sounds better.

Analysis tools

The MCP server exposes 20 tools over stdio:

Loudness is measured from the individual channels. Clipping checks either channel and accounts for integer PCM’s positive rail. For analyses based on a mono signal, Phantom uses the loudest channel if stereo cancellation would otherwise turn active audio into a silent downmix. Phase and stereo measurements still describe the original channels.

Optional processing

Install the capabilities you need into the same isolated environment:

# Corrective EQ, compression, and other Pedalboard effects
uv tool install --force 'phantom-audio[processing]' --python 3.13

# Add reference matching and stem separation as well
uv tool install --force 'phantom-audio[all]' --python 3.13

The matching extra uses Matchering. The separation extra installs the sibling phantom-audio-separation package and Demucs/PyTorch; these are a substantially larger download, and first use downloads model weights. analysis adds librosa for optional cross-validation. None is needed for the core analysis tools.

phantom fix vocal.wav --output vocal-fixed.wav
phantom separate mix.wav --output stems
phantom render mix.wav --reference reference.wav --output matched.wav
phantom render mix.wav --format flac --output converted.flac

Relative output paths resolve inside ~/.phantom/output by default. Set PHANTOM_OUTPUT_DIR to an existing directory to write elsewhere. Format conversion also requires the ffmpeg executable.

Corrective processing writes 32-bit float WAVs to preserve precision and headroom. It does not restore clipped samples, perform source-aware de-essing, or guarantee improvement. An EQ cut around 7 kHz is a static tonal change, not a dynamic de-esser. Listen to the result and inspect reported regressions.

Use with an MCP client

Run phantom-mcp or phantom serve for the stdio server. A client that accepts MCP JSON configuration can use:

{
  "mcpServers": {
    "phantom": {
      "command": "phantom-mcp",
      "args": []
    }
  }
}

The executable must be on the client’s PATH. See assistant configuration for client-specific setup.

The Claude Code plugin supplies these skills:

Work in a DAW

Phantom analyzes files; a separate MCP server controls the DAW. Export a mix or stems, analyze them, make a proposed change, then export and measure again. Check the bridge’s available tools before attempting an operation.

Reaper

phantom setup-reaper

This installs the Phantom Reaper MCP fork, copies its Lua bridge, and configures the MCP entry and startup script. Existing installations and conflicting configurations may require an explicit choice; read setup’s result before assuming it is connected. Open Reaper and verify the bridge responds before editing a session.

The plugin includes Reaper recipes for routing, FX, automation, and session setup. Plugin parameter names and ranges vary; discover them before setting values. Some third-party plugins expose limited parameters to the host.

Ableton Live

phantom setup-ableton

This runs the Remote Script installer from ableton-mcp==1.4.0 and configures AbletonMCP alongside Phantom. It preserves other MCP entries, restricts the installed Remote Script listener to 127.0.0.1:9877, and disables upstream telemetry. Setup stops if it cannot verify the listener configuration. Restart Live, select AbletonMCP as a Control Surface in its MIDI settings, then restart your MCP client and call get_session_info to verify the connection.

For a custom User Library, pass --scripts-dir '/path/to/User Library/Remote Scripts'. Use --config PATH to select an MCP JSON file, or --config-only to configure the client without installing or securing the script. If you use --config-only, restrict the Remote Script listener to localhost yourself before activating it. Setup refuses to replace a different existing Ableton entry unless you pass --force.

The external Ableton MCP project supplies Live control. Phantom’s audio analysis still uses exported files. Reaper Lua recipes cannot be run in Live; use the Ableton workflow guidance and only the tools exposed by your installed bridge. A real Live-session smoke test is still required for this integration; setup and configuration tests do not establish DAW compatibility.

Reference profiles

Built-in profiles: ambient, edm, electronic, hip-hop, lo-fi, metal, pop, rock, and rock-metal.

Profiles describe broad spectral and dynamics tendencies. They are not mastering rules for every song, and a full-mix profile is not an appropriate tonal target for every isolated stem. Streaming normalization levels are playback references, not a requirement to master every release to one LUFS value.

Privacy and limits

Audio analysis runs locally. If you connect an AI assistant, the measurements and tool results it receives are subject to that provider’s configuration and data policy. Optional separation downloads model weights. The standalone installers report install status, OS, architecture, version, selected extras, and a per-install identifier to fadelab.net; they do not send audio or raw error logs.

To opt out of installer telemetry:

curl -sSL https://fadelab.net/install | PHANTOM_NO_TELEMETRY=1 bash

Put the variable on bash, which runs the installer. Direct uv tool install does not run Phantom’s shell installer. Ableton MCP is a separate project; Phantom’s generated configuration explicitly disables its telemetry.

Inputs may come from anywhere unless PHANTOM_AUDIO_DIR is set. Outputs are always confined to the output directory. Default per-file limits are 15 minutes, 500 MB on disk, and 1 GB decoded. Large batches and resampling have additional memory guards. Live snapshots are limited to 1 MB and flagged stale after 10 seconds.

WAV, FLAC, AIFF, OGG, and other libsndfile formats are supported for analysis. MP3/AAC/M4A/WMA are rejected by the loader; convert them with phantom render first. Only mono and stereo audio are supported. Technical and tonal problem detectors are heuristics and may miss or misclassify material; a high-frequency cutoff alone is not proof of lossy encoding.

Configuration

Phantom reads its settings from environment variables. The full runtime set is 40 PHANTOM_* variables — paths and limits, analysis thresholds, FFT/frame sizes, and behavior flags — and phantom doctor prints the complete list with the value each has in your environment (or that it is unset). All analysis thresholds and frame sizes are knobs on AnalysisSettings (src/phantom/_settings.py), each overridable through its PHANTOM_* env var with the documented default. Settings resolve per call, so a change takes effect without a restart, and the analysis cache keys on your settings — a tuned run is never served a result computed under different settings.

Paths and Limits

Analysis Thresholds

FFT / Frame Sizes

Changing frame sizes changes the analysis geometry, so results are not numerically comparable with the built-in genre profiles or reference-target comparisons, both of which are calibrated to the default frame sizes. Reset the knobs to defaults before comparing, or re-run the comparison under the same tuned geometry.

Output and Behavior

The installers (install.sh, install.ps1) honor PHANTOM_NO_TELEMETRY to opt out of install telemetry; see the Telemetry section.

Contributing

See CONTRIBUTING.md for development setup, coding conventions, and how to submit changes.

License

Phantom is licensed under AGPL-3.0.

What you can do:

• Use Phantom for any purpose, personal or commercial
• Modify the code and distribute your modified version
• Use the MCP tools and CLI in your own workflow without restriction

What AGPL requires:

• If you modify Phantom and run it as a network service (e.g., a hosted API that wraps Phantom’s analysis), you must publish your modified source under AGPL-3.0
• If you distribute a modified version, same thing. Publish the source.
• Using Phantom unmodified as a tool in your workflow does not trigger this

Want to use Phantom in a proprietary product? Commercial licensing is available. Contact [email protected].

Patent Notice: Phantom’s weighted frequency masking analysis is patent pending (US Provisional Application 64/055,566). The AGPL-3.0 license includes an automatic patent grant — open source users are covered.

The optional matchering dependency uses GPLv3, which is compatible with AGPL-3.0.