soloslot 0.1.0__py3-none-any.whl

soloslot/__init__.py

@@ -0,0 +1,10 @@
+"""Mute instruments in a solo section of a song or its stems to build play-along tracks."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("soloslot")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree without install
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

soloslot/__main__.py

@@ -0,0 +1,4 @@
+from soloslot.cli import main
+
+if __name__ == "__main__":
+    main()

soloslot/audio.py

@@ -0,0 +1,69 @@
+"""Pure audio and stem-name helpers (no file access)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+from soloslot.config import Solo
+
+Audio = NDArray[np.floating]
+
+# Moises names stems "<Title>-<Stem>-<Key>-<tempo>bpm-<hz>hz.wav"
+_MOISES_RE = re.compile(r"-(?P<label>[^-]+)-[^-]+-\d+\s*bpm-\d+\s*hz$", re.IGNORECASE)
+
+
+def stem_label(path: Path) -> str:
+    """Lower-case stem name (e.g. 'winds') taken from a file name."""
+    m = _MOISES_RE.search(path.stem)
+    return (m.group("label") if m else path.stem).strip().lower()
+
+
+def matches(label: str, names: tuple[str, ...] | list[str]) -> bool:
+    """True if any name is a substring of the label (case-insensitive)."""
+    return any(n.lower() in label for n in names)
+
+
+def apply_gaps(audio: Audio, sr: int, solos: tuple[Solo, ...], fade_ms: float) -> Audio:
+    """Silence the solo regions, with short fades at the edges to avoid clicks.
+
+    `audio` has shape (frames, channels).
+    """
+    out = audio.copy()
+    n = len(out)
+    fade = max(1, int(sr * fade_ms / 1000))
+    for solo in solos:
+        a = min(max(round(solo.start * sr), 0), n)
+        b = min(max(round(solo.end * sr), 0), n)
+        if b <= a:
+            continue
+        out[a:b] = 0
+        fa = min(fade, a)  # fade-out ends at the gap
+        if fa:
+            out[a - fa : a] *= np.linspace(1.0, 0.0, fa, endpoint=False)[:, None]
+        fb = min(fade, n - b)  # fade-in starts after the gap
+        if fb:
+            out[b : b + fb] *= np.linspace(0.0, 1.0, fb, endpoint=False)[:, None]
+    return out
+
+
+def mix_stems(stems: list[Audio]) -> tuple[Audio, float]:
+    """Sum stems of possibly different length/channel count.
+
+    Returns the mix and the gain in dB applied to avoid clipping (0.0 if none).
+    """
+    length = max(len(s) for s in stems)
+    channels = max(s.shape[1] for s in stems)
+    mix = np.zeros((length, channels), dtype=np.float64)
+    for s in stems:
+        if s.shape[1] == 1 and channels > 1:
+            s = np.repeat(s, channels, axis=1)
+        mix[: len(s), : s.shape[1]] += s
+    peak = float(np.max(np.abs(mix))) if mix.size else 0.0
+    if peak > 0.99:
+        gain = 0.99 / peak
+        return (mix * gain).astype(np.float32), float(20 * np.log10(gain))
+    return mix.astype(np.float32), 0.0

soloslot/cli.py

@@ -0,0 +1,150 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from soloslot import __version__
+from soloslot.config import OUTPUT_FORMATS, ConfigError, load_config, song_from_audio
+from soloslot.process import process_song
+from soloslot.separate import DEFAULT_MODEL
+
+DEFAULT_CONFIG = "solo.toml"
+
+
+def _split(values: tuple[str, ...]) -> tuple[str, ...]:
+    """'piano,bass' 'drums' -> ('piano', 'bass', 'drums')"""
+    return tuple(v.strip() for value in values for v in value.split(",") if v.strip())
+
+
+def _solo(value: str) -> dict[str, str]:
+    start, sep, end = value.partition("-")
+    if not sep or not start.strip() or not end.strip():
+        raise click.BadParameter(f"expected START-END, e.g. 2:15-3:40, not {value!r}")
+    return {"start": start.strip(), "end": end.strip()}
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("inputs", nargs=-1, type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--song", "only", metavar="NAME", help="Process only this song (name from the config)."
+)
+@click.option(
+    "--solo",
+    "solos",
+    multiple=True,
+    metavar="START-END",
+    help="Solo region of an audio file, e.g. 2:15-3:40 or 135-220. Repeat for several.",
+)
+@click.option(
+    "--hear",
+    multiple=True,
+    metavar="STEMS",
+    help="Stems that stay audible in the solo, e.g. piano,bass,drums. All others are muted.",
+)
+@click.option(
+    "--mute",
+    multiple=True,
+    metavar="STEMS",
+    help="Stems that are muted in the solo, e.g. guitar. All others stay audible.",
+)
+@click.option(
+    "--model",
+    default=None,
+    metavar="NAME",
+    help=f"Demucs model used to split audio files (default: {DEFAULT_MODEL}).",
+)
+@click.option(
+    "--format", "fmt", type=click.Choice(OUTPUT_FORMATS), default=None, help="Output format."
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Output folder for an audio file (default: out/<song>/ next to it).",
+)
+@click.option(
+    "--backing-only",
+    is_flag=True,
+    help="Write only the backing track, not the individual stems.",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would happen, write nothing.")
+@click.version_option(__version__, prog_name="soloslot")
+def main(
+    inputs: tuple[Path, ...],
+    only: str | None,
+    solos: tuple[str, ...],
+    hear: tuple[str, ...],
+    mute: tuple[str, ...],
+    model: str | None,
+    fmt: str | None,
+    output: Path | None,
+    backing_only: bool,
+    dry_run: bool,
+) -> None:
+    """Mute instruments in a solo section and build a play-along backing track.
+
+    INPUTS are songs (MP3, WAV, FLAC, ...) or TOML configs.
+
+    \b
+    A song is split into stems with Demucs (needs the 'separate' extra):
+      soloslot song.mp3 --solo 2:15-3:40 --hear piano,bass,drums
+      soloslot song.flac --solo 1:05-2:40 --mute guitar
+
+    A config describes stems you already have, or songs to split (`input = "song.mp3"`).
+    A file holds either one song or several [[song]] tables. Without arguments,
+    ./solo.toml is used, so you can run the tool inside a stems folder. See
+    songs.example.toml and solo.example.toml.
+    """
+    configs = [p for p in inputs if p.suffix.lower() == ".toml"]
+    audio = [p for p in inputs if p.suffix.lower() != ".toml"]
+    song_options = solos or hear or mute or model or fmt or output or backing_only
+    if song_options and not audio:
+        raise click.UsageError(
+            "--solo, --hear, --mute, --model, --format, --output and --backing-only apply to "
+            "audio files; put these settings in the config instead"
+        )
+    if not inputs:
+        default = Path(DEFAULT_CONFIG)
+        if not default.is_file():
+            raise click.ClickException(
+                f"no input given and no ./{DEFAULT_CONFIG} in {Path.cwd()}. "
+                "Pass a song or a config file (see solo.example.toml)."
+            )
+        configs = [default]
+    if audio and not solos:
+        raise click.UsageError("give the solo region of the song with --solo START-END")
+    if hear and mute:
+        raise click.UsageError("use either --hear or --mute, not both")
+    if output and len(audio) > 1:
+        raise click.UsageError("--output works with one audio file at a time")
+
+    songs = []
+    try:
+        for config in configs:
+            songs.extend(load_config(config))
+        regions = [_solo(s) for s in solos]
+        options = {k: v for k, v in (("model", model), ("format", fmt)) if v}
+        if backing_only:
+            options["stems"] = False
+        songs.extend(
+            song_from_audio(
+                path, regions, hear=_split(hear), mute=_split(mute), output=output, **options
+            )
+            for path in audio
+        )
+    except ConfigError as e:
+        raise click.ClickException(str(e)) from e
+    if only:
+        songs = [s for s in songs if s.name == only]
+        if not songs:
+            raise click.ClickException(f"song '{only}' not found")
+
+    ok = [process_song(s, dry_run=dry_run, log=click.echo) for s in songs]
+    failed = len(ok) - sum(ok)
+    click.echo(f"\nDone: {sum(ok)} song(s) ok, {failed} failed.")
+    if failed:
+        raise SystemExit(1)

soloslot/config.py

@@ -0,0 +1,208 @@
+"""Reading and validating the songs config (TOML)."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from soloslot.separate import DEFAULT_MODEL
+
+OUTPUT_FORMATS = ("wav", "flac")
+
+
+class ConfigError(ValueError):
+    """The config file or one of its songs is invalid."""
+
+
+@dataclass(frozen=True)
+class Solo:
+    """A solo region in seconds."""
+
+    start: float
+    end: float
+
+
+@dataclass(frozen=True)
+class Song:
+    name: str
+    folder: Path
+    output: Path
+    solos: tuple[Solo, ...]
+    hear: tuple[str, ...] = ()
+    mute: tuple[str, ...] = ()
+    skip: tuple[str, ...] = ()
+    fade_ms: float = 30.0
+    mixdown: bool = True
+    write_stems: bool = True  # False: only the backing track is written
+    format: str = "wav"
+    # A full song to split into stems first; `folder` then holds the separated stems.
+    input: Path | None = None
+    model: str = DEFAULT_MODEL
+    notes: list[str] = field(default_factory=list, compare=False)
+
+
+def parse_time(value: Any) -> float:
+    """Seconds from a number, '135.5', '2:15' or '1:02:15.5'."""
+    if isinstance(value, bool):
+        raise ConfigError(f"invalid time: {value!r}")
+    if isinstance(value, int | float):
+        return float(value)
+    seconds = 0.0
+    try:
+        for part in str(value).strip().split(":"):
+            seconds = seconds * 60 + float(part)
+    except ValueError:
+        raise ConfigError(f"invalid time: {value!r}") from None
+    return seconds
+
+
+def _solos(raw: dict[str, Any], name: str) -> tuple[Solo, ...]:
+    entries = raw.get("solos") or []
+    if not entries:
+        raise ConfigError(f"{name}: 'solos' is missing or empty")
+    sec_per_bar = None
+    solos: list[Solo] = []
+    for entry in entries:
+        if "start" in entry or "end" in entry:
+            if "start" not in entry or "end" not in entry:
+                raise ConfigError(f"{name}: 'start' and 'end' belong together")
+            start, end = parse_time(entry["start"]), parse_time(entry["end"])
+        elif "start_bar" in entry or "end_bar" in entry:
+            if "start_bar" not in entry or "end_bar" not in entry:
+                raise ConfigError(f"{name}: 'start_bar' and 'end_bar' belong together")
+            if "bpm" not in raw:
+                raise ConfigError(f"{name}: bars need 'bpm' on the song")
+            if sec_per_bar is None:
+                beats = float(raw.get("beats_per_bar", 4))
+                sec_per_bar = beats * 60.0 / float(raw["bpm"])
+            offset = parse_time(raw.get("offset", 0))
+            start = offset + (float(entry["start_bar"]) - 1) * sec_per_bar
+            end = offset + (float(entry["end_bar"]) - 1) * sec_per_bar
+        else:
+            raise ConfigError(f"{name}: a solo needs start/end or start_bar/end_bar")
+        if end <= start:
+            raise ConfigError(f"{name}: solo end {end:.2f}s is not after start {start:.2f}s")
+        solos.append(Solo(start, end))
+    return tuple(solos)
+
+
+def _names(merged: dict[str, Any], key: str, name: str) -> tuple[str, ...]:
+    value = merged.get(key, ())
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, list | tuple) or not all(isinstance(v, str) for v in value):
+        raise ConfigError(f"{name}: '{key}' must be a list of stem names")
+    return tuple(value)
+
+
+def _song(raw: dict[str, Any], defaults: dict[str, Any], base: Path, *, single: bool) -> Song:
+    merged = {**defaults, **raw}
+    if "input" in raw and "folder" in raw:
+        raise ConfigError(
+            f"{raw.get('name', raw['input'])}: use either 'input' (a song) or 'folder' (stems)"
+        )
+    source = base / str(raw["input"]) if "input" in raw else None
+    if single:
+        # One song per config file: the stems live next to the config by default.
+        folder = base / str(raw.get("folder", "."))
+        default_name = source.stem if source else folder.resolve().name
+        name = str(raw.get("name", default_name))
+        output = base / str(merged.get("output", "out"))
+    else:
+        if "name" not in raw and source is None:
+            raise ConfigError("every [[song]] needs 'name' and 'folder' (or 'input')")
+        if "folder" not in raw and source is None:
+            raise ConfigError(f"{raw['name']}: [[song]] needs 'folder' or 'input'")
+        name = str(raw.get("name", source.stem if source else ""))
+        folder = base / str(raw.get("folder", "."))
+        output = base / str(merged.get("output", "out")) / name
+    fmt = str(merged.get("format", "wav")).lower().lstrip(".")
+    if fmt not in OUTPUT_FORMATS:
+        raise ConfigError(f"{name}: format must be one of {', '.join(OUTPUT_FORMATS)}, not {fmt!r}")
+    hear, mute = _names(merged, "hear", name), _names(merged, "mute", name)
+    if "hear" in raw and "mute" in raw:
+        raise ConfigError(f"{name}: use either 'hear' (keep) or 'mute' (remove), not both")
+    # A song-level choice replaces the other one from [defaults].
+    if "hear" in raw:
+        mute = ()
+    elif "mute" in raw:
+        hear = ()
+    elif hear and mute:
+        raise ConfigError(f"{name}: [defaults] has both 'hear' and 'mute'")
+    mixdown, write_stems = bool(merged.get("mixdown", True)), bool(merged.get("stems", True))
+    if not mixdown and not write_stems:
+        raise ConfigError(f"{name}: 'mixdown' and 'stems' are both off, nothing would be written")
+    model = str(merged.get("model", DEFAULT_MODEL))
+    if source is not None:
+        # Separated stems are cached in the output folder and reused on the next run.
+        folder = output / "separated" / model
+    return Song(
+        name=name,
+        folder=folder,
+        output=output,
+        solos=_solos(raw, name),
+        hear=hear,
+        mute=mute,
+        skip=_names(merged, "skip", name),
+        fade_ms=float(merged.get("fade_ms", 30)),
+        mixdown=mixdown,
+        write_stems=write_stems,
+        format=fmt,
+        input=source,
+        model=model,
+    )
+
+
+def song_from_audio(
+    path: Path,
+    solos: list[dict[str, Any]],
+    *,
+    hear: tuple[str, ...] = (),
+    mute: tuple[str, ...] = (),
+    output: Path | None = None,
+    **options: Any,
+) -> Song:
+    """A song to separate, given on the command line instead of in a config file.
+
+    The output defaults to `out/<song>/` next to the audio file.
+    """
+    path = path.resolve()
+    raw: dict[str, Any] = {"input": path.name, "solos": solos, **options}
+    if hear:
+        raw["hear"] = list(hear)
+    if mute:
+        raw["mute"] = list(mute)
+    raw["output"] = str(output.resolve() if output else path.parent / "out" / path.stem)
+    return _song(raw, {}, path.parent, single=True)
+
+
+def load_config(path: Path) -> list[Song]:
+    """Load the songs of a config file. Relative paths resolve against the config's directory.
+
+    Two layouts are accepted:
+    - several songs: `[[song]]` tables, each with `name` and `folder`;
+    - one song: `solos` (and optional `hear`, `bpm`, ...) at the top level. `folder` defaults
+      to the config's directory, `name` to that directory's name, and output goes to `out/`.
+
+    Instead of `folder`, a song can name a full recording as `input`; it is split into stems
+    first (see `separate.py`).
+    """
+    try:
+        with path.open("rb") as fh:
+            cfg = tomllib.load(fh)
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{path}: {e}") from e
+    base = path.resolve().parent
+    defaults = cfg.get("defaults", {})
+    raw_songs = cfg.get("song", [])
+
+    if raw_songs and "solos" in cfg:
+        raise ConfigError(f"{path}: use either [[song]] tables or a top-level 'solos', not both")
+    if raw_songs:
+        return [_song(raw, defaults, base, single=False) for raw in raw_songs]
+    if "solos" in cfg:
+        top = {k: v for k, v in cfg.items() if k != "defaults"}
+        return [_song(top, defaults, base, single=True)]
+    raise ConfigError(f"{path}: no [[song]] entries and no top-level 'solos'")

soloslot/process.py

@@ -0,0 +1,140 @@
+"""Process one song: read stems, clear the solo, write stems and backing track."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+import soundfile as sf
+
+from soloslot.audio import apply_gaps, matches, mix_stems, stem_label
+from soloslot.config import Song
+from soloslot.separate import MODEL_STEMS, SeparationError, is_cached, separate
+
+AUDIO_EXTENSIONS = (".wav", ".flac", ".mp3")  # in order of preference
+_LOSSLESS_SUBTYPES = {"PCM_16", "PCM_24", "PCM_32", "FLOAT", "DOUBLE"}
+
+
+def find_audio_files(folder: Path) -> list[Path]:
+    """Audio files in `folder`, one per base name (WAV preferred over FLAC over MP3)."""
+    chosen: dict[str, Path] = {}
+    for ext in reversed(AUDIO_EXTENSIONS):
+        for f in folder.iterdir():
+            if f.is_file() and f.suffix.lower() == ext:
+                chosen[f.stem] = f
+    return sorted(chosen.values())
+
+
+def output_subtype(input_subtype: str, fmt: str = "wav") -> str:
+    """Keep the input's bit depth; lossy or unsupported inputs become 24 bit PCM.
+
+    FLAC cannot store float or 32 bit PCM, so those become 24 bit there.
+    """
+    allowed = _LOSSLESS_SUBTYPES if fmt == "wav" else {"PCM_16", "PCM_24"}
+    return input_subtype if input_subtype in allowed else "PCM_24"
+
+
+def _check_names(song: Song, labels: list[str], log: Callable[[str], None]) -> None:
+    # A typo in 'hear' would silently mute a stem (and one in 'mute' keep it), so report it.
+    key, names = ("mute", song.mute) if song.mute else ("hear", song.hear)
+    for n in names:
+        if not any(n.lower() in label for label in labels):
+            log(f"  WARNING: '{key}' entry '{n}' matches no stem of this song")
+
+
+def _silenced(song: Song, label: str) -> bool:
+    return matches(label, song.mute) if song.mute else not matches(label, song.hear)
+
+
+def _separate(song: Song, *, dry_run: bool, log: Callable[[str], None]) -> bool | None:
+    """Split `song.input` into `song.folder`. Returns True/False to stop early, None to go on."""
+    assert song.input is not None
+    if not song.input.is_file():
+        log(f"  ERROR: input file not found: {song.input}")
+        return False
+    if dry_run and not is_cached(song.input, song.folder, song.model):
+        # Nothing to read yet: show what the separation would produce.
+        labels = list(MODEL_STEMS.get(song.model, ()))
+        log(f"  would separate {song.input.name} with Demucs '{song.model}' into {song.folder}")
+        for s in song.solos:
+            log(f"  Solo: {s.start:7.2f}s - {s.end:7.2f}s  ({s.end - s.start:.1f}s)")
+        if labels:
+            _check_names(song, labels, log)
+            for label in labels:
+                log(f"  {'silent in solo' if _silenced(song, label) else 'stays audible'}: {label}")
+        return True
+    try:
+        separate(song.input, song.folder, song.model, log=log)
+    except SeparationError as e:
+        log(f"  ERROR: {e}")
+        return False
+    return None
+
+
+def process_song(song: Song, *, dry_run: bool = False, log: Callable[[str], None] = print) -> bool:
+    """Process one song. Returns False (after logging why) if it could not be done."""
+    log(f"\n=== {song.name} ===")
+    if song.input is not None:
+        done = _separate(song, dry_run=dry_run, log=log)
+        if done is not None:
+            return done
+    if not song.folder.is_dir():
+        log(f"  ERROR: folder not found: {song.folder}")
+        return False
+    if song.output.resolve() == song.folder.resolve():
+        # Would overwrite the original stems and feed the results back in on the next run.
+        log("  ERROR: output folder is the stems folder; choose a different 'output'")
+        return False
+    for solo in song.solos:
+        log(f"  Solo: {solo.start:7.2f}s - {solo.end:7.2f}s  ({solo.end - solo.start:.1f}s)")
+
+    stems = []
+    for f in find_audio_files(song.folder):
+        label = stem_label(f)
+        if song.skip and matches(label, song.skip):
+            log(f"  skipped: {f.name}")
+            continue
+        stems.append((f, label))
+    if not stems:
+        log(f"  ERROR: no audio files found ({', '.join(AUDIO_EXTENSIONS)})")
+        return False
+
+    _check_names(song, [label for _, label in stems], log)
+
+    out_dir = song.output
+    sample_rate = None
+    results = []
+    for f, label in stems:
+        info = sf.info(f)
+        audio, sr = sf.read(f, dtype="float32", always_2d=True)
+        if sample_rate is None:
+            sample_rate = sr
+        elif sr != sample_rate:
+            log(f"  ERROR: {f.name} has {sr} Hz, expected {sample_rate} Hz")
+            return False
+        audible = not _silenced(song, label)
+        result = audio if audible else apply_gaps(audio, sr, song.solos, song.fade_ms)
+        log(f"  {'stays audible' if audible else 'silent in solo'}: {label}")
+        results.append(result)
+        if song.write_stems and not dry_run:
+            out_dir.mkdir(parents=True, exist_ok=True)
+            sf.write(
+                out_dir / f"{f.stem}.{song.format}",
+                result,
+                sr,
+                subtype=output_subtype(info.subtype, song.format),
+            )
+
+    if song.mixdown and sample_rate is not None:
+        mix, gain_db = mix_stems(results)
+        if gain_db:
+            log(f"  Mix would clip, lowered by {-gain_db:.1f} dB")
+        if not dry_run:
+            out_dir.mkdir(parents=True, exist_ok=True)
+            path = out_dir / f"{song.name} - Backing Track.{song.format}"
+            sf.write(path, mix, sample_rate, subtype="PCM_24")
+            log(f"  written: {path}")
+
+    if not dry_run:
+        log(f"  output: {out_dir.resolve()}")
+    return True

soloslot/separate.py

@@ -0,0 +1,118 @@
+"""Split a full song into stems with Demucs (optional `separate` extra).
+
+Demucs and PyTorch are imported only when a song actually needs separating, so the rest of
+the tool works without them.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+from numpy.typing import NDArray
+
+DEFAULT_MODEL = "htdemucs_6s"
+
+# Stems each known Demucs model produces. Used for --dry-run and for checking `hear`/`mute`
+# before the (slow) separation; other model names are passed to Demucs as they are.
+MODEL_STEMS: dict[str, tuple[str, ...]] = {
+    "htdemucs_6s": ("drums", "bass", "other", "vocals", "guitar", "piano"),
+    "htdemucs": ("drums", "bass", "other", "vocals"),
+    "htdemucs_ft": ("drums", "bass", "other", "vocals"),
+    "hdemucs_mmi": ("drums", "bass", "other", "vocals"),
+    "mdx": ("drums", "bass", "other", "vocals"),
+    "mdx_extra": ("drums", "bass", "other", "vocals"),
+    "mdx_q": ("drums", "bass", "other", "vocals"),
+    "mdx_extra_q": ("drums", "bass", "other", "vocals"),
+}
+
+INSTALL_HINT = (
+    "stem separation needs the 'separate' extra: "
+    "uv tool install 'soloslot[separate] @ git+https://github.com/swallat/soloslot.git'"
+)
+
+_MARKER = "source.json"
+_EXT = "flac"  # lossless and about half the size of WAV
+
+# (frames, channels) float32 audio per stem name, and the sample rate
+Stems = dict[str, NDArray[np.float32]]
+Separator = Callable[[Path], tuple[Stems, int]]
+
+
+class SeparationError(RuntimeError):
+    """Separation could not run (Demucs missing, model not available, unreadable input)."""
+
+
+def load_separator(model: str) -> Separator:
+    """Load a Demucs model and return a function that splits one file into stems."""
+    try:
+        from demucs.api import Separator as DemucsSeparator
+    except ImportError as e:
+        raise SeparationError(INSTALL_HINT) from e
+    try:
+        demucs = DemucsSeparator(model=model, progress=True)
+    except Exception as e:  # unknown model name, download failed, ...
+        raise SeparationError(f"could not load Demucs model '{model}': {e}") from e
+
+    def separate(path: Path) -> tuple[Stems, int]:
+        try:
+            _, stems = demucs.separate_audio_file(path)
+        except Exception as e:
+            raise SeparationError(f"could not separate {path.name}: {e}") from e
+        return {name: t.T.cpu().numpy().astype(np.float32) for name, t in stems.items()}, int(
+            demucs.samplerate
+        )
+
+    return separate
+
+
+def _fingerprint(path: Path, model: str) -> dict[str, object]:
+    st = path.stat()
+    return {"input": path.name, "size": st.st_size, "mtime_ns": st.st_mtime_ns, "model": model}
+
+
+def is_cached(input_path: Path, folder: Path, model: str) -> bool:
+    """True if `folder` holds a finished separation of exactly this input file and model."""
+    marker = folder / _MARKER
+    try:
+        return json.loads(marker.read_text(encoding="utf-8")) == _fingerprint(input_path, model)
+    except (OSError, ValueError):
+        return False
+
+
+def separate(
+    input_path: Path,
+    folder: Path,
+    model: str = DEFAULT_MODEL,
+    *,
+    log: Callable[[str], None] = print,
+    load: Callable[[str], Separator] | None = None,
+) -> None:
+    """Split `input_path` into `<folder>/<stem>.flac`, unless that was already done.
+
+    The result is reused as long as the input file and model stay the same, so trying
+    another solo region does not separate the song again.
+    """
+    if is_cached(input_path, folder, model):
+        log(f"  using separated stems from {folder}")
+        return
+    log(f"  separating {input_path.name} with Demucs '{model}' (this takes a while) ...")
+    stems, sr = (load or load_separator)(model)(input_path)
+
+    # Separated stems can peak slightly above full scale. Lower them all by the same amount
+    # so they still add up to the original instead of clipping in the PCM file.
+    peak = max((float(np.max(np.abs(a))) for a in stems.values() if a.size), default=0.0)
+    gain = 0.99 / peak if peak > 0.99 else 1.0
+    if gain < 1.0:
+        log(f"  separated stems lowered by {-20 * np.log10(gain):.1f} dB to avoid clipping")
+
+    folder.mkdir(parents=True, exist_ok=True)
+    (folder / _MARKER).unlink(missing_ok=True)
+    for old in folder.glob(f"*.{_EXT}"):
+        old.unlink()
+    for name, audio in stems.items():
+        sf.write(folder / f"{name}.{_EXT}", audio * gain, sr, subtype="PCM_24")
+    (folder / _MARKER).write_text(json.dumps(_fingerprint(input_path, model)), encoding="utf-8")

soloslot-0.1.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.5
+Name: soloslot
+Version: 0.1.0
+Summary: Mute instruments in the solo of a song to build play-along backing tracks
+Project-URL: Homepage, https://github.com/swallat/soloslot
+Project-URL: Source, https://github.com/swallat/soloslot
+Project-URL: Issues, https://github.com/swallat/soloslot/issues
+Author: Sebastian Wallat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,backing-track,demucs,play-along,practice,stem-separation,stems
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: soundfile>=0.12
+Provides-Extra: separate
+Requires-Dist: demucs>=4.1; extra == 'separate'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/logo.svg" alt="soloslot logo" width="420">
+</p>
+
+<h1 align="center">soloslot</h1>
+
+<p align="center"><strong>Make room for your solo.</strong><br>
+Turn any song into a play-along backing track in one command.</p>
+
+<p align="center">
+  <a href="https://github.com/swallat/soloslot/actions/workflows/ci.yml"><img src="https://github.com/swallat/soloslot/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+You know the song. You want to play the guitar part, the piano solo, the sax line. But the
+record has the original player on it, right where you want to jump in.
+
+soloslot takes the song, finds the instruments you name, and takes them **out of the solo
+section only**. The band keeps playing, the song stays whole before and after, and the gap is
+yours.
+
+```bash
+soloslot "Blue Bossa.mp3" --solo 1:05-2:40 --mute guitar
+```
+
+That is the whole workflow: one song in, one backing track out.
+
+## Why soloslot
+
+- **Practice with the real recording.** No more generic backing tracks or MIDI band-in-a-box.
+  You play with the actual band, the actual groove, the actual song.
+- **Only the solo is muted.** Intro, theme and outro stay intact, so you play the song the way
+  it goes, from the top, and step into the gap at the right moment.
+- **Start from a plain MP3.** Drop in an MP3, WAV or FLAC. soloslot splits it into stems with
+  [Demucs](https://github.com/adefossez/demucs), a state-of-the-art open-source separator. No
+  stems? No problem.
+- **Or bring your own stems.** Already have stems from Moises, Demucs or your DAW? soloslot works
+  on those directly and needs no separation, no PyTorch and no GPU.
+- **Say what goes, or what stays.** `--mute guitar` removes one instrument. `--hear
+  piano,bass,drums` keeps only the rhythm section. Pick whichever is shorter to type.
+- **Several solos, one run.** Repeat `--solo` for every section you want to play over.
+- **Click-free edits.** Short fades at the edges of each gap, so there are no pops or abrupt
+  cuts where the instrument leaves and returns.
+- **Fast to try again.** The separation is cached. Change the solo region, mute another
+  instrument, re-run: the song is not split twice.
+- **Safe for your files.** Your originals are never modified. Everything goes to a separate
+  output folder, and soloslot refuses to write over your input.
+- **Private and offline.** Everything runs on your computer. Your recordings are never uploaded.
+  Only the Demucs model is downloaded, once.
+- **Lossless output.** WAV or FLAC, with the bit depth of your source preserved (MP3 input is
+  written as 24 bit).
+- **Plain-text config for repeat use.** Describe a song, or a whole repertoire, in a small TOML
+  file. Give solos as timestamps or as bar numbers.
+
+## What you get
+
+For every song, an output folder with:
+
+| File | What it is |
+| --- | --- |
+| `<song> - Backing Track.wav` | The finished play-along track: the whole song with your chosen instruments missing in the solo. Load it into your player and go. |
+| `drums.wav`, `bass.wav`, `guitar.wav`, ... | The individual stems, each with the same mute applied. Handy for DAWs, for loops, or for mixing your own balance. Skip them with `--backing-only`. |
+| `separated/<model>/` | The untouched stems from separation, kept so the next run is instant. |
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/). It fetches a suitable Python (3.12 or newer) for you.
+
+```bash
+# with stem separation (pulls in PyTorch, a large download)
+uv tool install "soloslot[separate] @ git+https://github.com/swallat/soloslot.git"
+
+# without it, if you only work on stems you already have
+uv tool install git+https://github.com/swallat/soloslot.git
+
+soloslot --help
+```
+
+Update with `uv tool upgrade soloslot`.
+
+The first separation downloads the Demucs model (about 50 to 100 MB) and caches it. Separation
+runs on an NVIDIA GPU if PyTorch finds one, otherwise on the CPU, where a song takes a few
+minutes.
+
+## Quick start
+
+```bash
+# The guitar drops out between 1:05 and 2:40
+soloslot song.mp3 --solo 1:05-2:40 --mute guitar
+
+# Only piano, bass and drums stay in the solo
+soloslot song.flac --solo 2:15-3:40 --hear piano,bass,drums
+
+# Two solos, two instruments gone
+soloslot song.mp3 --solo 1:05-2:40 --solo 4:10-5:02 --mute guitar,piano
+
+# Look first, write nothing
+soloslot song.mp3 --solo 2:15-3:40 --mute guitar --dry-run
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--solo START-END` | A solo region. Repeat it for several. Times like `135.5`, `2:15`, `1:02:15.5`. |
+| `--mute STEMS` | Silence these stems in the solo; everything else stays. |
+| `--hear STEMS` | The opposite: only these stems stay in the solo. Use one of the two. |
+| `--model` | Demucs model. Default `htdemucs_6s` splits into **drums, bass, guitar, piano, vocals, other**. `htdemucs` and `htdemucs_ft` give drums, bass, vocals, other, and are a bit cleaner at that. |
+| `--backing-only` | Write only the backing track. |
+| `--format flac` | Write FLAC instead of WAV. |
+| `-o, --output DIR` | Output folder. Default: `out/<song>/` next to the song. |
+| `--dry-run` | Show what would happen and write nothing. |
+
+## Working with stems you already have
+
+Put each song's stems (WAV, FLAC or MP3) in their own folder and describe the solo in a
+`solo.toml` next to them (see `solo.example.toml`):
+
+```toml
+hear  = ["piano", "bass", "drums"]   # stems that stay audible in the solo
+skip  = ["visualizer"]               # ignore the full mix
+solos = [ { start = "2:15", end = "3:40" } ]
+```
+
+```bash
+cd stems/Interplay
+soloslot                  # uses ./solo.toml
+soloslot --dry-run        # show what would happen, write nothing
+```
+
+The song name defaults to the folder name and the result goes to `./out/`. You can also pass
+several configs at once, for example `soloslot stems/*/solo.toml`.
+
+### A whole repertoire in one file
+
+Copy `songs.example.toml` to `songs.toml` and list your songs as `[[song]]` tables:
+
+```toml
+[defaults]
+hear = ["piano", "bass", "drums"]   # shared by all songs
+
+[[song]]
+name   = "Interplay"
+folder = "stems/Interplay"
+bpm    = 113
+solos  = [ { start_bar = 36, end_bar = 97 } ]
+
+[[song]]
+name   = "Blue Bossa"
+input  = "Blue Bossa.mp3"            # a full song: split it first
+mute   = ["guitar"]
+solos  = [ { start = "1:05", end = "2:40" } ]
+```
+
+```bash
+soloslot songs.toml                    # all songs
+soloslot songs.toml --song Interplay   # one song
+```
+
+Output goes to `out/<song>/`, next to the config file. Defaults live in `[defaults]` and any
+song can override them.
+
+## Configuration reference
+
+- **`input`**: a full song to split into stems first, instead of `folder`. The song name
+  defaults to the file name.
+- **`model`**: Demucs model for `input`, default `htdemucs_6s`.
+- **`hear`**: stems that stay audible in the solo; every other stem is silenced there. Matching
+  is a case-insensitive substring of the stem name (`"piano"` matches `Grand Piano`). Stems a
+  song does not have are ignored. A `hear` entry that matches nothing is reported as a warning,
+  so a typo cannot silently mute the wrong thing.
+- **`mute`**: the opposite of `hear`. Use either one per song.
+- **`skip`**: files or stems to ignore, such as a full mix (`["visualizer"]`).
+- **`solos`**: one or more solo regions, see below.
+- **`format`**: `"wav"` (default) or `"flac"`. FLAC is lossless and smaller; float or 32 bit
+  input becomes 24 bit there.
+- **`stems`**: `stems = false` writes only the backing track.
+- **`fade_ms`**, **`mixdown`**, **`output`**: see `songs.example.toml`.
+- Relative paths are resolved against the directory of the config file.
+
+### Solo regions: timestamps or bars
+
+```toml
+# Timestamps: no tempo needed
+solos = [ { start = "2:15", end = "3:40" } ]
+
+# Several solos, mixing seconds and mm:ss
+solos = [ { start = 135.5, end = "3:40" }, { start = "4:10.5", end = "5:02" } ]
+
+# Bars: needs bpm on the song
+bpm   = 113
+solos = [ { start_bar = 36, end_bar = 97 } ]
+```
+
+- **Timestamps** are seconds from the start of the file: `135.5`, `"2:15"` or `"1:02:15.5"`.
+  Read them off your player or DAW.
+- **Bars** count from 1, bar 1 starts at the beginning of the file, and `end_bar` is the bar
+  where the solo is over again. Use `beats_per_bar` (default 4) for other meters and `offset`
+  if the file has a lead-in before bar 1.
+- Bars assume a constant tempo. For live recordings with a drifting tempo, use timestamps.
+
+Stem names are read from Moises file names (`<title>-<Stem>-<key>-<tempo>bpm-<hz>hz.wav`);
+other names are matched on the whole file name.
+
+## Your audio
+
+soloslot only processes files you provide, on your own computer. It includes no recordings and
+downloads none; only the Demucs model is fetched. Make sure you have the right to use your
+recordings. The output keeps the copyright status of the original. That is why `*.wav`,
+`*.mp3` and `*.flac` are git-ignored and the tests use synthetic audio only.
+
+## Develop
+
+[mise](https://mise.jdx.dev) provides `uv`; `uv` manages Python and packages.
+
+```bash
+mise install      # uv
+mise run install  # uv sync
+mise run check    # ruff + pytest
+mise tasks        # all tasks
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute, [CHANGELOG.md](CHANGELOG.md) for changes
+and [SECURITY.md](SECURITY.md) to report a vulnerability.
+
+## License
+
+[MIT](LICENSE) © 2026 Sebastian Wallat.
+
+soloslot installs these libraries, which keep their own licenses: click (BSD-3-Clause), NumPy
+(BSD-3-Clause and other permissive licenses) and python-soundfile (BSD-3-Clause), whose binary
+wheels include libsndfile (LGPL-2.1-or-later). The `separate` extra adds Demucs (MIT) and
+PyTorch (BSD-3-Clause).

soloslot-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+soloslot/__init__.py,sha256=Lr3YjsthOixHR7NbxDJyDeosrMlExGsYw0zmXEW9DOE,345
+soloslot/__main__.py,sha256=Egt1P0y1KycRehrUz3pBg4QpYJUXTflCVkdeUELA9CU,69
+soloslot/audio.py,sha256=tuvud7Qv-yqQfnsd8nBji7GoPLrC_dV0bUZ5U021olc,2347
+soloslot/cli.py,sha256=VaCI2nemHKwOIiSBwvOPr24WGAg-QzMZ_69n93dC-2I,5281
+soloslot/config.py,sha256=dHsdHhvt4jWNQIQFSOMOGGO8k2RiEoGRH1dj7KEoEyo,7998
+soloslot/process.py,sha256=xLHdG1l9LOumHClH0kzV2ywWsHeraRr8S8jaG3eU_-Q,5666
+soloslot/separate.py,sha256=svjV92J6VzyKan5NV9NIf0uZAdfiNcEyvu6s1U9-cRc,4549
+soloslot-0.1.0.dist-info/METADATA,sha256=nyobUnaYHqNXtsFiME8vmqY1I3jal7GAvj4o_BXVasc,10581
+soloslot-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+soloslot-0.1.0.dist-info/entry_points.txt,sha256=WBvT6yEo2xyjIT1mTqneh51sWzC8dCnwpKbLSkq4qfs,47
+soloslot-0.1.0.dist-info/licenses/LICENSE,sha256=sRhl1P6VL5jxrbHYAjBUnStsajxXaMiVzrHuTnzwtkM,1073
+soloslot-0.1.0.dist-info/RECORD,,

soloslot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

soloslot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+soloslot = soloslot.cli:main

soloslot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Wallat
+
+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.