chuja 0.1.0__py3-none-any.whl

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",
+]

chuja/banner.py

@@ -0,0 +1,77 @@
+"""ASCII wordmark + a small startup animation for the CLI.
+
+All animation auto-disables when stdout is not a TTY (piped/redirected), so
+scripts and captured output stay clean."""
+
+from __future__ import annotations
+
+import sys
+import time
+
+from rich.console import Console
+from rich.text import Text
+
+# Block wordmark. Kept as plain rows so we can color/animate per line.
+_LOGO = [
+    " ██████ ██   ██ ██   ██     ███  █████ ",
+    "██      ██   ██ ██   ██      ██ ██   ██",
+    "██      ███████ ██   ██      ██ ███████",
+    "██      ██   ██ ██   ██ ██   ██ ██   ██",
+    " ██████ ██   ██  █████   █████  ██   ██",
+]
+
+# warm amber gradient top→bottom
+_SHADES = ["#ffb38f", "#ff8c5a", "#ff6b35", "#ef5a28", "#d44a1c"]
+
+
+def _is_tty() -> bool:
+    try:
+        return sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+def show(console: Console | None = None, *, animate: bool | None = None, tagline: str = "stem console") -> None:
+    """Render the wordmark. Animates a staggered reveal + a tiny VU flourish
+    when attached to a terminal."""
+    console = console or Console()
+    if animate is None:
+        animate = _is_tty()
+
+    console.print()
+    for i, row in enumerate(_LOGO):
+        line = Text("  " + row, style=f"bold {_SHADES[i]}")
+        console.print(line)
+        if animate:
+            time.sleep(0.05)
+
+    sub = Text("  ", style="")
+    sub.append("│ ", style="#474c54")
+    sub.append(tagline.upper(), style="bold #d7dbe0")
+    sub.append("  ·  ", style="#474c54")
+    sub.append("local neural stem separation", style="#767c85")
+    console.print(sub)
+
+    if animate:
+        _vu(console)
+    console.print()
+
+
+def _vu(console: Console, frames: int = 14) -> None:
+    """A brief equalizer flourish under the wordmark."""
+    import random  # local: only used in the animated TTY path
+
+    bars = 28
+    heights = [0] * bars
+    blocks = " ▁▂▃▄▅▆▇█"
+    for _ in range(frames):
+        line = Text("  ")
+        for b in range(bars):
+            target = random.randint(0, 8)
+            heights[b] = (heights[b] + target) // 2
+            shade = _SHADES[min(len(_SHADES) - 1, heights[b] // 2)]
+            line.append(blocks[heights[b]], style=shade)
+        console.print(line, end="\r")
+        time.sleep(0.045)
+    # clear the flourish line
+    console.print(Text(" " * (bars + 4)), end="\r")

chuja/cli.py

@@ -0,0 +1,286 @@
+"""Command-line interface for chuja."""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+import click
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from typer.core import TyperGroup
+
+from . import __version__, banner
+from .errors import ChujaError
+from .pipeline import separate as run_separate
+from .separator import DEFAULT_MODEL, MODELS
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+class DefaultGroup(TyperGroup):
+    """Let `chuja song.mp3` work as a shortcut for `chuja separate song.mp3`."""
+
+    def resolve_command(self, ctx, args):
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            if not args:
+                raise
+            return super().resolve_command(ctx, ["separate", *args])
+
+
+app = typer.Typer(
+    cls=DefaultGroup,
+    add_completion=False,
+    help="Separate a song into stems (vocals/drums/bass/other). "
+    "Run `chuja` with no arguments for interactive mode, or `chuja serve` for the visual console.",
+    rich_markup_mode="rich",
+)
+
+
+def _version_callback(value: bool):
+    if value:
+        console.print(f"chuja {__version__}")
+        raise typer.Exit()
+
+
+# ----------------------------------------------------------------------------
+# separate
+# ----------------------------------------------------------------------------
+@app.command()
+def separate(
+    source: str = typer.Argument(..., help="Audio file path, or a URL (needs the 'url' extra)."),
+    out: Path = typer.Option("stems", "--out", "-o", help="Directory to write the stem folder into."),
+    model: str = typer.Option(DEFAULT_MODEL, "--model", "-m", help="Separation model. See `chuja models`."),
+    fmt: str = typer.Option("wav", "--format", "-f", help="Output format: wav, mp3, or flac."),
+    two_stems: Optional[str] = typer.Option(None, "--two-stems", help="One stem + accompaniment, e.g. vocals."),
+    mp3_bitrate: int = typer.Option(320, "--mp3-bitrate", help="kbps for mp3 export."),
+    zip_output: bool = typer.Option(False, "--zip", help="Also bundle the stems into a portable .zip."),
+    device: Optional[str] = typer.Option(None, "--device", help="Force a torch device: cpu, cuda, or mps."),
+    open_folder: bool = typer.Option(False, "--open", "-O", help="Reveal the output folder in your file manager when done."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress the banner and progress chatter."),
+):
+    """Separate SOURCE into stems."""
+    if not quiet:
+        banner.show(console)
+
+    def on_event(message: str):
+        if not quiet:
+            console.print(f"  [dim]›[/] {message}")
+
+    try:
+        result = run_separate(
+            source, out_dir=out, model=model, two_stems=two_stems, fmt=fmt,
+            mp3_bitrate=mp3_bitrate, zip_output=zip_output, device=device, on_event=on_event,
+        )
+    except ChujaError as exc:
+        err_console.print(f"\n[bold red]✗ Error:[/] {exc}")
+        raise typer.Exit(code=1)
+    except KeyboardInterrupt:  # pragma: no cover
+        err_console.print("\n[yellow]Cancelled.[/]")
+        raise typer.Exit(code=130)
+
+    _print_result(result, fmt)
+    if open_folder:
+        _reveal(result.out_dir)
+
+
+def _reveal_command() -> str:
+    """The platform-native 'open this folder' command, for the copy-paste hint."""
+    if sys.platform == "darwin":
+        return "open"
+    if sys.platform.startswith("win"):
+        return "explorer"
+    return "xdg-open"
+
+
+def _reveal(path: Path) -> bool:
+    """Open a folder in the OS file manager. Best-effort; never raises."""
+    import subprocess
+
+    target = str(Path(path).resolve())
+    try:
+        if sys.platform.startswith("win"):
+            import os
+            os.startfile(target)  # type: ignore[attr-defined]
+        else:
+            subprocess.run([_reveal_command(), target], check=False,
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        return True
+    except Exception:
+        return False
+
+
+def _print_result(result, fmt):
+    out_dir = Path(result.out_dir).resolve()
+    body = Text()
+    body.append(f"{result.track}\n\n", style="bold #ff6b35")
+    # The folder, front and center — absolute so it's unambiguous and clickable.
+    body.append("folder  ", style="#767c85")
+    body.append(f"{out_dir}\n", style="bold #d7dbe0")
+    for name, path in result.stems.items():
+        body.append(f"        {name:<13}", style="#29d3c2")
+        body.append(f"{Path(path).name}\n", style="dim")
+    if result.archive:
+        body.append("        ", style="")
+        body.append(f"{'zip':<13}", style="#b56bff")
+        body.append(f"{Path(result.archive).name}\n", style="dim")
+    body.append("\nreveal  ", style="#767c85")
+    body.append(f'{_reveal_command()} "{out_dir}"', style="#29d3c2")
+    console.print()
+    console.print(Panel(body, title=f"[bold green]✓ {len(result.stems)} stems · {fmt}[/]",
+                        subtitle="[dim]rerun with --open to jump straight to the folder[/]",
+                        border_style="#34383e", expand=False))
+
+
+# ----------------------------------------------------------------------------
+# serve
+# ----------------------------------------------------------------------------
+@app.command()
+def serve(
+    out: Path = typer.Option(
+        Path(tempfile.gettempdir()) / "chuja-stems", "--out", "-o",
+        help="Where the console writes stems.",
+    ),
+    port: int = typer.Option(7777, "--port", "-p", help="Port to listen on."),
+    host: str = typer.Option("127.0.0.1", "--host", help="Interface to bind (localhost by default)."),
+    model: str = typer.Option(DEFAULT_MODEL, "--model", "-m", help="Default model for the console."),
+    no_open: bool = typer.Option(False, "--no-open", help="Don't auto-open the browser."),
+):
+    """Launch the visual mixing console in your browser."""
+    _serve(out=out, port=port, host=host, model=model, no_open=no_open)
+
+
+def _serve(
+    *,
+    out: Optional[Path] = None,
+    port: int = 7777,
+    host: str = "127.0.0.1",
+    model: str = DEFAULT_MODEL,
+    no_open: bool = False,
+):
+    """Plain implementation shared by the `serve` command and interactive mode.
+
+    Kept separate because Typer command functions can't be called directly —
+    their parameter defaults are OptionInfo descriptors, not values."""
+    from . import server  # local import: avoids loading the server unless used
+
+    if out is None:
+        out = Path(tempfile.gettempdir()) / "chuja-stems"
+
+    banner.show(console, tagline="visual console")
+    try:
+        httpd, url = server.serve(out_dir=out, host=host, port=port, model=model)
+    except OSError as exc:
+        err_console.print(f"[bold red]✗[/] Could not bind {host}:{port} — {exc}")
+        err_console.print("  Try another port:  [bold]chuja serve --port 7788[/]")
+        raise typer.Exit(code=1)
+
+    panel = Text()
+    panel.append("  console live at  ", style="#767c85")
+    panel.append(url, style="bold #ff6b35 underline")
+    panel.append("\n  output folder    ", style="#767c85")
+    panel.append(str(Path(out)), style="dim")
+    panel.append("\n\n  drop a file or paste a URL in the browser.", style="#d7dbe0")
+    panel.append("\n  press ", style="#767c85")
+    panel.append("Ctrl+C", style="bold #29d3c2")
+    panel.append(" here to stop.", style="#767c85")
+    console.print(Panel(panel, border_style="#34383e", title="[bold]▶ chuja serve[/]", expand=False))
+
+    if not no_open:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        console.print("\n[dim]console stopped.[/]")
+    finally:
+        httpd.server_close()
+
+
+# ----------------------------------------------------------------------------
+# models
+# ----------------------------------------------------------------------------
+@app.command()
+def models():
+    """List available separation models."""
+    table = Table(title="Demucs models", border_style="#34383e", title_style="bold #ff6b35")
+    table.add_column("Model", style="#29d3c2", no_wrap=True)
+    table.add_column("Description", style="#d7dbe0")
+    for name, desc in MODELS.items():
+        label = f"{name}  (default)" if name == DEFAULT_MODEL else name
+        table.add_row(label, desc)
+    console.print(table)
+
+
+# ----------------------------------------------------------------------------
+# interactive (bare `chuja`)
+# ----------------------------------------------------------------------------
+def interactive():
+    """A small guided flow when the user runs `chuja` with no arguments."""
+    from rich.prompt import Prompt
+
+    if not sys.stdin.isatty():
+        # Non-interactive context (piped/CI): show help instead of hanging.
+        command = typer.main.get_command(app)
+        with click.Context(command) as ctx:
+            console.print(ctx.get_help())
+        return
+
+    banner.show(console)
+    console.print("  [bold]What would you like to do?[/]\n")
+    console.print("   [#ff6b35]1[/]  Separate a local file")
+    console.print("   [#ff6b35]2[/]  Separate from a URL")
+    console.print("   [#ff6b35]3[/]  Launch the visual console  [dim](web UI)[/]")
+    console.print("   [#ff6b35]q[/]  Quit\n")
+    choice = Prompt.ask("  [bold]›[/]", choices=["1", "2", "3", "q"], default="3", show_choices=False)
+
+    if choice == "q":
+        return
+    if choice == "3":
+        return _serve()
+
+    source = Prompt.ask("  [#29d3c2]file path[/]" if choice == "1" else "  [#29d3c2]url[/]")
+    model = Prompt.ask("  model", choices=list(MODELS), default=DEFAULT_MODEL, show_choices=False)
+    fmt = Prompt.ask("  format", choices=["wav", "mp3", "flac"], default="mp3")
+    split = Prompt.ask("  split", choices=["full", "karaoke"], default="full")
+    two = "vocals" if split == "karaoke" else None
+    bundle = Prompt.ask("  zip the stems?", choices=["y", "n"], default="y") == "y"
+
+    def on_event(message: str):
+        console.print(f"  [dim]›[/] {message}")
+
+    try:
+        result = run_separate(source, out_dir="stems", model=model, two_stems=two,
+                              fmt=fmt, zip_output=bundle, on_event=on_event)
+    except ChujaError as exc:
+        err_console.print(f"\n[bold red]✗ Error:[/] {exc}")
+        raise typer.Exit(code=1)
+    _print_result(result, fmt)
+    if Prompt.ask("  reveal the folder?", choices=["y", "n"], default="y") == "y":
+        _reveal(result.out_dir)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", callback=_version_callback, is_eager=True, help="Show version and exit."),
+):
+    """chuja — stem separation for the command line."""
+    if ctx.invoked_subcommand is None:
+        interactive()
+        raise typer.Exit()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

chuja/errors.py

@@ -0,0 +1,26 @@
+"""Exception types raised across chuja. Kept dependency-free so callers can
+catch them without importing the heavy ML stack."""
+
+
+class ChujaError(Exception):
+    """Base class for all expected, user-facing failures."""
+
+
+class SourceError(ChujaError):
+    """The input could not be resolved to a usable audio file."""
+
+
+class FetchError(SourceError):
+    """A URL could not be downloaded (network, unsupported site, blocked, etc.)."""
+
+
+class MissingDependencyError(ChujaError):
+    """An optional dependency required for this operation is not installed."""
+
+
+class SeparationError(ChujaError):
+    """The separation engine (Demucs) failed to produce stems."""
+
+
+class ExportError(ChujaError):
+    """A separated stem could not be written to disk in the requested format."""

chuja/export.py

@@ -0,0 +1,112 @@
+"""Write separated stem tensors to disk and optionally bundle them.
+
+Export is intentionally backend-independent: WAV/FLAC go through soundfile
+(libsndfile) and MP3 through ffmpeg. We deliberately do NOT use torchaudio's
+save path, which depends on whichever audio backend (sox/soundfile/torchcodec)
+happens to be installed and fails confusingly across environments.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Dict
+
+from .errors import ExportError
+from .util import require_ffmpeg
+
+FORMATS = {"wav", "mp3", "flac"}
+
+
+def write_stems(
+    stems: Dict,
+    samplerate: int,
+    out_dir: Path,
+    *,
+    fmt: str = "wav",
+    mp3_bitrate: int = 320,
+) -> Dict[str, Path]:
+    """Write each stem tensor to ``out_dir/<name>.<fmt>``.
+
+    Returns a mapping of stem name -> written path."""
+    if fmt not in FORMATS:
+        raise ExportError(f"Unsupported format '{fmt}'. Choose from: {', '.join(sorted(FORMATS))}.")
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    written: Dict[str, Path] = {}
+    for name, tensor in stems.items():
+        dest = out_dir / f"{name}.{fmt}"
+        try:
+            _write_one(tensor, samplerate, dest, fmt=fmt, mp3_bitrate=mp3_bitrate)
+        except ExportError:
+            raise
+        except Exception as exc:
+            raise ExportError(f"Failed to write stem '{name}' to {dest}: {exc}") from exc
+        written[name] = dest
+    return written
+
+
+def _to_frames(tensor):
+    """Convert a Demucs stem tensor [channels, time] to a soundfile-shaped
+    float32 array [time, channels], rescaling if it would clip."""
+    import numpy as np
+
+    data = tensor.detach().to("cpu").numpy()  # [channels, time]
+    if data.ndim == 1:
+        data = data[None, :]
+    peak = float(np.abs(data).max()) if data.size else 0.0
+    if peak > 1.0:  # match Demucs' default 'rescale' clip behavior
+        data = data / peak
+    return np.ascontiguousarray(data.T, dtype="float32")  # [time, channels]
+
+
+def _write_one(tensor, samplerate: int, dest: Path, *, fmt: str, mp3_bitrate: int) -> None:
+    try:
+        import soundfile as sf
+    except ImportError as exc:  # pragma: no cover - import guard
+        raise ExportError(
+            "soundfile is required for audio export. Install chuja's deps: pip install chuja"
+        ) from exc
+
+    frames = _to_frames(tensor)
+
+    if fmt == "wav":
+        sf.write(str(dest), frames, samplerate, subtype="PCM_16")
+    elif fmt == "flac":
+        sf.write(str(dest), frames, samplerate, format="FLAC")
+    elif fmt == "mp3":
+        _write_mp3(frames, samplerate, dest, mp3_bitrate, sf)
+    else:  # pragma: no cover - guarded by caller
+        raise ExportError(f"Unsupported format '{fmt}'.")
+
+
+def _write_mp3(frames, samplerate: int, dest: Path, bitrate: int, sf) -> None:
+    """Encode to MP3 via ffmpeg (libsndfile can't write MP3)."""
+    ffmpeg = require_ffmpeg()
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
+        tmp_path = Path(tmp.name)
+    try:
+        sf.write(str(tmp_path), frames, samplerate, subtype="PCM_16")
+        proc = subprocess.run(
+            [ffmpeg, "-y", "-loglevel", "error", "-i", str(tmp_path),
+             "-b:a", f"{bitrate}k", str(dest)],
+            capture_output=True, text=True,
+        )
+        if proc.returncode != 0:
+            raise ExportError(f"ffmpeg failed to encode MP3: {proc.stderr.strip()}")
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def bundle(stem_paths: Dict[str, Path], archive_path: Path) -> Path:
+    """Zip the written stems into a single portable archive."""
+    archive_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for path in stem_paths.values():
+                zf.write(path, arcname=path.name)
+    except OSError as exc:
+        raise ExportError(f"Failed to build archive {archive_path}: {exc}") from exc
+    return archive_path

chuja/pipeline.py

@@ -0,0 +1,78 @@
+"""End-to-end orchestration: source -> stems -> files. The public entrypoint."""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Dict, Optional
+
+from . import export, separator, sources
+from .separator import DEFAULT_MODEL
+from .util import safe_name, unique_dir
+
+EventHook = Optional[Callable[[str], None]]
+
+
+@dataclass
+class Result:
+    track: str                          # cleaned track name
+    out_dir: Path                       # folder containing the stems
+    stems: Dict[str, Path] = field(default_factory=dict)
+    archive: Optional[Path] = None      # zip path, if bundling was requested
+
+    @property
+    def stem_names(self):
+        return list(self.stems)
+
+
+def separate(
+    source: str,
+    *,
+    out_dir: str | Path = "stems",
+    model: str = DEFAULT_MODEL,
+    two_stems: Optional[str] = None,
+    fmt: str = "wav",
+    mp3_bitrate: int = 320,
+    zip_output: bool = False,
+    device: Optional[str] = None,
+    on_event: EventHook = None,
+    on_progress: Optional[Callable[[float], None]] = None,
+) -> Result:
+    """Separate ``source`` (a local audio file or, with the ``url`` extra, a URL)
+    into stems written under ``out_dir/<track name>/``.
+
+    This is the single function the CLI and library users call.
+    """
+    out_root = Path(out_dir).expanduser()
+
+    # One temp dir for any URL download; cleaned up on exit no matter what.
+    with tempfile.TemporaryDirectory(prefix="chuja-") as tmp:
+        resolved = sources.resolve(source, workdir=Path(tmp), on_event=on_event)
+
+        samplerate, stems = separator.separate(
+            resolved.path,
+            model=model,
+            device=device,
+            two_stems=two_stems,
+            on_event=on_event,
+            on_progress=on_progress,
+        )
+
+        track_dir = unique_dir(out_root, safe_name(resolved.title))
+        if on_event:
+            on_event(f"Writing {len(stems)} stems to {track_dir}")
+
+        written = export.write_stems(
+            stems, samplerate, track_dir, fmt=fmt, mp3_bitrate=mp3_bitrate
+        )
+
+        archive = None
+        if zip_output:
+            # NB: not track_dir.with_suffix(".zip") — a track title like
+            # "feat. K.Flay" would have ".Flay" mistaken for an extension.
+            archive = export.bundle(written, track_dir.parent / f"{track_dir.name}.zip")
+            if on_event:
+                on_event(f"Bundled archive at {archive}")
+
+    return Result(track=resolved.title, out_dir=track_dir, stems=written, archive=archive)