Skip to content

Changelog

What's new in Phantom. Release notes written for engineers, not commit logs.

  1. v1.6.0 September 7, 2026

    Phantom 1.6.0 adds Ableton MCP setup and fixes audio-analysis, output, and installation edge cases.

    DAW setup

    • phantom setup-ableton installs the pinned Ableton MCP Remote Script and configures it alongside Phantom. Existing unrelated MCP servers are preserved; replacing an existing Ableton entry requires --force.
    • Full Ableton setup restricts the installed Remote Script listener to localhost and stops if it cannot verify the configuration. --config-only does not secure an existing script.
    • Ableton MCP telemetry and automatic script installation on server startup are disabled in the generated configuration. Activate the Remote Script in Live and verify get_session_info after setup.
    • REAPER setup now pins the independently versioned bridge release v1.1.1. Failed bridge checkouts stop setup before copying scripts unless unverified operation is explicitly requested.
    • Setup previews withhold MCP configuration values that could contain credentials.

    Audio and reliability

    • Check loudness and clipping across channels so stereo cancellation does not hide active audio or clipped samples.
    • Detect positive integer PCM clipping rails and keep clipping metadata distinct in cached analysis.
    • Preserve headroom in processed audio using atomic 32-bit float WAV output. Separate input and output directories now work through processing and reference matching.
    • Reject invalid analysis settings before native algorithms run, bound live-metrics reads, and check resampling allocations against the configured audio budget.
    • Load the native analysis engine when needed so installation diagnostics remain available when it cannot load.
    • Remove unused code, enforce import ordering and additional lint rules, and revise the README and engineering skills around verified behavior and limits.

    Packaging

    Source archives now use an explicit file list. CI checks both package formats for unexpected files and local home paths before release.

    Compatibility and verification

    Phantom’s MCP surface remains 20 tools. External DAW bridges provide their own tools. Python 3.10–3.13 on macOS and Linux remains the supported installation range; Windows support still requires an alternative analysis backend.

    Local tests covered synthetic signals, local audio integration, setup configuration, and package contents. The pinned REAPER bridge and Ableton Remote Script were installed locally. A connected Ableton Live session was not tested because Live was unavailable; configuration success is not a live-session verification.

  2. v1.5.2 August 22, 2026

    Fixed

    Stereo rating on the reference path

    compare_to_reference rated stereo width and correlation on the dB scale. The #56 fix in 1.5.1 corrected compare_to_profile only, so the reference path still called _rate_deviation_ref with no thresholds and fell back to the dB defaults (1.0/3.0/6.0).

    Width gaps between two mixes top out near 1.2 and correlation gaps at 2.0, so anything under 1.0 read on_target and, for correlation, the significant ratings were unreachable by construction. A near-mono mix against a decorrelated reference reported deviation 1.0 and rated on_target.

    Width reuses _WIDTH_THRESHOLDS. Correlation gets _CORRELATION_THRESHOLDS, anchored on _BASS_MONO_THRESHOLD — a 0.05 departure from fully mono is the established just-detectable step — with 0.15/0.25 continuing the ladder.

    GCC-PHAT delay on short inputs

    _gcc_phat_delay built its lag region without checking the correlation was long enough to hold it. max_shift is 2205 samples at 44.1 kHz, so once an input fell below twice that the two halves overlapped, and once it fell below max_shift the negative slice clamped to the whole array.

    Measured with broadband noise: a 1000-sample pair with a true delay of 0 reported -2205 samples (-50.00 ms); the same pair at delay 100 reported -2105 (-47.73 ms). The reading tracked the real delay but sat a full window away from it. Reachable from real files, since compare_phase truncates both signals to the shorter one.

    max_shift is now clamped to n // 2.

    Other fixes

    • PHANTOM_MASKING_TOP_N rejects 0 and negatives. Pairs sort worst-first, so a negative slice dropped the most severe pairs rather than returning fewer.
    • fix --interactive --json keeps its prompt off stdout, so the document parses.
    • read_live_metrics returns the "no live metrics" message instead of a raw FileNotFoundError when a snapshot vanishes between listing and selection.
    • enforce_decode_limits honours its AudioLoadError contract in the size probe.
    • install.sh reports phantom's exit status, not grep's — two of three success cases previously printed a failure.
    • install.ps1 checks $LASTEXITCODE after phantom setup.
    • Commit hooks scan .ps1 and .bats, and block the Claude URL shapes actually handed out.
    • CI: the optional-extras job can fail the build and runs test_processing.py; the planning-docs gate fetches origin/main before diffing.

    Added

    mid_side_state

    mid_side_ratio_db is undefined at both extremes and returned a bare None for each — a mono file has no side energy, a fully inverted one has no mid. Those are opposite conditions: mono is usually fine, fully inverted cancels on a mono fold.

    StereoResult now carries mid_side_state, set to pure_mid or pure_side in those cases and None when the ratio is a real measurement. Additive; the existing field is unchanged.

    Tests

    Nine tests closing gaps confirmed by mutation testing: compare_phase resampling (deleting align_sample_rates left all 43 phase tests passing), the masking moderate/low severity branches (both threshold tests asserted inside an if that never ran), and dynamic_complexity/loudness_db (replacing the Essentia call with constants passed the entire suite).

    Also rewritten to depend on what they name: band normalization call sites, the problem sort order, and the analysis window truncation.

    Known

    Phantom still does not install on Windows. essentia has never published a Windows wheel, so uv tool install phantom-audio fails at dependency resolution. Tracked in #52. Phantom Studio, the plugin, is unaffected — it does not use essentia and builds on Windows.

    Full Changelog: https://github.com/fadelabs/phantom/compare/v1.5.1...v1.5.2

  3. v1.5.1 August 17, 2026

    Fixed

    Stereo width was rated on the wrong scale

    compare_to_profile returned on_target for stereo width on every possible input, including a fully mono mix. Width is a side/mid ratio, but it was being scored against the dB thresholds (1.0/3.0/6.0), and the largest below-range deviation width can produce is 0.7 — under the on_target threshold. Width now uses ratio-scaled thresholds. A near-mono mix rates significantly_below against pop and ambient, and still on_target against lo-fi, which targets narrow.

    Fixing it surfaced a second gap: _WIDTH_RANGES had no entry for very_wide. The ambient profile declares that descriptor, so it fell through to a (0.0, 2.0) catch-all spanning the whole usable domain, which disabled the width check for that genre entirely. Six regression tests cover both; one asserts that no bundled profile relies on the catch-all, so a future descriptor cannot silently disable its own check. (#56)

    Other fixes

    • The pre-push hook refuses to vouch for a ref that is not the one checked out. Its checks run against the working tree, so pushing a different ref meant the hook reported on code that wasn't being pushed. --no-verify overrides.
    • ClassVar now resolves at module scope, so pydantic honors it on Python 3.10–3.12. Python 3.13 resolved the annotation where the older versions did not.

    Changed

    Windows install telemetry matches install.sh

    install.ps1 now sends a single POST with a JSON body: install method, outcome, and one of four enumerated failure reason codes through a new Stop-Install that mirrors install.sh's err(). Telemetry initialization moved above the Windows build check, architecture is normalized to x86_64/arm64, and extras report none until an install is actually attempted. Same endpoint, same opt-out (PHANTOM_NO_TELEMETRY=1), still fire-and-forget.

    Windows CI

    New .github/workflows/install-windows.yml runs the installer's telemetry harness on windows-latest under both Windows PowerShell 5.1 — what users actually have — and PowerShell 7, plus a parse check. tests/install_ps1/ adds 125 assertions across nine scenarios, checked against the validation rules the telemetry endpoint really applies. It runs anywhere:

    python3 tests/install_ps1/verify_telemetry.py

    A second CI job runs install.ps1 end to end and is expected to fail until #52 lands. See below.

    Lint

    Adopted ruff 0.16.3 and cleared the findings its widened default rule set surfaced.

    Docs

    Phantom does not install on Windows, and never has

    essentia is a hard core dependency and has never published a Windows wheel for any version, nor an sdist since 2020. uv tool install phantom-audio therefore fails at dependency resolution on Windows, with or without extras. Every other dependency resolves fine.

    This release does not fix that — it stops the project implying otherwise. The README install block states it, pyproject.toml classifiers no longer claim Operating System :: OS Independent (which was false), and CLAUDE.md records it beside the Essentia decision that caused it. Replacing essentia with a Windows-capable backend is tracked in #52.

    Corrections

    • detect_problems coverage and batch_diagnostic concurrency were both documented inaccurately.
    • Fixed the uvx invocation example, the telemetry opt-out example, and a link to a 404 install URL.
    • RELEASING.md now names the real keychain item, warns that uv publish without file arguments uploads every stale artifact left in dist/, and corrects the Anthropic marketplace step.

    Full Changelog: https://github.com/fadelabs/phantom/compare/v1.5.0...v1.5.1

  4. v1.5.0 August 17, 2026

    What's new

    Live metering from Reaper

    New read_live_metrics MCP tool reads real-time loudness and peak metrics from a running Reaper session, bringing the tool count to 20.

    Tunable analysis

    New AnalysisSettings layer: FFT and frame sizes, polarity and crest thresholds, PHAT window, masking band splits, and problem-detection thresholds are now tunable through PHANTOM_* environment variables. Analysis caching is scoped to the active settings, so changing a knob never returns stale results. All 40 runtime variables are documented in the README, and phantom doctor prints its environment table straight from the central registry so docs and code can't drift.

    Stem separation is its own package

    The Demucs-based separation engine moved to a sibling PyPI package, phantom-audio-separation (also 1.5.0). Installing phantom-audio[separation] still works and now pulls it in; the core package stays lighter for everyone who doesn't separate stems.

    Safer Reaper setup

    phantom setup-reaper is now transactional: it backs up existing configuration, stages changes before applying them, and supports --dry-run and --uninstall.

    Changed

    • Install telemetry (install.sh) now sends a single POST with a JSON body: install method, outcome, and one of six enumerated failure reason codes, plus a stable per-run id. Same endpoint, same opt-out (PHANTOM_NO_TELEMETRY=1), still fire-and-forget. The Windows installer also reports install outcomes; its payload moves to the same JSON shape in an upcoming release.
    • Typed response models throughout: per-band maps, problem details, and dict-compatible flat maps replace loose dicts.
    • Internal analysis facade: all analysis tools route through a single registry with generated wrappers, gated by a schema snapshot test so the MCP surface can't change silently.

    Fixed

    • Input hardening across the analysis pipeline: non-finite samples are rejected, sample magnitudes bounded, decoded array sizes capped, environment values validated, and error messages redact absolute paths (including UNC and spaced paths).
    • phantom analyze --json output contract restored.
    • 2026-07-05 audit findings and all Phase 0–3 code-review findings resolved.
    • CLI tests no longer overwrite a real .mcp.json.

    Security

    • cryptography 49.0.0 → 50.0.0 (PYSEC-2026-3552).
    • torch → 2.13.0, setuptools → 83.0.0, plus patched transitive dependencies.
    • Semgrep SAST added to CI and pre-commit; gitleaks action updated to v3.

    Docs

    • All five plugin skills (mix, mastering, effects, diagnostician, session-architect) recalibrated against the actual analysis code — thresholds, knobs, and tool facts now match what ships.
    • Full PHANTOM_* environment variable reference in the README, including the installer-only variables and telemetry disclosure.

    Full Changelog: https://github.com/fadelabs/phantom/compare/v1.3.1...v1.5.0

  5. v1.3.1 June 1, 2026

    Security hardening release. All users should upgrade: pip install -U phantom-audio

    Fixes

    • Output writes are now always confined to a sandbox (default ~/.phantom/output, override with PHANTOM_OUTPUT_DIR). Closes an arbitrary file-write path in the default configuration.
    • Decode-bomb guards added to the stem-separation and render paths (duration/size caps + ffmpeg -max_alloc/-t/-fs).
    • Atomic, race-free output creation in reference matching; symlink TOCTOU hardening on confined input reads.

    Behavior change

    • Default output location moved from next to the input file to ~/.phantom/output. Set PHANTOM_OUTPUT_DIR to write elsewhere. Input reads stay unconfined unless PHANTOM_AUDIO_DIR is set.

    See the published Security Advisory for full details and CVEs.

  6. v1.3.0 May 20, 2026

    What's Changed

    All five domain expert skills (audio-diagnostician, mix-engineer, effects-engineer, mastering-engineer, session-architect) have been substantially rewritten with deeper decision trees, conflict resolution, and measurable verification criteria.

    Mix Engineer

    • Buried vocal diagnostic sequence with fallback chain
    • Three-way frequency conflict resolution (home-band assignment)
    • Compression/EQ interaction awareness (re-check threshold after EQ moves)
    • Per-section processing for density changes across song sections
    • Cumulative thinning detection after HPF passes

    Mastering Engineer

    • Corrective-only 6 dB send-back threshold (enhancement and album adaptation excluded)
    • Minimum-phase vs linear-phase EQ decision tree
    • Compressor-limiter attack interaction for punch preservation
    • Section-aware mastering automation
    • Parallel compression skip on over-compressed material
    • Pass/fail QC thresholds for final delivery

    Effects Engineer

    • Pre-reverb ambiance assessment (dry studio vs live room)
    • Dual-bus mono-safety for extreme width intent
    • Chain order rationale (distortion→reverb vs reverb→distortion)
    • Inter-effect coherence framework
    • Bus vs individual effect routing decision matrix
    • Stem delivery considerations for send/return effects

    Audio Diagnostician

    • Creative intent detection before flagging (aesthetic noise, player's tone)
    • Per-section cumulative noise calculation
    • Confidence prefixes on all findings (Definite/Likely/Possible)
    • M/S detection before phase correlation flagging
    • Pan-aware masking analysis
    • Playback context reporting (headphone vs PA)

    Session Architect

    • Time-pressure prep triage (immediate vs deferrable)
    • Complexity-driven scaling override (instrument density, not just stem count)
    • Multi-format delivery architecture from session start
    • Mid-session track expansion procedures
    • Creative direction override documentation
    • Headphone feed independence routing

    Housekeeping

    • Remove SKILL-AUDIT.md from tracked files
    • Add .claudeignore
    • Update .gitignore to exclude docs/research

    Full Changelog: https://github.com/fadelabs/phantom/compare/v1.2.4...v1.3.0

  7. v1.2.4 May 14, 2026

    What's Changed

    Phases 21-22 of the v1.2 milestone, plus CI fixes.

    Performance & Resilience (Phase 21)

    • Thread-safe LRU analysis cache eliminates redundant computation across comparison calls
    • Polyphase FIR resampling for cross-sample-rate comparison (auto-resamples instead of erroring)
    • FFT spectrum sharing in detect_problems — eliminates 4 redundant FFT passes
    • Environment variable helpers (PHANTOM_PHAT_WINDOW_S, PHANTOM_MASKING_TOP_N) for tuning
    • Adaptive top_n for multi-stem masking based on stem count

    Code Review Fixes (Phase 21)

    • Sentinel object for cache miss instead of None (prevents false hits)
    • fcntl.flock advisory locking replaces TOCTOU-vulnerable O_CREAT|O_EXCL pattern
    • Exception chaining with from exc in env helpers
    • Integer array overflow protection in RMS calculations
    • Resampling log downgraded from warning to info (expected operation)

    Test Hardening & CI (Phase 22)

    • 60-second stereo fixture for duration-handling tests
    • Error schema consistency tests for all 18 MCP tools
    • Plugin skill content validation (frontmatter, tool references, domain keywords)
    • Long audio duration tests with 120s timeout guards
    • Optional dependency integration tests (matchering, demucs, pedalboard)
    • GitHub Actions CI workflow — Python 3.10 + 3.12 matrix, ruff + pytest
    • Dependabot configuration for pip and GitHub Actions updates

    CI Fixes

    • Use setup-uv@v7 (v8 not yet published)
    • Install dev extras for ruff and pytest in CI
    • Pedalboard skip guards for optional dependency tests
    • tomllib fallback for Python 3.10 compatibility

    Full Changelog: https://github.com/fadelabs/phantom/compare/v1.2.3...v1.2.4

  8. v1.2.3 May 13, 2026

    What's Changed

    Phases 18-24 of the v1.2 milestone.

    Bug Fixes & UX (Phase 18)

    • Reaper setup improvements with FFmpeg/SWS detection
    • CLI render command with Matchering integration
    • Audio fix pipeline CLI command

    Tech Debt (Phase 19)

    • Server handler deduplication (~400 lines removed)
    • Complete test coverage for CLI and processing modules

    Security Hardening (Phase 20)

    • Input sanitization across all MCP tools
    • Path security for audio file access
    • Profile loading hardened against JSON injection

    Audio Processing (Phase 23)

    • Auto-fix pipeline for audio problem remediation
    • Parametric EQ recipe generation from problem detection
    • Processing comparison with before/after analysis

    Overengineering Audit (Phase 24)

    • wrap_errors decorator replaces 12 inline try/except patterns
    • Band-excess detector deduplication (3 functions → 1)
    • comparison/ subpackage consolidated (5 files → 1)
    • Dead code and proxy class removal
    • All 19 MCP tools using uniform error handling
    • Code review findings fixed (lock leak, cache bug, nan guards, FIPS compliance)

    Stats

    • Tests: 883 passed, 4 skipped
    • Net change: +6,052 / -1,544 lines across 57 files

    Full Changelog: https://github.com/fadelabs/phantom/compare/v1.2.2...v1.2.3

  9. v1.2.2 May 14, 2026

    What's Changed

    Security & Safety Gates (Phase 17.1)

    • Pre-commit framework with gitleaks secret scanning (v8.30.1)
    • PII detection hook — blocks personal info and absolute paths in commits
    • Large binary hook — blocks audio files >1MB from being committed
    • Planning docs hook — prevents internal .planning/ docs from leaking
    • GitHub Actions security scan CI for PRs and pushes to main
    • .gitignore extended with credential file patterns (*.pem, *.key, *.p12)

    Bug Fixes

    • Version string drift fixed (__init__.py now matches pyproject.toml)
    • Path validation added to phantom render command
    • Pytest restored to pre-push hook
    • Gitleaks allowlist narrowed from tests/ to tests/fixtures/
    • actions/checkout downgraded from v6 to v4 (v6 doesn't exist)

    Docs

    • Star badge, PayPal support link, and GitHub Sponsor button added
    • CONTRIBUTING.md updated with pre-commit install instructions

    Full Changelog: https://github.com/fadelabs/phantom/compare/v1.2.1...v1.2.2

  10. v1.2.1 May 4, 2026

    📖 Documentation · Getting Started · Website

    What's new

    • Install telemetry — install script reports anonymous install events (started, completed, failed) to fadelab.net for platform support decisions
    • Install URL — curl -sSL https://fadelab.net/install | bash (redirects to latest installer)
    • README — added docs links, updated contact to hello@fadelab.net

    Install

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

    Or try without installing:

    uvx phantom-audio analyze your-track.wav
  11. v1.2.0 May 14, 2026

    What's Changed

    Hardening (PR #21)

    • TOCTOU race fix in profile caching
    • Demucs 600s timeout via ThreadPoolExecutor
    • Lock file prevents concurrent match_to_reference output races

    CLI & Setup

    • phantom setup — one-command onboarding (MCP config, plugin install, Reaper bridge)
    • phantom version / phantom update / phantom uninstall lifecycle commands
    • Claude Code marketplace manifest for plugin installation
    • MCP config defaults to ~/.mcp.json (global) for new users

    Audio Diagnostician Skill (autoresearch 55 → 84)

    • Instrument-aware phase correlation thresholds
    • Cumulative noise math with worked examples
    • Live recording bleed vs masking distinction
    • Pre-mastering borderline pass/fail table
    • Spectral centroid edge cases for instrument identification
    • Concrete EQ prescriptions and tool recommendations

    Installer & Docs

    • uv-first install (pip fails on stock macOS due to PEP 668)
    • Interactive extras prompt with size/license info
    • Pin uv bootstrap to v0.11.7 for supply chain safety
    • Patent pending notice added to README

    Full Changelog: https://github.com/fadelabs/phantom/compare/v1.1.0...v1.2.0

  12. v1.1.0 May 2, 2026

    Phantom v1.1.0

    First tagged release. Includes the complete v1.0 analysis engine and v1.1 CLI tools.

    What's included

    • 17 MCP analysis tools — spectrum, loudness, dynamics, stereo, phase, problems, masking, comparison, matching, separation, diagnostics
    • 5 domain expert skills — mix engineer, effects engineer, mastering engineer, audio diagnostician, session architect
    • 9 genre reference profiles — pop, rock, hip-hop, electronic, EDM, metal, rock-metal, lo-fi, ambient
    • CLI tools — phantom analyze, compare, separate, render, setup-reaper, doctor, version, update, uninstall
    • Reaper DAW integration — auto-setup bridge with phantom setup-reaper
    • Self-update system — phantom update checks GitHub for new versions
    • Clean uninstall — phantom uninstall removes all artifacts

    Install

    pip install git+https://github.com/fadelabs/phantom

    Or try without installing:

    uvx phantom-audio analyze your-track.wav