Skip to content

Changelog

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

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

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

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

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

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

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

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