Skip to content

Getting Started

Requirements

  • macOS or Linux (see the note below about Windows)
  • Python 3.10, 3.11, 3.12, or 3.13. Python 3.14 is not supported yet — the analysis engine has no build for it
  • An MCP-compatible assistant for conversational use. The CLI works without one
  • Mono or stereo files, at sample rates from 8 kHz to 384 kHz. Multichannel files are rejected
  • Audio files to analyze (WAV, FLAC, AIFF, and OGG). MP3, AAC, M4A, and WMA are rejected — convert to WAV first with phantom render yourfile.mp3 --format wav

Warning

Windows is not supported yet. Phantom’s analysis engine, essentia, publishes no Windows package, so installing on Windows fails while resolving dependencies. Replacing that engine with a Windows-capable one is tracked on GitHub. In the meantime, Phantom runs on macOS, on Linux, and under WSL.

Install Phantom

$ install

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

The installer sets up uv and a supported Python version, installs Phantom, and guides assistant setup. Optional extras add processing, reference matching, or stem separation; separation also downloads model weights.

Verify the installation:

$ verify

phantom —version

Try it without installing

Don’t want to commit to a full install yet? Run Phantom directly with uvx. The package is named phantom-audio but the command it installs is phantom, so you need --from:

$ try without installing

uvx —python 3.13 —from phantom-audio phantom analyze your-track.wav

Optional extras

The installer puts Phantom in its own isolated environment, so extras have to be added to that environment with uv tool install --force. A plain pip install lands somewhere else and the phantom on your PATH won’t see it.

$ optional extras

# Stem separation (Demucs, ~2.5GB) uv tool install "phantom-audio[separation]" --python 3.13 --force # Reference matching (GPLv3) uv tool install "phantom-audio[matching]" --python 3.13 --force # Fix and apply processing tools uv tool install "phantom-audio[processing]" --python 3.13 --force # Everything uv tool install "phantom-audio[all]" --python 3.13 --force

Pro tip

Install the extras you want in one go. Each uv tool install replaces the environment, so adding them one at a time means re-downloading what you already had.

Assistant plugins

For assistant setup, use the MCP configuration below or the configuration guide. The Python analysis package must be installed in a supported environment.

Check the installation

Run phantom doctor if installation or analysis fails. It reports missing dependencies and setup issues. FFmpeg is needed for format conversion; optional tools require their corresponding extras.

Configure your AI assistant

Phantom connects to your AI assistant via MCP (Model Context Protocol). You need to tell your assistant where to find the Phantom server.

See the full configuration guide: Configuring AI Assistants

Quick setup for Claude Code:

Claude Code

claude mcp add phantom — phantom-mcp

Quick setup for Claude Desktop — add to your claude_desktop_config.json:

claude_desktop_config.json

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

Run your first analysis

Once connected, ask your AI assistant to analyze an audio file. Use a natural language prompt — no special syntax needed.

Your prompt:

Analyze the loudness of my mix at mix-v3.wav

Illustrative summary:

Loudness Analysis Integrated: -14.2 LUFS True peak: -0.8 dBTP Range (LRA): 7.3 LU Short-term: -12.1 LUFS (max) Momentary: -9.4 LUFS (max)

Your AI assistant interprets this and responds with something like:

The file measures -14.2 LUFS integrated, with a true peak of -0.8 dBTP and a loudness range of 7.3 LU. If your delivery brief calls for a -1 dBTP ceiling, reduce the level slightly and measure the new render. Listen for any loss of punch before choosing a louder master.

Pro tip

Start with analyze the loudness of [file] or run a full diagnostic on [file] as your first prompt. These give comprehensive results that demonstrate Phantom’s capabilities.

What to try next

  • Full diagnostic: “Run a full diagnostic on vocals.wav” — measures everything at once
  • Problem detection: “Check my mix for problems” — finds clipping, mud, sibilance, resonances
  • Fix problems: “Fix the issues found in vocals.wav” — auto-applies corrective EQ and filtering
  • Comparison: “Compare my mix to a reference track at reference.wav” — A/B against a professional master
  • Batch analysis: “Analyze all stems in my session folder” — process up to 50 files in one call

Next steps