Phantom reads its runtime configuration from environment variables. The full 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).
Setting a variable takes effect on the next analysis; settings resolve per call, so there is no restart. The analysis cache keys on your settings, so a tuned run is never served a result computed under different settings.
Paths and Limits
| Variable | Default | Description |
|---|---|---|
PHANTOM_AUDIO_DIR | (none) | Restrict input file reads to this directory tree. When unset, inputs may be read from anywhere (Phantom’s core use case); writes are always confined regardless. |
PHANTOM_OUTPUT_DIR | ~/.phantom/output | Directory all file writes are confined to. Writes outside it are rejected. Created on demand when unset; set this to write elsewhere. |
PHANTOM_PROFILES_DIR | (built-ins) | Custom reference profile directory (overrides built-ins). |
PHANTOM_METRICS_DIR | (platform default) | Directory for live metrics snapshots: ~/Library/PhantomStudio/metrics (macOS), %APPDATA%\PhantomStudio\metrics (Windows), ~/.config/PhantomStudio/metrics (Linux). |
PHANTOM_MAX_DURATION | 900 (15 min) | Maximum audio duration in seconds |
PHANTOM_MAX_FILE_SIZE | 500000000 (500 MB) | Maximum file size in bytes |
PHANTOM_MAX_DECODED_BYTES | 1000000000 (1 GB) | Maximum decoded float32 footprint per audio file in bytes |
PHANTOM_MAX_AGGREGATE_BYTES | 4000000000 (4 GB) | Combined decoded-size cap for multi-file tools |
Analysis Thresholds
| Variable | Default | Description |
|---|---|---|
PHANTOM_POLARITY_THRESHOLD | -0.5 | Overall L/R correlation below this flags polarity inversion |
PHANTOM_PHAT_WINDOW_S | 10.0 | GCC-PHAT cross-correlation window in seconds |
PHANTOM_CREST_FACTOR_LOW_DB | 6.0 | Crest factor below this marks the track as over-compressed |
PHANTOM_CLIPPING_THRESHOLD | 1.0 | Sample magnitude at or above this counts as clipping |
PHANTOM_DC_OFFSET_THRESHOLD | 0.0005 | Mean sample value above this flags DC offset |
PHANTOM_ISP_OVERSHOOT_DB | 0.5 | True-peak overshoot above this flags inter-sample peaks |
PHANTOM_ISP_SEVERE_DBTP | -1.0 | True peak above this raises ISP severity to significant |
PHANTOM_DYNAMIC_SPREAD_MIN_DB | 10.0 | Minimum P90-P10 block spread to trust a noise-floor estimate |
PHANTOM_NOISE_FLOOR_MODERATE_DB | -50.0 | Noise floor above this is flagged moderate |
PHANTOM_NOISE_FLOOR_MINOR_DB | -60.0 | Noise floor above this is flagged minor |
PHANTOM_SNR_PROFESSIONAL_DB | 60.0 | SNR at or above this counts as professional |
PHANTOM_SNR_POOR_DB | 50.0 | SNR below this is flagged poor/significant |
PHANTOM_SPECTRAL_FLATNESS_MIN | 0.01 | Minimum flatness to run band-excess detectors |
PHANTOM_BAND_EXCESS_THRESHOLD_DB | 6.0 | Band energy above expected level triggers detection |
PHANTOM_RESONANCE_MEDIAN_FLOOR_DB | -40.0 | Median spectral level floor for resonance detection |
PHANTOM_RESONANCE_PROMINENCE_DB | 12 | Peak prominence threshold for resonance detection |
PHANTOM_LOSSY_SHELF_DROP_DB | 20.0 | Shelf drop above this indicates a lossy codec |
PHANTOM_MASKING_SEVERITY_HIGH | 0.6 | Overlap score at or above this is labeled high severity |
PHANTOM_MASKING_SEVERITY_MODERATE | 0.3 | Overlap score at or above this is labeled moderate severity |
PHANTOM_MASKING_SEVERITY_LOW | 0.1 | Overlap score at or above this is labeled low severity |
PHANTOM_MASKING_FLOOR_DB | 40.0 | Bands more than this below the pair peak are zeroed before scoring |
FFT / Frame Sizes
| Variable | Default | Description |
|---|---|---|
PHANTOM_SPECTRAL_FRAME_SIZE | 2048 | Frame size of the main spectral analysis pass |
PHANTOM_SPECTRAL_HOP_SIZE | 1024 | Hop size of the main spectral analysis pass |
PHANTOM_OCTAVE_FRAME_SIZE | 4096 | Frame size of the octave-band energy pass (spectral + masking) |
PHANTOM_OCTAVE_HOP_SIZE | 2048 | Hop size of the octave-band energy pass |
PHANTOM_FLATNESS_FRAME_SIZE | 4096 | Frame size of the spectral-flatness gate (band-excess detectors) |
PHANTOM_SPECTRUM_FRAME_SIZE | 8192 | Frame size of the shared power-spectrum pass (resonance, lossy-codec detection) |
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. See AnalysisSettings for the full comparability caveat.
Output and Behavior
| Variable | Default | Description |
|---|---|---|
PHANTOM_MASKING_TOP_N | (auto) | Number of top masking pairs returned (scales with stem count when unset) |
PHANTOM_PROFILE_MERGE | (none) | Merge a user profile over the built-in instead of replacing it |
PHANTOM_PROFILE_OVERRIDE_QUIET | (none) | Silence the user-profile-override log line |
PHANTOM_DEBUG | (none) | Enable verbose error output from MCP tools |
PHANTOM_QUIET | (none) | Suppress startup preflight messages |
Installer-only variables
PHANTOM_NO_TELEMETRY is not a runtime variable and doesn’t appear in phantom doctor. The installers (install.sh, install.ps1) honor it to opt out of install telemetry:
# macOS / Linux
curl -sSL https://fadelab.net/install | PHANTOM_NO_TELEMETRY=1 bashThe variable has to go on bash, not on curl. Writing PHANTOM_NO_TELEMETRY=1 curl ... | bash sets it for the download and not for the script that reads it, so telemetry still fires.
The Windows installer honors the same variable, but Phantom cannot be installed on Windows yet — see Getting Started for why and what’s being done about it.
Pro tip
The complete list above matches phantom doctor output exactly. If a variable isn’t listed here,
the runtime doesn’t read it.