v1.3.1 security release

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.

v1.3.0 - Skill Rebuild

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: v1.2.4...v1.3.0

v1.2.4 — Performance, Test Hardening & CI

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: v1.2.3...v1.2.4

v1.2.3 — Hardening & Simplification

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: v1.2.2...v1.2.3

v1.2.2 — Repo Safety Gates

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: v1.2.1...v1.2.2

v1.2.1

📖 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

v1.2.0 — Setup, Skills Optimization & UX

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: v1.1.0...v1.2.0

v1.1.0

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