chuja 0.1.0__tar.gz

chuja-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      # Lightweight install: the test suite lazy-imports / mocks the heavy ML
+      # stack (torch, demucs), so CI skips it entirely and stays fast.
+      - name: Install (no ML stack)
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest typer rich click
+          pip install -e . --no-deps
+
+      - name: Run tests
+        run: pytest -q

chuja-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+# Publishes on a GitHub Release. Uses PyPI Trusted Publishing (OIDC) — no API
+# token is ever stored or entered. PyPI must have a matching pending/trusted
+# publisher configured for this repo + workflow (see README "Publishing").
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi          # must match the environment set on the PyPI publisher
+    permissions:
+      id-token: write          # required for OIDC trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Verify metadata
+        run: |
+          python -m pip install twine
+          python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

chuja-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments (never commit the multi-hundred-MB ML stack)
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# chuja output
+stems/
+*.stems/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/

chuja-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Nakitare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chuja-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: chuja
+Version: 0.1.0
+Summary: Separate a song into stems (vocals/drums/bass/other) from a local file — or, opt-in, from a URL.
+Project-URL: Homepage, https://github.com/dnakitare/chuja
+Project-URL: Issues, https://github.com/dnakitare/chuja/issues
+Author: Daniel Nakitare
+License: MIT
+License-File: LICENSE
+Keywords: audio,demucs,karaoke,music,source-separation,stems,vocals
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.9
+Requires-Dist: demucs>=4.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: soundfile>=0.12.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: url
+Requires-Dist: yt-dlp>=2024.1.1; extra == 'url'
+Description-Content-Type: text/markdown
+
+# chuja
+
+[![CI](https://github.com/Dnakitare/chuja/actions/workflows/ci.yml/badge.svg)](https://github.com/Dnakitare/chuja/actions/workflows/ci.yml)
+
+Separate a song into its stems — **vocals, drums, bass, other** — from a local
+audio file, or (opt-in) from a YouTube / SoundCloud / direct URL. One command,
+portable output.
+
+![chuja mixing console](https://raw.githubusercontent.com/Dnakitare/chuja/main/docs/03-console.png)
+
+> *The `chuja serve` mixing console — one channel strip per stem with a live
+> waveform, solo/mute, faders, and sample-accurate synced playback.*
+
+`chuja` is a thin, friendly wrapper around two excellent open-source engines:
+
+- **[Demucs](https://github.com/facebookresearch/demucs)** (Meta) — state-of-the-art neural source separation.
+- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — used *only* for the optional URL-fetching feature.
+
+It does not reinvent either. What it adds is the glue: one pipeline from a
+source to clean, named, downloadable stem files, with sensible defaults and a
+polished CLI + Python API.
+
+---
+
+## Screenshots
+
+**Intake** — drop a file or paste a URL, pick a model / format / split:
+
+![chuja intake screen](https://raw.githubusercontent.com/Dnakitare/chuja/main/docs/01-intake.png)
+
+**Progress** — a real, per-chunk separation progress bar (not a fake spinner):
+
+![chuja separation progress](https://raw.githubusercontent.com/Dnakitare/chuja/main/docs/02-progress.png)
+
+**Console** — the per-stem mixing board shown at the top of this README.
+
+---
+
+## Install
+
+Install from source (not yet published to PyPI):
+
+```bash
+git clone https://github.com/dnakitare/chuja
+cd chuja
+
+# Core: separate LOCAL files. Pulls in Demucs (PyTorch).
+pip install .
+
+# Optional: add URL ingestion (YouTube/SoundCloud/etc.)
+pip install '.[url]'
+```
+
+### Install globally (run `chuja` from anywhere)
+
+```bash
+./install.sh
+```
+
+If this project already has a `.venv`, the installer just symlinks its `chuja`
+onto your PATH (`~/.local/bin` by default) — instant, nothing re-downloaded.
+With no `.venv`, it falls back to an isolated [pipx](https://pipx.pypa.io)
+install. Override the link location with `CHUJA_BIN=/usr/local/bin ./install.sh`.
+
+Prefer to do it by hand? `pipx install '.[url]'` from the project root, or
+`pip install --user '.[url]'`.
+
+### Requirements
+
+Requires **Python 3.9+** and **ffmpeg** on your PATH:
+
+| Platform | Install ffmpeg |
+| --- | --- |
+| macOS | `brew install ffmpeg` |
+| Ubuntu/Debian | `sudo apt install ffmpeg` |
+| Windows | `winget install Gyan.FFmpeg` |
+
+> The first separation downloads the model weights (~150 MB) once and caches them.
+
+## Usage (CLI)
+
+```bash
+# Local file → 4 stems as WAV under ./stems/<track>/
+chuja separate song.mp3
+
+# Pick a format and bundle into a portable zip
+chuja separate song.flac --format mp3 --zip -o ~/Desktop/stems
+
+# Karaoke / acapella split: one stem + everything else
+chuja separate song.mp3 --two-stems vocals
+
+# From a URL (requires the [url] extra)
+chuja separate "https://www.youtube.com/watch?v=..." --format mp3
+
+# Best-quality (slower) model, force a device
+chuja separate song.wav --model htdemucs_ft --device cpu
+
+# List available models
+chuja models
+```
+
+## Usage (library)
+
+```python
+import chuja
+
+result = chuja.separate(
+    "song.mp3",
+    out_dir="stems",
+    fmt="mp3",
+    two_stems=None,        # or "vocals" for a 2-stem split
+    zip_output=True,
+)
+print(result.track)        # "song"
+print(result.stems)        # {"vocals": Path(...), "drums": Path(...), ...}
+print(result.archive)      # Path("stems/song.zip")
+```
+
+## Models
+
+| Model | Stems | Notes |
+| --- | --- | --- |
+| `htdemucs` *(default)* | 4 | Best balance of speed and quality |
+| `htdemucs_ft` | 4 | Fine-tuned — best quality, ~4× slower |
+| `htdemucs_6s` | 6 | Adds piano + guitar (experimental) |
+| `mdx_extra` | 4 | Alternative MDX-challenge model |
+
+## A note on quality
+
+Separation quality is bounded by your **source** quality. Demucs is excellent,
+but it cannot recover information that lossy compression already discarded — a
+128 kbps MP3 in means audible artifacts in the stems out. Feed it the highest-
+fidelity source you have (WAV/FLAC > 320 kbps MP3 > a low-bitrate stream) for
+the cleanest results. `chuja` deliberately does **not** transcode before
+separation, so it never throws away quality you started with.
+
+Performance: separation is compute-heavy. It runs on CPU everywhere, and uses
+your GPU automatically when available — **CUDA** (NVIDIA) or **MPS** (Apple
+Silicon). GPU is many times faster than CPU for full songs.
+
+> **Platform note:** developed and tested on **macOS** (CPU and Apple
+> Silicon/MPS). The code is written to be cross-platform — its dependencies
+> (Demucs/PyTorch, soundfile, ffmpeg) all ship for Linux and Windows — but
+> separation hasn't been exercised on those yet. CI runs the test suite on
+> Linux. Reports from other platforms are welcome.
+
+## Responsible use
+
+The optional URL feature uses `yt-dlp`. Downloading content from YouTube,
+SoundCloud, and similar platforms may violate their Terms of Service, and the
+audio is almost always copyrighted. **You are solely responsible** for ensuring
+you have the right to download and process any audio you give to `chuja`
+(e.g. your own recordings, public-domain works, or content you are licensed to
+use). The core install ships *without* this capability for exactly this reason.
+
+## Releasing (maintainers)
+
+Releases publish to PyPI via **Trusted Publishing** (OIDC) — no API token is
+ever stored. One-time setup on PyPI
+([Publishing settings](https://pypi.org/manage/account/publishing/) → add a
+*pending publisher*):
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `chuja` |
+| Owner | `Dnakitare` |
+| Repository name | `chuja` |
+| Workflow name | `release.yml` |
+| Environment name | `pypi` |
+
+Then publish a version by cutting a GitHub Release (e.g. tag `v0.1.0`). The
+`release.yml` workflow builds the sdist + wheel and uploads them automatically.
+
+## License
+
+MIT.

chuja-0.1.0/README.md

@@ -0,0 +1,176 @@
+# chuja
+
+[![CI](https://github.com/Dnakitare/chuja/actions/workflows/ci.yml/badge.svg)](https://github.com/Dnakitare/chuja/actions/workflows/ci.yml)
+
+Separate a song into its stems — **vocals, drums, bass, other** — from a local
+audio file, or (opt-in) from a YouTube / SoundCloud / direct URL. One command,
+portable output.
+
+![chuja mixing console](https://raw.githubusercontent.com/Dnakitare/chuja/main/docs/03-console.png)
+
+> *The `chuja serve` mixing console — one channel strip per stem with a live
+> waveform, solo/mute, faders, and sample-accurate synced playback.*
+
+`chuja` is a thin, friendly wrapper around two excellent open-source engines:
+
+- **[Demucs](https://github.com/facebookresearch/demucs)** (Meta) — state-of-the-art neural source separation.
+- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — used *only* for the optional URL-fetching feature.
+
+It does not reinvent either. What it adds is the glue: one pipeline from a
+source to clean, named, downloadable stem files, with sensible defaults and a
+polished CLI + Python API.
+
+---
+
+## Screenshots
+
+**Intake** — drop a file or paste a URL, pick a model / format / split:
+
+![chuja intake screen](https://raw.githubusercontent.com/Dnakitare/chuja/main/docs/01-intake.png)
+
+**Progress** — a real, per-chunk separation progress bar (not a fake spinner):
+
+![chuja separation progress](https://raw.githubusercontent.com/Dnakitare/chuja/main/docs/02-progress.png)
+
+**Console** — the per-stem mixing board shown at the top of this README.
+
+---
+
+## Install
+
+Install from source (not yet published to PyPI):
+
+```bash
+git clone https://github.com/dnakitare/chuja
+cd chuja
+
+# Core: separate LOCAL files. Pulls in Demucs (PyTorch).
+pip install .
+
+# Optional: add URL ingestion (YouTube/SoundCloud/etc.)
+pip install '.[url]'
+```
+
+### Install globally (run `chuja` from anywhere)
+
+```bash
+./install.sh
+```
+
+If this project already has a `.venv`, the installer just symlinks its `chuja`
+onto your PATH (`~/.local/bin` by default) — instant, nothing re-downloaded.
+With no `.venv`, it falls back to an isolated [pipx](https://pipx.pypa.io)
+install. Override the link location with `CHUJA_BIN=/usr/local/bin ./install.sh`.
+
+Prefer to do it by hand? `pipx install '.[url]'` from the project root, or
+`pip install --user '.[url]'`.
+
+### Requirements
+
+Requires **Python 3.9+** and **ffmpeg** on your PATH:
+
+| Platform | Install ffmpeg |
+| --- | --- |
+| macOS | `brew install ffmpeg` |
+| Ubuntu/Debian | `sudo apt install ffmpeg` |
+| Windows | `winget install Gyan.FFmpeg` |
+
+> The first separation downloads the model weights (~150 MB) once and caches them.
+
+## Usage (CLI)
+
+```bash
+# Local file → 4 stems as WAV under ./stems/<track>/
+chuja separate song.mp3
+
+# Pick a format and bundle into a portable zip
+chuja separate song.flac --format mp3 --zip -o ~/Desktop/stems
+
+# Karaoke / acapella split: one stem + everything else
+chuja separate song.mp3 --two-stems vocals
+
+# From a URL (requires the [url] extra)
+chuja separate "https://www.youtube.com/watch?v=..." --format mp3
+
+# Best-quality (slower) model, force a device
+chuja separate song.wav --model htdemucs_ft --device cpu
+
+# List available models
+chuja models
+```
+
+## Usage (library)
+
+```python
+import chuja
+
+result = chuja.separate(
+    "song.mp3",
+    out_dir="stems",
+    fmt="mp3",
+    two_stems=None,        # or "vocals" for a 2-stem split
+    zip_output=True,
+)
+print(result.track)        # "song"
+print(result.stems)        # {"vocals": Path(...), "drums": Path(...), ...}
+print(result.archive)      # Path("stems/song.zip")
+```
+
+## Models
+
+| Model | Stems | Notes |
+| --- | --- | --- |
+| `htdemucs` *(default)* | 4 | Best balance of speed and quality |
+| `htdemucs_ft` | 4 | Fine-tuned — best quality, ~4× slower |
+| `htdemucs_6s` | 6 | Adds piano + guitar (experimental) |
+| `mdx_extra` | 4 | Alternative MDX-challenge model |
+
+## A note on quality
+
+Separation quality is bounded by your **source** quality. Demucs is excellent,
+but it cannot recover information that lossy compression already discarded — a
+128 kbps MP3 in means audible artifacts in the stems out. Feed it the highest-
+fidelity source you have (WAV/FLAC > 320 kbps MP3 > a low-bitrate stream) for
+the cleanest results. `chuja` deliberately does **not** transcode before
+separation, so it never throws away quality you started with.
+
+Performance: separation is compute-heavy. It runs on CPU everywhere, and uses
+your GPU automatically when available — **CUDA** (NVIDIA) or **MPS** (Apple
+Silicon). GPU is many times faster than CPU for full songs.
+
+> **Platform note:** developed and tested on **macOS** (CPU and Apple
+> Silicon/MPS). The code is written to be cross-platform — its dependencies
+> (Demucs/PyTorch, soundfile, ffmpeg) all ship for Linux and Windows — but
+> separation hasn't been exercised on those yet. CI runs the test suite on
+> Linux. Reports from other platforms are welcome.
+
+## Responsible use
+
+The optional URL feature uses `yt-dlp`. Downloading content from YouTube,
+SoundCloud, and similar platforms may violate their Terms of Service, and the
+audio is almost always copyrighted. **You are solely responsible** for ensuring
+you have the right to download and process any audio you give to `chuja`
+(e.g. your own recordings, public-domain works, or content you are licensed to
+use). The core install ships *without* this capability for exactly this reason.
+
+## Releasing (maintainers)
+
+Releases publish to PyPI via **Trusted Publishing** (OIDC) — no API token is
+ever stored. One-time setup on PyPI
+([Publishing settings](https://pypi.org/manage/account/publishing/) → add a
+*pending publisher*):
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `chuja` |
+| Owner | `Dnakitare` |
+| Repository name | `chuja` |
+| Workflow name | `release.yml` |
+| Environment name | `pypi` |
+
+Then publish a version by cutting a GitHub Release (e.g. tag `v0.1.0`). The
+`release.yml` workflow builds the sdist + wheel and uploads them automatically.
+
+## License
+
+MIT.

chuja-0.1.0/install.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# Install `chuja` globally so you can run it from any directory.
+#
+# Default (fast): if this project's .venv exists, symlink the `chuja` it
+#   already contains onto your PATH. No re-download of the ML stack.
+# Fallback (clean): if there's no .venv, do an isolated install with pipx.
+#
+# Override the link target with:  CHUJA_BIN=/usr/local/bin ./install.sh
+#
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BIN="${CHUJA_BIN:-$HOME/.local/bin}"
+
+if [ -x "$HERE/.venv/bin/chuja" ]; then
+    mkdir -p "$BIN"
+    ln -sf "$HERE/.venv/bin/chuja" "$BIN/chuja"
+    echo "✓ Linked chuja → $BIN/chuja  (reuses $HERE/.venv — nothing re-downloaded)"
+    case ":$PATH:" in
+        *":$BIN:"*)
+            echo "  Run it from anywhere:   chuja"
+            ;;
+        *)
+            echo "  ⚠ $BIN is not on your PATH yet. Add this to ~/.zshrc, then restart your shell:"
+            echo "      export PATH=\"$BIN:\$PATH\""
+            ;;
+    esac
+else
+    echo "No .venv here — installing in an isolated environment with pipx…"
+    if ! command -v pipx >/dev/null 2>&1; then
+        echo "✗ pipx not found. Install it first:  brew install pipx  (or: python3 -m pip install --user pipx)"
+        exit 1
+    fi
+    pipx install --force "$HERE"
+    pipx inject chuja yt-dlp   # optional URL-ingestion support
+    echo "✓ Installed with pipx.   Run:  chuja"
+fi
+
+echo
+echo "Try:   chuja            # interactive"
+echo "       chuja serve      # visual console"
+echo "       chuja song.mp3   # separate a file"

chuja-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chuja"
+version = "0.1.0"
+description = "Separate a song into stems (vocals/drums/bass/other) from a local file — or, opt-in, from a URL."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Daniel Nakitare" }]
+keywords = ["stems", "source-separation", "demucs", "audio", "music", "vocals", "karaoke"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+]
+
+# Core stays deliberately lean and legally unambiguous: separate a LOCAL file.
+dependencies = [
+    "demucs>=4.0.0",
+    "soundfile>=0.12.0",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+# URL ingestion (YouTube/SoundCloud/etc.) is opt-in. You are responsible for
+# complying with each platform's Terms of Service and applicable copyright law.
+url = ["yt-dlp>=2024.1.1"]
+dev = ["pytest>=8.0.0"]
+
+[project.scripts]
+chuja = "chuja.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/dnakitare/chuja"
+Issues = "https://github.com/dnakitare/chuja/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chuja"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/chuja/web/console.html" = "chuja/web/console.html"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

chuja-0.1.0/src/chuja/__init__.py

@@ -0,0 +1,33 @@
+"""chuja — separate a song into stems from a local file or (opt-in) a URL.
+
+    >>> import chuja
+    >>> result = chuja.separate("song.mp3", out_dir="stems", fmt="mp3")
+    >>> result.stems
+    {'drums': PosixPath('stems/song/drums.mp3'), ...}
+"""
+
+from .errors import (
+    ExportError,
+    FetchError,
+    MissingDependencyError,
+    SeparationError,
+    SourceError,
+    ChujaError,
+)
+from .pipeline import Result, separate
+from .separator import MODELS
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "separate",
+    "Result",
+    "MODELS",
+    "__version__",
+    "ChujaError",
+    "SourceError",
+    "FetchError",
+    "MissingDependencyError",
+    "SeparationError",
+    "ExportError",
+]