phantom-audio 1.1.0__tar.gz

phantom_audio-1.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Report a problem with Phantom
+labels: bug
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. ...
+2. ...
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include error messages or tracebacks if available.
+
+## Environment
+
+- **OS:** (e.g., macOS 15, Ubuntu 24.04, Windows 11)
+- **Python version:** (e.g., 3.12.5)
+- **Phantom version:** (run `phantom --version` or `python -c "import phantom; print(phantom.__version__)"`)
+- **Installation method:** (pip, uv, from source)
+- **Optional extras installed:** (separation, matching, processing)
+
+## Additional Context
+
+Any other relevant information (audio file details, MCP client, etc.).

phantom_audio-1.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature Request
+about: Suggest an idea for Phantom
+labels: enhancement
+---
+
+## Problem
+
+What problem does this feature solve? What's missing?
+
+## Proposed Solution
+
+How would you like this to work?
+
+## Alternatives Considered
+
+Any other approaches you've thought about.
+
+## Additional Context
+
+Any other relevant information (use cases, examples, references).

phantom_audio-1.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+Brief description of what this PR does and why.
+
+## Changes
+
+- ...
+- ...
+
+## Test Plan
+
+How was this tested?
+
+- [ ] New tests added
+- [ ] Existing tests pass
+
+## Checklist
+
+- [ ] Tests pass (`uv run pytest tests/ -x -q`)
+- [ ] Linting passes (`uv tool run ruff check src/ tests/`)
+- [ ] Formatting passes (`uv tool run ruff format --check src/ tests/`)
+

phantom_audio-1.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Audio files — managed outside git
+*.wav
+*.mp3
+*.flac
+*.aiff
+*.ogg
+*.m4a
+!examples/demo.wav
+
+# Live test audio -- not committed (D-02)
+tests/fixtures/live/
+
+# DAW project files
+*.cpr
+*.bak
+*.flp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude local
+.claude.local.md
+
+# Environment
+.env
+.env.*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+.venv/
+venv/
+
+# Development planning (internal only)
+.planning/
+
+# Claude Code local config
+.claude/
+.mcp.json
+
+# Internal design specs and milestone plans
+docs/superpowers/
+
+# Skill evaluation workspaces (contain local paths)
+plugin/eval-workspaces/
+
+# Local skill development
+plugin/skills-local/
+
+# Reference materials
+resources/
+
+# autoresearch runs
+.autoresearch/
+
+# Local working files
+.superpowers/

phantom_audio-1.1.0/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the Phantom codebase.
+
+## Project
+
+Phantom is an AI audio engineering system. It combines an MCP server for audio analysis with Claude Code skills encoding professional mixing/mastering expertise, integrated with Reaper via MCP for DAW control.
+
+**Core Value:** Claude can analyze any audio file or set of stems and produce actionable, measurement-backed mixing and mastering guidance calibrated to a reference target.
+
+## Architecture
+
+- **MCP Server** (`src/phantom/`) -- Python, audio analysis via Essentia + scipy/numpy, served through FastMCP
+- **Claude Code Plugin** (`plugin/`) -- 5 domain expert skills: mix-engineer, effects-engineer, mastering-engineer, audio-diagnostician, session-architect
+- **CLI** (`src/phantom/cli/`) -- Rich terminal interface for analysis, comparison, separation, rendering
+- **Reference Profiles** (`src/phantom/profiles/`) -- 9 genre spectral and dynamics targets as JSON
+- **DAW Control** -- via external Reaper MCP server (TwelveTake recommended)
+
+## Tech Stack
+
+| Library | Purpose |
+|---------|---------|
+| Python 3.10+ | Runtime |
+| essentia | Primary analysis engine (spectral, loudness, problem detection) |
+| scipy / numpy | Signal processing, array operations |
+| soundfile | WAV I/O |
+| pydantic | Typed response models |
+| FastMCP 2.x | MCP server framework |
+| click + rich | CLI interface |
+
+Optional: demucs (stem separation), matchering (reference matching, GPLv3), pedalboard (audio processing)
+
+## Conventions
+
+### Code Patterns
+
+- All analysis modules follow: input guard -> analyze -> return Pydantic model
+- Optional dependencies use lazy imports with `DependencyMissingError`
+- `PhantomError` hierarchy with musician-friendly error messages
+- Env var configuration: `PHANTOM_AUDIO_DIR`, `PHANTOM_OUTPUT_DIR`, `PHANTOM_MAX_DURATION`, `PHANTOM_MAX_FILE_SIZE`
+
+### Testing
+
+- All tests use synthetic audio fixtures (no real audio committed)
+- pytest 8.x with pytest-asyncio
+- Run: `uv run pytest tests/ -x -q`
+
+### Pre-push Checks
+
+- Linting: `uv tool run ruff check src/ tests/`
+- Formatting: `uv tool run ruff format --check src/ tests/`
+- Tests: `uv run pytest tests/ -x -q --tb=short`
+- Hook: `scripts/pre-push` (auto-runs on git push)
+
+## Privacy
+
+Artist personal information must never appear in commits or public-facing documentation. Reference artists by first name only in internal docs, never in committed code.
+
+## Key Decisions
+
+- **AGPL-3.0** -- open source, copyleft (commercial licensing available separately)
+- **Reaper over Cubase** for DAW integration (900+ API functions vs sandboxed JS)
+- **Monorepo** -- MCP server usable by any MCP client, skills are Claude Code specific
+- **Essentia as primary engine** -- 10-25x faster than librosa for feature extraction
+- **Dynamic reference system** -- accepts artist name, genre, song title, or WAV file as mixing/mastering target
+
+## Entry Points
+
+| Command | Source | Description |
+|---------|--------|-------------|
+| `phantom` | `src/phantom/cli/__init__.py` | CLI entry point (click group) |
+| `phantom-mcp` | `src/phantom/server.py` | MCP server entry point |
+
+### MCP Tools (17)
+
+`analyze_spectrum`, `analyze_loudness`, `analyze_dynamics`, `analyze_stereo`, `analyze_phase`, `compare_phase`, `detect_problems`, `analyze_masking`, `analyze_masking_matrix`, `multi_stem_masking`, `compare_to_profile`, `compare_to_reference`, `match_to_reference`, `separate_stems`, `full_diagnostic`, `batch_diagnostic`, `setup_reaper`
+
+### CLI Commands
+
+`phantom analyze`, `phantom compare`, `phantom separate`, `phantom render`, `phantom setup-reaper`, `phantom serve`
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+<!-- For detailed internal technical research (dependency analysis, alternatives considered, -->
+<!-- version pinning rationale), see .claude.local.md (not committed). -->

phantom_audio-1.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Code of Conduct
+
+This project follows the **Contributor Covenant Code of Conduct, version 2.1**.
+
+The full text is available at:
+https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project team at **phantom-audio@proton.me**.
+
+All complaints will be reviewed and investigated promptly and fairly. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

phantom_audio-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing to Phantom
+
+Thank you for your interest in contributing to Phantom! This guide will help you get started.
+
+Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) in all interactions.
+
+Contributions are welcome under the [AGPL-3.0](LICENSE) license (inbound = outbound).
+
+## Development Setup
+
+1. Fork and clone the repository:
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/phantom.git
+   cd phantom
+   ```
+
+2. Install dependencies (requires Python 3.10+ and [uv](https://docs.astral.sh/uv/)):
+
+   ```bash
+   uv sync --dev
+   ```
+
+   Or with pip:
+
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+3. Install the pre-push hook:
+
+   ```bash
+   ln -sf ../../scripts/pre-push .git/hooks/pre-push
+   ```
+
+4. Run the test suite:
+
+   ```bash
+   uv run pytest tests/ -x -q
+   ```
+
+## Code Style
+
+- **Linting:** `uv tool run ruff check src/ tests/`
+- **Formatting:** `uv tool run ruff format src/ tests/`
+- The pre-push hook runs both automatically before each push
+- No manual type checking required (essentia lacks type stubs)
+
+## Architecture Overview
+
+- `src/phantom/` — Core analysis modules, MCP server, CLI entry points
+- `plugin/` — Claude Code plugin with 5 domain expert skills
+- `tests/` — All tests use synthetic audio fixtures (no real audio files in repo)
+- `docs/workflows/` — DAW integration workflow documentation
+- `src/phantom/profiles/` — Genre reference profiles (JSON)
+
+See [CLAUDE.md](CLAUDE.md) for deeper architectural guidance.
+
+## How to Contribute
+
+**Bug reports:** Use the [bug report template](https://github.com/fadelabs/phantom/issues/new?template=bug_report.md)
+
+**Feature requests:** Use the [feature request template](https://github.com/fadelabs/phantom/issues/new?template=feature_request.md)
+
+**Pull requests:**
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Implement your changes
+4. Ensure all checks pass
+5. Open a pull request
+
+All PRs require:
+
+- Tests passing (`uv run pytest tests/ -x -q`)
+- Ruff linting clean (`uv tool run ruff check src/ tests/`)
+- Ruff formatting clean (`uv tool run ruff format --check src/ tests/`)
+
+
+New analysis features should follow existing module patterns: input guard, analyze, return Pydantic model. See any module in `src/phantom/` for examples.
+
+Optional dependencies must use lazy imports with `DependencyMissingError`.
+
+## Testing
+
+- All tests use synthetic audio fixtures generated in `tests/conftest.py`
+- Never commit real audio files to the repository
+- Run a single test file: `uv run pytest tests/test_spectral.py -x -v`
+- Run the full suite: `uv run pytest tests/ -v`
+- Test marker: `@pytest.mark.live` for tests requiring real audio (gitignored fixtures)
+
+## Optional Dependencies
+
+Phantom uses a tiered dependency system:
+
+| Tier | Packages | Install |
+|------|----------|---------|
+| **Core** | essentia, scipy, numpy, soundfile, pydantic, FastMCP | `uv sync` |
+| **Dev** | pytest, ruff, pyloudnorm | `uv sync --dev` |
+| **Separation** | demucs, torch | `uv sync --extra separation` |
+| **Matching** | matchering (GPLv3) | `uv sync --extra matching` |
+| **Processing** | pedalboard | `uv sync --extra processing` |
+| **Analysis** | librosa | `uv sync --extra analysis` |
+
+## License
+
+By submitting a contribution, you agree that your work is licensed under [AGPL-3.0](LICENSE), the same license as the project.