Skip to content

Changelog

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

  1. 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

  2. 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

  3. 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

  4. 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
  5. 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

  6. 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