Phantom’s analyzers are tunable. The exposed analysis thresholds and frame sizes are fields on a settings object called AnalysisSettings (src/phantom/_settings.py), and every knob has an environment variable override with a documented default. The knobs fall into four groups: phase and dynamics thresholds, the problem-detection threshold block, masking severity splits, and the FFT/frame sizes.

This page explains how tuning works, what the typed result models are, and the one caveat that matters before you change frame sizes.

How tuning works

• Defaults provide a common baseline. Leave the overrides unset to use the defaults for your installed version.

• Every knob is env-overridable. Each field on AnalysisSettings maps to a PHANTOM_* variable. Setting one overrides the default for every analysis that reads it. The complete list is in the Environment Variables Reference.

• Settings resolve per call. Analyzers read the effective settings when they run, not at import. A change in the running process environment takes effect on the next analysis. After editing an assistant’s MCP environment configuration, restart its Phantom server so it receives those values.

• The cache keys on your settings. The analysis cache folds a fingerprint of the current settings into its cache key. A tuned run is never served a result computed under different settings, and reverting to defaults doesn’t break earlier cached results.

The knob groups

Most spectral, dynamics, and masking measurements use a mono analysis signal. In 1.6.0, when opposite-polarity channels nearly cancel in that sum, Phantom falls back to the strongest channel so real audio is not treated as silence. Stereo and phase tools retain the channel relationship; check those results before interpreting the fallback analysis as a mono-compatible mix.

Typed result models

The core analyzers return typed result models that MCP serializes as structured JSON. Other tools return lists, composite responses, profile data, or errors; consult each tool’s reference for its shape.

The six analysis dimensions each return their own model:

Composite tools combine these models into larger typed payloads:

• full_diagnostic / batch_diagnostic return a StemDiagnosticResult per file: file metadata (name, duration, sample rate, channels) plus one typed field per dimension. The model rejects unknown fields, so output shape is stable by construction.
• batch_diagnostic wraps stems in a BatchDiagnosticResult with a stems map and stem_count; failed stems appear as error objects, not dropped entries.
• multi_stem_masking returns typed MaskingPair entries with severity scores per pair.
• read_live_metrics returns a LiveMetricsResult with instance metadata and the raw meter snapshot.
• load_profile returns a ReferenceProfile with loudness, frequency, stereo, and spatial targets.

Because the models are typed, tuning a threshold changes values inside the same schema — never the output shape. An assistant that learned the schema once keeps working when you adjust a knob.

The FFT comparability caveat

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. A different octave-band or spectral frame size produces different band energies and descriptors.

Two rules when you tune the frame-size knobs:

1. Reset the knobs to defaults before comparing, or
2. For a reference-file comparison, analyze both files under the same settings. Re-running a built-in profile comparison cannot recalibrate that profile; keep defaults when using built-in targets.