Upload folder using huggingface_hub

.env.example

@@ -0,0 +1,12 @@
+# StemSplitter Configuration
+STEMSPLITTER_OUTPUT_DIR=./output
+STEMSPLITTER_MODEL_DIR=/tmp/audio-separator-models/
+STEMSPLITTER_2STEM_MODEL=model_mel_band_roformer_ep_3005_sdr_11.4360.ckpt
+STEMSPLITTER_4STEM_MODEL=htdemucs_ft.yaml
+STEMSPLITTER_OUTPUT_FORMAT=WAV
+STEMSPLITTER_OUTPUT_BITRATE=320k
+STEMSPLITTER_SAMPLE_RATE=44100
+STEMSPLITTER_NORMALIZATION=0.9
+STEMSPLITTER_LOG_LEVEL=WARNING
+STEMSPLITTER_WEB_HOST=127.0.0.1
+STEMSPLITTER_WEB_PORT=7860

.github/workflows/update_space.yml

@@ -0,0 +1,28 @@
+name: Run Python script
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.9'
+
+    - name: Install Gradio
+      run: python -m pip install gradio
+
+    - name: Log in to Hugging Face
+      run: python -c 'import huggingface_hub; huggingface_hub.login(token="${{ secrets.hf_token }}")'
+
+    - name: Deploy to Spaces
+      run: gradio deploy

.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Environment
+.env
+.venv/
+
+# Output
+output/
+
+# Models (large, auto-downloaded)
+/tmp/audio-separator-models/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Claude
+.claude/

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,37 @@
+[
+  "tests/test_cli.py::TestCLI::test_2stem_default",
+  "tests/test_cli.py::TestCLI::test_4stem_flac",
+  "tests/test_cli.py::TestCLI::test_custom_output_dir",
+  "tests/test_cli.py::TestCLI::test_help",
+  "tests/test_cli.py::TestCLI::test_missing_file",
+  "tests/test_cli.py::TestCLI::test_mode_shown_in_output",
+  "tests/test_cli.py::TestCLI::test_mp3_format",
+  "tests/test_cli.py::TestCLI::test_output_lists_files",
+  "tests/test_config.py::TestSettings::test_defaults",
+  "tests/test_config.py::TestSettings::test_env_override",
+  "tests/test_config.py::TestSettings::test_get_settings_returns_fresh_instance",
+  "tests/test_config.py::TestSettings::test_immutability",
+  "tests/test_config.py::TestSettings::test_model_defaults",
+  "tests/test_config.py::TestSettings::test_output_dir_default",
+  "tests/test_separator.py::TestOutputFormat::test_format_values",
+  "tests/test_separator.py::TestStemLabels::test_four_stem_labels",
+  "tests/test_separator.py::TestStemLabels::test_two_stem_labels",
+  "tests/test_separator.py::TestStemMode::test_four_stem_value",
+  "tests/test_separator.py::TestStemMode::test_from_string",
+  "tests/test_separator.py::TestStemMode::test_two_stem_value",
+  "tests/test_separator.py::TestStemSplitter::test_file_not_found",
+  "tests/test_separator.py::TestStemSplitter::test_format_override",
+  "tests/test_separator.py::TestStemSplitter::test_model_caching",
+  "tests/test_separator.py::TestStemSplitter::test_model_override",
+  "tests/test_separator.py::TestStemSplitter::test_model_switch",
+  "tests/test_separator.py::TestStemSplitter::test_result_contains_input_file",
+  "tests/test_separator.py::TestStemSplitter::test_result_contains_model_used",
+  "tests/test_separator.py::TestStemSplitter::test_separate_2stem",
+  "tests/test_separator.py::TestStemSplitter::test_separate_4stem",
+  "tests/test_separator.py::TestStemSplitter::test_separation_runtime_error",
+  "tests/test_web.py::TestWebApp::test_app_creation",
+  "tests/test_web.py::TestWebApp::test_separate_audio_2stem",
+  "tests/test_web.py::TestWebApp::test_separate_audio_4stem",
+  "tests/test_web.py::TestWebApp::test_separate_audio_format_passed",
+  "tests/test_web.py::TestWebApp::test_separate_audio_no_file"
+]

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -1,12 +1,161 @@
 ---
 title: StemSplitter
-emoji: 🚀
-colorFrom: blue
-colorTo: pink
+app_file: /Users/YaronMcNabb_1/Documents/StemSplitter/src/stemsplitter/web.py
 sdk: gradio
 sdk_version: 6.6.0
-app_file: app.py
-pinned: false
 ---
+# StemSplitter
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Audio stem separation tool that splits songs into individual components (vocals, drums, bass, instruments). Provides both a command-line interface and a Gradio web UI.
+
+Powered by open-source models via [audio-separator](https://github.com/nomadkaraoke/python-audio-separator):
+
+| Mode | Stems | Default Model |
+|------|-------|---------------|
+| 2-stem | Vocals, Instrumental | MelBand-RoFormer |
+| 4-stem | Vocals, Drums, Bass, Other | Demucs htdemucs_ft |
+
+## Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) for dependency management
+- FFmpeg (required by audio-separator for reading various audio formats)
+
+Install FFmpeg if you don't have it:
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Windows (via chocolatey)
+choco install ffmpeg
+```
+
+## Installation
+
+```bash
+git clone <repo-url>
+cd StemSplitter
+
+# Copy the example env file and adjust as needed
+cp .env.example .env
+
+# Install dependencies (CPU inference)
+uv sync --extra dev
+
+# Or, for GPU-accelerated inference (NVIDIA CUDA)
+uv sync --extra dev --extra gpu
+```
+
+Models are downloaded automatically on first use (~200 MB for 2-stem, ~800 MB for 4-stem).
+
+## Usage
+
+### CLI
+
+```bash
+# Basic 2-stem separation (vocals + instrumental), outputs WAV
+uv run stemsplitter song.mp3
+
+# 4-stem separation with FLAC output
+uv run stemsplitter song.wav -m 4stem -f FLAC
+
+# MP3 output to a custom directory
+uv run stemsplitter song.flac -m 2stem -f MP3 -o ./my_stems/
+
+# Override the model
+uv run stemsplitter song.mp3 --model htdemucs.yaml
+
+# Show all options
+uv run stemsplitter --help
+```
+
+**Supported input formats:** MP3, WAV, FLAC, OGG, M4A, and anything FFmpeg can decode.
+
+**Supported output formats:** WAV, MP3, FLAC (set via `-f` flag or `STEMSPLITTER_OUTPUT_FORMAT` in `.env`).
+
+### Web UI
+
+```bash
+uv run stemsplitter-web
+```
+
+Opens a Gradio interface (default: `http://127.0.0.1:7860`) where you can:
+
+1. Upload an audio file
+2. Choose separation mode (2-stem or 4-stem)
+3. Choose output format (WAV, MP3, FLAC)
+4. Click **Separate** and download individual stems
+
+A public share link is also generated automatically.
+
+## Project Structure
+
+```
+src/stemsplitter/
+    __init__.py      # Package version
+    config.py        # Settings loaded from .env with sensible defaults
+    separator.py     # Core StemSplitter class wrapping audio-separator
+    cli.py           # Click-based CLI entry point
+    web.py           # Gradio web UI
+
+tests/
+    conftest.py      # Shared fixtures (mock separator, synthetic audio)
+    test_config.py   # Configuration loading tests
+    test_separator.py# Core separation logic tests
+    test_cli.py      # CLI invocation tests
+    test_web.py      # Web UI handler tests
+```
+
+### Components
+
+- **config.py** -- Loads settings from a `.env` file using `python-dotenv`. All values are exposed as a frozen `Settings` dataclass. See `.env.example` for the full list of options.
+
+- **separator.py** -- Wraps `audio-separator` with a `StemSplitter` class that handles model selection per mode, lazy initialization (so imports are fast), and model caching (the model stays loaded between calls).
+
+- **cli.py** -- A Click command that accepts an input file and flags for mode, format, output directory, and model override.
+
+- **web.py** -- A Gradio Blocks app with audio upload, mode/format radio buttons, and per-stem audio outputs. The 4-stem outputs (drums, bass) are hidden in 2-stem mode.
+
+## Configuration
+
+All settings are configurable via environment variables in `.env`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STEMSPLITTER_OUTPUT_DIR` | `./output` | Directory for separated stems |
+| `STEMSPLITTER_MODEL_DIR` | `/tmp/audio-separator-models/` | Where downloaded models are cached |
+| `STEMSPLITTER_2STEM_MODEL` | `model_mel_band_roformer_ep_3005_sdr_11.4360.ckpt` | Model for 2-stem separation |
+| `STEMSPLITTER_4STEM_MODEL` | `htdemucs_ft.yaml` | Model for 4-stem separation |
+| `STEMSPLITTER_OUTPUT_FORMAT` | `WAV` | Default output format (WAV, MP3, FLAC) |
+| `STEMSPLITTER_OUTPUT_BITRATE` | `320k` | Bitrate for MP3 output |
+| `STEMSPLITTER_SAMPLE_RATE` | `44100` | Output sample rate |
+| `STEMSPLITTER_NORMALIZATION` | `0.9` | Peak normalization threshold |
+| `STEMSPLITTER_LOG_LEVEL` | `WARNING` | Logging verbosity (DEBUG, INFO, WARNING, ERROR) |
+| `STEMSPLITTER_WEB_HOST` | `127.0.0.1` | Web UI bind address |
+| `STEMSPLITTER_WEB_PORT` | `7860` | Web UI port |
+
+## Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Verbose output
+uv run pytest -v
+
+# With coverage report
+uv run pytest -v --cov=stemsplitter --cov-report=term-missing
+
+# Run a specific test file
+uv run pytest tests/test_separator.py
+```
+
+Tests use mocked models so no GPU or model downloads are required.
+
+## License
+
+MIT

pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "stemsplitter"
+version = "0.1.0"
+description = "Audio stem splitter with CLI and web UI"
+requires-python = ">=3.10"
+dependencies = [
+    "audio-separator[cpu]>=0.41.0",
+    "click>=8.1",
+    "gradio>=5.0",
+    "python-dotenv>=1.0",
+    "soundfile>=0.12",
+]
+
+[project.optional-dependencies]
+gpu = ["audio-separator[gpu]>=0.41.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-mock>=3.14",
+    "numpy>=1.26",
+]
+
+[project.scripts]
+stemsplitter = "stemsplitter.cli:main"
+stemsplitter-web = "stemsplitter.web:launch"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stemsplitter"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

requirements.txt

@@ -0,0 +1,6 @@
+audio-seperator click gradio python-dotenv soundfile
+audio-separator
+click
+gradio
+python-dotenv
+soundfile

src/stemsplitter/__init__.py

@@ -0,0 +1,3 @@
+"""StemSplitter - Audio stem separation with CLI and web UI."""
+
+__version__ = "0.1.0"

src/stemsplitter/cli.py

@@ -0,0 +1,97 @@
+"""Command-line interface for StemSplitter."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+import click
+
+from stemsplitter.config import get_settings
+from stemsplitter.separator import OutputFormat, StemMode, StemSplitter
+
+
+@click.command()
+@click.argument("input_file", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "-m",
+    "--mode",
+    type=click.Choice(["2stem", "4stem"], case_sensitive=False),
+    default="2stem",
+    show_default=True,
+    help="Separation mode: 2-stem (vocals/instrumental) or 4-stem.",
+)
+@click.option(
+    "-f",
+    "--format",
+    "output_format",
+    type=click.Choice(["WAV", "MP3", "FLAC"], case_sensitive=False),
+    default=None,
+    help="Output audio format. Defaults to value in .env or WAV.",
+)
+@click.option(
+    "-o",
+    "--output-dir",
+    type=click.Path(file_okay=False),
+    default=None,
+    help="Output directory. Defaults to value in .env or ./output.",
+)
+@click.option(
+    "--model",
+    default=None,
+    help="Override the model filename (e.g., htdemucs.yaml).",
+)
+def main(
+    input_file: str,
+    mode: str,
+    output_format: str | None,
+    output_dir: str | None,
+    model: str | None,
+) -> None:
+    """Separate audio stems from INPUT_FILE.
+
+    Splits an audio file into vocal and instrumental stems (2-stem mode)
+    or into vocals, drums, bass, and other (4-stem mode).
+
+    \b
+    Examples:
+        stemsplitter song.mp3
+        stemsplitter song.wav -m 4stem -f FLAC
+        stemsplitter song.flac -m 2stem -f MP3 -o ./stems/
+    """
+    settings = get_settings()
+
+    if output_dir:
+        settings = replace(settings, output_dir=output_dir)
+
+    Path(settings.output_dir).mkdir(parents=True, exist_ok=True)
+
+    splitter = StemSplitter(settings=settings)
+
+    stem_mode = StemMode(mode)
+    fmt = OutputFormat(output_format.upper()) if output_format else None
+
+    click.echo(
+        f"Processing: {input_file}\n"
+        f"Mode: {stem_mode.value} | "
+        f"Format: {(fmt or OutputFormat(settings.output_format)).value}"
+    )
+
+    try:
+        result = splitter.separate(
+            input_path=input_file,
+            mode=stem_mode,
+            output_format=fmt,
+            model_override=model,
+        )
+    except FileNotFoundError as exc:
+        click.secho(str(exc), fg="red", err=True)
+        sys.exit(1)
+    except RuntimeError as exc:
+        click.secho(f"Separation failed: {exc}", fg="red", err=True)
+        sys.exit(1)
+
+    click.secho("Separation complete!", fg="green")
+    for f in result.output_files:
+        click.echo(f"  -> {f}")

src/stemsplitter/config.py

@@ -0,0 +1,75 @@
+"""Application configuration loaded from .env with defaults."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+def _load_env() -> None:
+    """Load .env from project root (or CWD) if it exists."""
+    for candidate in (Path(__file__).resolve().parents[2], Path.cwd()):
+        env_path = candidate / ".env"
+        if env_path.is_file():
+            load_dotenv(env_path)
+            return
+    load_dotenv()
+
+
+_load_env()
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Immutable application settings."""
+
+    output_dir: str = field(
+        default_factory=lambda: os.getenv("STEMSPLITTER_OUTPUT_DIR", "./output")
+    )
+    model_file_dir: str = field(
+        default_factory=lambda: os.getenv(
+            "STEMSPLITTER_MODEL_DIR", "/tmp/audio-separator-models/"
+        )
+    )
+    default_2stem_model: str = field(
+        default_factory=lambda: os.getenv(
+            "STEMSPLITTER_2STEM_MODEL",
+            "model_mel_band_roformer_ep_3005_sdr_11.4360.ckpt",
+        )
+    )
+    default_4stem_model: str = field(
+        default_factory=lambda: os.getenv(
+            "STEMSPLITTER_4STEM_MODEL", "htdemucs_ft.yaml"
+        )
+    )
+    output_format: str = field(
+        default_factory=lambda: os.getenv("STEMSPLITTER_OUTPUT_FORMAT", "WAV")
+    )
+    output_bitrate: str = field(
+        default_factory=lambda: os.getenv("STEMSPLITTER_OUTPUT_BITRATE", "320k")
+    )
+    sample_rate: int = field(
+        default_factory=lambda: int(os.getenv("STEMSPLITTER_SAMPLE_RATE", "44100"))
+    )
+    normalization: float = field(
+        default_factory=lambda: float(
+            os.getenv("STEMSPLITTER_NORMALIZATION", "0.9")
+        )
+    )
+    log_level: str = field(
+        default_factory=lambda: os.getenv("STEMSPLITTER_LOG_LEVEL", "WARNING")
+    )
+    web_host: str = field(
+        default_factory=lambda: os.getenv("STEMSPLITTER_WEB_HOST", "127.0.0.1")
+    )
+    web_port: int = field(
+        default_factory=lambda: int(os.getenv("STEMSPLITTER_WEB_PORT", "7860"))
+    )
+
+
+def get_settings() -> Settings:
+    """Return a fresh Settings instance (re-reads env vars)."""
+    return Settings()

src/stemsplitter/separator.py

@@ -0,0 +1,147 @@
+"""Core audio stem separation logic."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+from stemsplitter.config import Settings, get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class StemMode(str, Enum):
+    """Separation mode."""
+
+    TWO_STEM = "2stem"
+    FOUR_STEM = "4stem"
+
+
+class OutputFormat(str, Enum):
+    """Supported output audio formats."""
+
+    WAV = "WAV"
+    MP3 = "MP3"
+    FLAC = "FLAC"
+
+
+STEM_LABELS: dict[StemMode, list[str]] = {
+    StemMode.TWO_STEM: ["Vocals", "Instrumental"],
+    StemMode.FOUR_STEM: ["Vocals", "Drums", "Bass", "Other"],
+}
+
+
+@dataclass
+class SeparationResult:
+    """Result of a stem separation operation."""
+
+    input_file: str
+    output_files: list[str]
+    mode: StemMode
+    output_format: OutputFormat
+    model_used: str
+
+
+class StemSplitter:
+    """High-level wrapper around audio-separator's Separator."""
+
+    def __init__(self, settings: Optional[Settings] = None) -> None:
+        self._settings = settings or get_settings()
+        self._separator = None
+        self._loaded_model: str | None = None
+
+    def _ensure_separator(self) -> None:
+        """Lazily create the underlying Separator instance."""
+        if self._separator is not None:
+            return
+
+        from audio_separator.separator import Separator
+
+        self._separator = Separator(
+            output_dir=self._settings.output_dir,
+            model_file_dir=self._settings.model_file_dir,
+            output_format=self._settings.output_format,
+            normalization_threshold=self._settings.normalization,
+            sample_rate=self._settings.sample_rate,
+            log_level=logging.getLevelName(self._settings.log_level),
+        )
+
+    def _load_model_for_mode(
+        self, mode: StemMode, model_override: str | None = None
+    ) -> str:
+        """Load the appropriate model, returning the model filename used."""
+        self._ensure_separator()
+
+        if model_override:
+            model_filename = model_override
+        elif mode == StemMode.TWO_STEM:
+            model_filename = self._settings.default_2stem_model
+        else:
+            model_filename = self._settings.default_4stem_model
+
+        if self._loaded_model != model_filename:
+            logger.info("Loading model: %s", model_filename)
+            self._separator.load_model(model_filename=model_filename)
+            self._loaded_model = model_filename
+
+        return model_filename
+
+    def separate(
+        self,
+        input_path: str | Path,
+        mode: StemMode = StemMode.TWO_STEM,
+        output_format: OutputFormat | None = None,
+        model_override: str | None = None,
+    ) -> SeparationResult:
+        """Separate an audio file into stems.
+
+        Args:
+            input_path: Path to the input audio file.
+            mode: TWO_STEM or FOUR_STEM separation.
+            output_format: Override the configured output format.
+            model_override: Use a specific model filename instead of the
+                           default for the chosen mode.
+
+        Returns:
+            SeparationResult with paths to all output stem files.
+
+        Raises:
+            FileNotFoundError: If input_path does not exist.
+            RuntimeError: If separation fails.
+        """
+        input_path = Path(input_path)
+        if not input_path.is_file():
+            raise FileNotFoundError(f"Input file not found: {input_path}")
+
+        fmt = output_format or OutputFormat(self._settings.output_format)
+        if output_format:
+            self._ensure_separator()
+            self._separator.output_format = fmt.value
+
+        model_used = self._load_model_for_mode(mode, model_override)
+
+        logger.info(
+            "Separating '%s' (mode=%s, format=%s, model=%s)",
+            input_path.name,
+            mode.value,
+            fmt.value,
+            model_used,
+        )
+
+        try:
+            output_files = self._separator.separate(str(input_path))
+        except Exception as exc:
+            raise RuntimeError(
+                f"Separation failed for '{input_path}': {exc}"
+            ) from exc
+
+        return SeparationResult(
+            input_file=str(input_path),
+            output_files=list(output_files),
+            mode=mode,
+            output_format=fmt,
+            model_used=model_used,
+        )

src/stemsplitter/web.py

@@ -0,0 +1,141 @@
+"""Gradio web interface for StemSplitter."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import gradio as gr
+
+from stemsplitter.config import get_settings
+from stemsplitter.separator import OutputFormat, StemMode, StemSplitter
+
+logger = logging.getLogger(__name__)
+
+_splitter: StemSplitter | None = None
+
+
+def _get_splitter() -> StemSplitter:
+    """Get or create the module-level StemSplitter singleton."""
+    global _splitter
+    if _splitter is None:
+        settings = get_settings()
+        Path(settings.output_dir).mkdir(parents=True, exist_ok=True)
+        _splitter = StemSplitter(settings=settings)
+    return _splitter
+
+
+def separate_audio(
+    audio_path: str,
+    mode: str,
+    output_format: str,
+    progress: gr.Progress = gr.Progress(),
+) -> list[str | None]:
+    """Gradio handler: separate audio and return stem file paths.
+
+    Returns a list of 4 file paths (padding with None for 2-stem mode).
+    """
+    if not audio_path:
+        raise gr.Error("Please upload an audio file.")
+
+    progress(0.1, desc="Initializing model...")
+    splitter = _get_splitter()
+
+    stem_mode = StemMode(mode)
+    fmt = OutputFormat(output_format)
+
+    progress(0.3, desc=f"Separating stems ({stem_mode.value})...")
+    result = splitter.separate(
+        input_path=audio_path,
+        mode=stem_mode,
+        output_format=fmt,
+    )
+
+    progress(1.0, desc="Done!")
+
+    outputs = list(result.output_files)
+    while len(outputs) < 4:
+        outputs.append(None)
+
+    return outputs[:4]
+
+
+def create_app() -> gr.Blocks:
+    """Build and return the Gradio Blocks application."""
+    with gr.Blocks(title="StemSplitter") as app:
+        gr.Markdown("# StemSplitter\nSeparate audio into individual stems.")
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                audio_input = gr.Audio(
+                    label="Upload Audio",
+                    type="filepath",
+                    sources=["upload"],
+                )
+                mode_radio = gr.Radio(
+                    choices=["2stem", "4stem"],
+                    value="2stem",
+                    label="Separation Mode",
+                    info="2-stem: Vocals + Instrumental | 4-stem: Vocals + Drums + Bass + Other",
+                )
+                format_radio = gr.Radio(
+                    choices=["WAV", "MP3", "FLAC"],
+                    value="WAV",
+                    label="Output Format",
+                )
+                separate_btn = gr.Button("Separate", variant="primary")
+
+            with gr.Column(scale=2):
+                vocals_output = gr.Audio(label="Vocals", type="filepath")
+                instrumental_output = gr.Audio(
+                    label="Instrumental", type="filepath"
+                )
+                drums_output = gr.Audio(
+                    label="Drums",
+                    type="filepath",
+                    visible=False,
+                )
+                bass_output = gr.Audio(
+                    label="Bass",
+                    type="filepath",
+                    visible=False,
+                )
+
+        def update_outputs_visibility(mode: str):
+            is_4stem = mode == "4stem"
+            return (
+                gr.update(label="Instrumental" if not is_4stem else "Other"),
+                gr.update(visible=is_4stem),
+                gr.update(visible=is_4stem),
+            )
+
+        mode_radio.change(
+            fn=update_outputs_visibility,
+            inputs=[mode_radio],
+            outputs=[instrumental_output, drums_output, bass_output],
+        )
+
+        separate_btn.click(
+            fn=separate_audio,
+            inputs=[audio_input, mode_radio, format_radio],
+            outputs=[
+                vocals_output,
+                instrumental_output,
+                drums_output,
+                bass_output,
+            ],
+        )
+
+    return app
+
+
+def launch() -> None:
+    """Entry point for `stemsplitter-web` console script."""
+    settings = get_settings()
+    app = create_app()
+    app.launch(
+        server_name=settings.web_host,
+        server_port=settings.web_port,
+        theme=gr.themes.Soft(),
+        share=True,
+    )

tests/conftest.py

@@ -0,0 +1,82 @@
+"""Shared test fixtures."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import numpy as np
+import pytest
+import soundfile as sf
+
+
+@pytest.fixture
+def tmp_output_dir(tmp_path: Path) -> Path:
+    """Provide a temporary output directory."""
+    d = tmp_path / "output"
+    d.mkdir()
+    return d
+
+
+@pytest.fixture
+def test_audio_path(tmp_path: Path) -> Path:
+    """Generate a small synthetic WAV file (~1 second, 44100 Hz, mono)."""
+    path = tmp_path / "test_tone.wav"
+    sr = 44100
+    duration = 1.0
+    t = np.linspace(0, duration, int(sr * duration), endpoint=False)
+    audio = (0.5 * np.sin(2 * np.pi * 440 * t)).astype(np.float32)
+    sf.write(str(path), audio, sr)
+    return path
+
+
+@pytest.fixture
+def mock_separator(mocker, tmp_output_dir: Path):
+    """Mock audio_separator.separator.Separator for 2-stem output."""
+    mock_cls = mocker.patch("audio_separator.separator.Separator")
+    instance = MagicMock()
+    mock_cls.return_value = instance
+
+    def fake_separate(input_path):
+        stem = Path(input_path).stem
+        files = []
+        for label in ["Vocals", "Instrumental"]:
+            out = tmp_output_dir / f"{stem}_{label}.wav"
+            out.touch()
+            files.append(str(out))
+        return files
+
+    instance.separate.side_effect = fake_separate
+    instance.load_model.return_value = None
+
+    return instance
+
+
+@pytest.fixture
+def mock_separator_4stem(mocker, tmp_output_dir: Path):
+    """Mock separator producing 4-stem outputs."""
+    mock_cls = mocker.patch("audio_separator.separator.Separator")
+    instance = MagicMock()
+    mock_cls.return_value = instance
+
+    def fake_separate(input_path):
+        stem = Path(input_path).stem
+        files = []
+        for label in ["Vocals", "Drums", "Bass", "Other"]:
+            out = tmp_output_dir / f"{stem}_{label}.wav"
+            out.touch()
+            files.append(str(out))
+        return files
+
+    instance.separate.side_effect = fake_separate
+    instance.load_model.return_value = None
+
+    return instance
+
+
+@pytest.fixture
+def env_settings(monkeypatch, tmp_output_dir: Path):
+    """Set environment variables for testing config."""
+    monkeypatch.setenv("STEMSPLITTER_OUTPUT_DIR", str(tmp_output_dir))
+    monkeypatch.setenv("STEMSPLITTER_LOG_LEVEL", "DEBUG")
+    monkeypatch.setenv("STEMSPLITTER_OUTPUT_FORMAT", "WAV")

tests/test_cli.py

@@ -0,0 +1,78 @@
+"""Tests for the CLI interface."""
+
+from click.testing import CliRunner
+
+from stemsplitter.cli import main
+
+
+class TestCLI:
+    def test_help(self):
+        """--help should succeed and show usage."""
+        runner = CliRunner()
+        result = runner.invoke(main, ["--help"])
+        assert result.exit_code == 0
+        assert "Separate audio stems" in result.output
+
+    def test_missing_file(self):
+        """Non-existent file should produce error."""
+        runner = CliRunner()
+        result = runner.invoke(main, ["/nonexistent.wav"])
+        assert result.exit_code != 0
+
+    def test_2stem_default(self, mock_separator, test_audio_path, env_settings):
+        """Default invocation should use 2-stem mode."""
+        runner = CliRunner()
+        result = runner.invoke(main, [str(test_audio_path)])
+        assert result.exit_code == 0
+        assert "Separation complete" in result.output
+
+    def test_4stem_flac(
+        self, mock_separator_4stem, test_audio_path, env_settings
+    ):
+        """4-stem + FLAC flags should be accepted."""
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            [str(test_audio_path), "-m", "4stem", "-f", "FLAC"],
+        )
+        assert result.exit_code == 0
+        assert "Separation complete" in result.output
+
+    def test_custom_output_dir(
+        self, mock_separator, test_audio_path, tmp_path, env_settings
+    ):
+        """--output-dir flag should override the default."""
+        custom_dir = tmp_path / "custom_out"
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            [str(test_audio_path), "-o", str(custom_dir)],
+        )
+        assert result.exit_code == 0
+        assert custom_dir.is_dir()
+
+    def test_output_lists_files(
+        self, mock_separator, test_audio_path, env_settings
+    ):
+        """Output should list the generated stem files."""
+        runner = CliRunner()
+        result = runner.invoke(main, [str(test_audio_path)])
+        assert "->" in result.output
+
+    def test_mode_shown_in_output(
+        self, mock_separator, test_audio_path, env_settings
+    ):
+        """The mode should be shown in processing output."""
+        runner = CliRunner()
+        result = runner.invoke(main, [str(test_audio_path), "-m", "2stem"])
+        assert "2stem" in result.output
+
+    def test_mp3_format(self, mock_separator, test_audio_path, env_settings):
+        """MP3 format flag should be accepted."""
+        runner = CliRunner()
+        result = runner.invoke(
+            main,
+            [str(test_audio_path), "-f", "MP3"],
+        )
+        assert result.exit_code == 0
+        assert "MP3" in result.output

tests/test_config.py

@@ -0,0 +1,51 @@
+"""Tests for configuration loading."""
+
+import pytest
+
+from stemsplitter.config import Settings, get_settings
+
+
+class TestSettings:
+    def test_defaults(self):
+        """Settings should provide sensible defaults."""
+        s = Settings()
+        assert s.output_format in ("WAV", "MP3", "FLAC")
+        assert s.sample_rate == 44100
+        assert s.normalization == 0.9
+        assert s.web_port == 7860
+        assert s.log_level == "WARNING"
+
+    def test_env_override(self, monkeypatch):
+        """Settings should pick up environment variable overrides."""
+        monkeypatch.setenv("STEMSPLITTER_OUTPUT_FORMAT", "FLAC")
+        monkeypatch.setenv("STEMSPLITTER_SAMPLE_RATE", "48000")
+        monkeypatch.setenv("STEMSPLITTER_WEB_PORT", "9090")
+        s = get_settings()
+        assert s.output_format == "FLAC"
+        assert s.sample_rate == 48000
+        assert s.web_port == 9090
+
+    def test_immutability(self):
+        """Settings instances should be frozen."""
+        s = Settings()
+        with pytest.raises(AttributeError):
+            s.output_dir = "/some/other/path"  # type: ignore
+
+    def test_output_dir_default(self):
+        """Default output_dir should be ./output."""
+        s = Settings()
+        assert s.output_dir == "./output"
+
+    def test_model_defaults(self):
+        """Default models should be set for both modes."""
+        s = Settings()
+        assert "mel_band_roformer" in s.default_2stem_model
+        assert "htdemucs_ft" in s.default_4stem_model
+
+    def test_get_settings_returns_fresh_instance(self, monkeypatch):
+        """get_settings should create a new instance each time."""
+        s1 = get_settings()
+        monkeypatch.setenv("STEMSPLITTER_OUTPUT_FORMAT", "MP3")
+        s2 = get_settings()
+        assert s2.output_format == "MP3"
+        assert s1 is not s2

tests/test_separator.py

@@ -0,0 +1,136 @@
+"""Tests for the core StemSplitter class."""
+
+import pytest
+
+from stemsplitter.separator import (
+    STEM_LABELS,
+    OutputFormat,
+    SeparationResult,
+    StemMode,
+    StemSplitter,
+)
+
+
+class TestStemMode:
+    def test_two_stem_value(self):
+        assert StemMode.TWO_STEM.value == "2stem"
+
+    def test_four_stem_value(self):
+        assert StemMode.FOUR_STEM.value == "4stem"
+
+    def test_from_string(self):
+        assert StemMode("2stem") == StemMode.TWO_STEM
+        assert StemMode("4stem") == StemMode.FOUR_STEM
+
+
+class TestOutputFormat:
+    def test_format_values(self):
+        assert OutputFormat.WAV.value == "WAV"
+        assert OutputFormat.MP3.value == "MP3"
+        assert OutputFormat.FLAC.value == "FLAC"
+
+
+class TestStemLabels:
+    def test_two_stem_labels(self):
+        assert STEM_LABELS[StemMode.TWO_STEM] == ["Vocals", "Instrumental"]
+
+    def test_four_stem_labels(self):
+        assert STEM_LABELS[StemMode.FOUR_STEM] == [
+            "Vocals",
+            "Drums",
+            "Bass",
+            "Other",
+        ]
+
+
+class TestStemSplitter:
+    def test_separate_2stem(self, mock_separator, test_audio_path, env_settings):
+        """2-stem separation should return 2 output files."""
+        splitter = StemSplitter()
+        result = splitter.separate(
+            input_path=test_audio_path,
+            mode=StemMode.TWO_STEM,
+        )
+        assert isinstance(result, SeparationResult)
+        assert len(result.output_files) == 2
+        assert result.mode == StemMode.TWO_STEM
+        mock_separator.load_model.assert_called_once()
+
+    def test_separate_4stem(
+        self, mock_separator_4stem, test_audio_path, env_settings
+    ):
+        """4-stem separation should return 4 output files."""
+        splitter = StemSplitter()
+        result = splitter.separate(
+            input_path=test_audio_path,
+            mode=StemMode.FOUR_STEM,
+        )
+        assert len(result.output_files) == 4
+        assert result.mode == StemMode.FOUR_STEM
+
+    def test_format_override(self, mock_separator, test_audio_path, env_settings):
+        """Output format override should be reflected in result."""
+        splitter = StemSplitter()
+        result = splitter.separate(
+            input_path=test_audio_path,
+            mode=StemMode.TWO_STEM,
+            output_format=OutputFormat.FLAC,
+        )
+        assert result.output_format == OutputFormat.FLAC
+
+    def test_model_caching(self, mock_separator, test_audio_path, env_settings):
+        """Same mode twice should NOT reload the model."""
+        splitter = StemSplitter()
+        splitter.separate(test_audio_path, mode=StemMode.TWO_STEM)
+        splitter.separate(test_audio_path, mode=StemMode.TWO_STEM)
+        assert mock_separator.load_model.call_count == 1
+
+    def test_model_switch(self, mock_separator, test_audio_path, env_settings):
+        """Switching modes should reload the model."""
+        splitter = StemSplitter()
+        splitter.separate(test_audio_path, mode=StemMode.TWO_STEM)
+        splitter.separate(test_audio_path, mode=StemMode.FOUR_STEM)
+        assert mock_separator.load_model.call_count == 2
+
+    def test_file_not_found(self, env_settings):
+        """Should raise FileNotFoundError for missing input."""
+        splitter = StemSplitter()
+        with pytest.raises(FileNotFoundError):
+            splitter.separate("/nonexistent/file.wav")
+
+    def test_model_override(self, mock_separator, test_audio_path, env_settings):
+        """Custom model_override should be passed through."""
+        splitter = StemSplitter()
+        splitter.separate(
+            test_audio_path,
+            mode=StemMode.TWO_STEM,
+            model_override="UVR_MDXNET_KARA_2.onnx",
+        )
+        mock_separator.load_model.assert_called_with(
+            model_filename="UVR_MDXNET_KARA_2.onnx"
+        )
+
+    def test_result_contains_input_file(
+        self, mock_separator, test_audio_path, env_settings
+    ):
+        """Result should reference the original input file."""
+        splitter = StemSplitter()
+        result = splitter.separate(test_audio_path, mode=StemMode.TWO_STEM)
+        assert result.input_file == str(test_audio_path)
+
+    def test_result_contains_model_used(
+        self, mock_separator, test_audio_path, env_settings
+    ):
+        """Result should reference which model was used."""
+        splitter = StemSplitter()
+        result = splitter.separate(test_audio_path, mode=StemMode.TWO_STEM)
+        assert "mel_band_roformer" in result.model_used
+
+    def test_separation_runtime_error(
+        self, mock_separator, test_audio_path, env_settings
+    ):
+        """RuntimeError should be raised if the underlying separator fails."""
+        mock_separator.separate.side_effect = Exception("Model crashed")
+        splitter = StemSplitter()
+        with pytest.raises(RuntimeError, match="Separation failed"):
+            splitter.separate(test_audio_path, mode=StemMode.TWO_STEM)

tests/test_web.py

@@ -0,0 +1,72 @@
+"""Tests for the Gradio web interface."""
+
+import pytest
+
+import stemsplitter.web as web_mod
+from stemsplitter.web import create_app, separate_audio
+
+
+@pytest.fixture(autouse=True)
+def _reset_splitter_singleton():
+    """Reset the module-level splitter before each test."""
+    web_mod._splitter = None
+    yield
+    web_mod._splitter = None
+
+
+class TestWebApp:
+    def test_app_creation(self):
+        """create_app() should return a Gradio Blocks instance."""
+        import gradio as gr
+
+        app = create_app()
+        assert isinstance(app, gr.Blocks)
+
+    def test_separate_audio_2stem(
+        self, mock_separator, test_audio_path, env_settings
+    ):
+        """Handler should return 4 values (2 real + 2 None) for 2-stem."""
+        outputs = separate_audio(
+            audio_path=str(test_audio_path),
+            mode="2stem",
+            output_format="WAV",
+        )
+        assert len(outputs) == 4
+        assert outputs[0] is not None
+        assert outputs[1] is not None
+        assert outputs[2] is None
+        assert outputs[3] is None
+
+    def test_separate_audio_4stem(
+        self, mock_separator_4stem, test_audio_path, env_settings
+    ):
+        """Handler should return 4 non-None values for 4-stem."""
+        outputs = separate_audio(
+            audio_path=str(test_audio_path),
+            mode="4stem",
+            output_format="WAV",
+        )
+        assert len(outputs) == 4
+        assert all(o is not None for o in outputs)
+
+    def test_separate_audio_no_file(self, env_settings):
+        """Handler should raise gr.Error when no file uploaded."""
+        import gradio as gr
+
+        with pytest.raises(gr.Error):
+            separate_audio(
+                audio_path="",
+                mode="2stem",
+                output_format="WAV",
+            )
+
+    def test_separate_audio_format_passed(
+        self, mock_separator, test_audio_path, env_settings
+    ):
+        """The output format choice should be forwarded to the splitter."""
+        outputs = separate_audio(
+            audio_path=str(test_audio_path),
+            mode="2stem",
+            output_format="FLAC",
+        )
+        assert len(outputs) == 4