feat: split stem separation into phantom-audio-separation plugin package#43
Merged
Conversation
New sibling distribution carrying the Demucs/PyTorch dependency tree (issue #7). The implementation moves verbatim from phantom/separation.py into packages/phantom-audio-separation (phantom_separation.demucs_backend), registered under the phantom.separation entry-point group. Behavior tests move with it (all demucs mocked via sys.modules -- no torch execution). Root package wiring: - [tool.uv.workspace] members = packages/*, workspace source for the plugin - [separation] extra becomes a backward-compatible meta-installer pulling phantom-audio-separation; core deps stay torch-free - dev extra gains tomli for the py3.10 metadata test - uv.lock regenerated (workspace cycle phantom-audio[separation] -> phantom-audio-separation -> phantom-audio resolves cleanly) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…oint phantom/separation.py becomes a thin shim: it keeps SeparationResult and the separate_stems signature, discovers an installed backend plugin via the phantom.separation entry-point group, and dispatches to it. With no plugin installed it raises DependencyMissingError with the unchanged install hint (uv tool install "phantom-audio[separation]"). Plugin detection replaces the direct demucs import probe everywhere: - _diagnostics: separation_plugin_status() reports OK only when the entry point is present AND loads; demucs dropped from OPTIONAL_DEPS - phantom doctor: phantom-audio-separation row via plugin detection - MCP _startup_preflight: separation=OK/missing via plugin detection - phantom setup: probes the plugin and installs phantom-audio-separation Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
tests/test_separation.py rewritten around the shim: missing-plugin DependencyMissingError hint, backend dispatch passthrough, entry-point discovery, and a metadata test asserting no torch/torchaudio/demucs in phantom-audio's own dependencies or extras and that [separation] is exactly the phantom-audio-separation meta-installer. Doctor tests gain plugin-row coverage (OK only when loadable; missing plugin never fails overall health). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- ruff check/format now cover packages/ in CI and scripts/pre-push - optional-deps job runs packages/phantom-audio-separation/tests (the workspace member installs there via --extra separation; tests stay mock-based, no torch execution) - README notes the [separation] extra is a meta-installer for the sibling package; RELEASING.md documents building/publishing it Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
| """Importing the backend without demucs installed does not raise (SEP-02).""" | ||
| import builtins | ||
| import sys | ||
| import phantom_separation.demucs_backend |
| PathSecurityError, | ||
| ) | ||
|
|
||
| import phantom.separation as separation_mod |
test_import_without_demucs reloads the backend module, replacing its function objects; comparing ep.load() against the import captured at collection time then fails. Compare against the module attribute at assertion time instead (the same lookup ep.load() performs). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
| """The installed distribution exposes phantom.separation -> separate_stems.""" | ||
| from importlib.metadata import entry_points | ||
|
|
||
| import phantom_separation.demucs_backend as backend_mod |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Splits the
[separation]extra into a sibling distribution, per the plan in #7. The corephantom-audiopackage now carries zero PyTorch/Demucs dependency surface — its release cadence and platform matrix are decoupled from PyTorch's.packages/phantom-audio-separation/(v1.4.0): the Demucs implementation moved verbatim (path validation, decode-bomb guard, silent-input guard, timeout, safe stem names) intophantom_separation.demucs_backend, registered under thephantom.separationentry-point group. Depends onphantom-audio>=1.3.1,demucs>=4.0,torch>=2.0,torchaudio>=2.0.phantom/separation.pyis now a thin shim: keepsSeparationResultand theseparate_stems(input_path, output_dir)signature, discovers the installed backend via entry points, dispatches to it, and otherwise raisesDependencyMissingErrorwith the unchanged install hint (uv tool install "phantom-audio[separation]" --python 3.13). All consumers (phantom.__init__, MCP tool,phantom separate) work unchanged.[separation]extra becomes a backward-compatible meta-installer pullingphantom-audio-separation;[all]stays correct transitively. Thephantom-audio[separation]↔phantom-audio-separationworkspace cycle resolves cleanly inuv lock.phantom-audio[separation]into a separate distribution #7's doctor/preflight requirement): newseparation_plugin_status()in_diagnostics.pyreports OK only when the entry point is present and loads.phantom doctorgains aphantom-audio-separationrow, the MCP_startup_preflightreportsseparation=OK/missingfrom plugin detection, andphantom setupprobes/installs the sibling package.phantom-audio's dependencies or extras. The moved behavior tests (all demucs mocked viasys.modules— no torch execution in CI) live inpackages/phantom-audio-separation/testsand run in the optional-deps CI job, where the workspace member installs via--extra separation.packages/in CI andscripts/pre-push.Release note
Not published to PyPI here and no
phantom-audioversion bump — both belong to the pending 1.4.0 release train. Untilphantom-audio-separationis on PyPI,pip install "phantom-audio[separation]"from PyPI won't resolve the new extra; within this repo the uv workspace source covers it. RELEASING.md documents building/publishing the sibling package at release time.Closes #7
Test plan
uv run pytest tests/ -x -q— 1041 passed, 47 skippedPYTHONPATH=packages/phantom-audio-separation/src uv run pytest packages/phantom-audio-separation/tests -q— 13 passed, 1 skipped (entry-point registration test needs a real install; runs in the optional-deps CI job)uv tool run ruff check src/ tests/ packages/andruff format --check— cleanphantom.separate_stemsraisesDependencyMissingErrorwith the exact legacy hint when no plugin is installed;phantom doctor --jsonshows thephantom-audio-separationrow; MCP preflight printsseparation=missinguv sync --locked --extra devpasses with the regenerated lockfile🤖 Generated with Claude Code