multiafx 0.1.0__py3-none-any.whl

multiafx/__init__.py

@@ -0,0 +1,18 @@
+"""multiafx: multi-library audio effects with a unified chain-application API."""
+
+from multiafx._version import __version__
+from multiafx.apply import apply_chain
+from multiafx.chain import FXChain, generate_random_chain
+from multiafx.registry import registry
+from multiafx.types import EffectDef, MacroCategory, ParamRange
+
+__all__ = [
+    "__version__",
+    "FXChain",
+    "generate_random_chain",
+    "apply_chain",
+    "registry",
+    "EffectDef",
+    "MacroCategory",
+    "ParamRange",
+]

multiafx/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

multiafx/apply.py

@@ -0,0 +1,39 @@
+"""Apply a chain of effects to an audio array."""
+
+import numpy as np
+
+from multiafx.registry import registry, INTEGER_PARAMS
+
+
+def apply_chain(audio: np.ndarray, sr: int, chain: list[dict]) -> np.ndarray:
+    """Apply a sequence of effects to audio.
+
+    No error handling — the first failing effect raises. This is intentional:
+    if an effect fails we want the call site to know exactly which one.
+
+    Args:
+        audio: (channels, samples) float32 array.
+        sr: Sample rate.
+        chain: List of dicts, each with keys ``effect`` (str) and ``params`` (dict).
+
+    Returns:
+        Processed (channels, samples) float32 array, clipped to [-1, 1].
+    """
+    x = audio.astype(np.float32)
+
+    for step in chain:
+        name = step["effect"]
+        params = dict(step.get("params", {}))
+
+        # Coerce integer-only params
+        for p in INTEGER_PARAMS:
+            if p in params:
+                params[p] = int(round(params[p]))
+
+        effect_def = registry.get(name)
+        x = effect_def.callable(x, sr, **params)
+
+        if not np.all(np.isfinite(x)):
+            raise ValueError(f"Effect {name!r} produced NaN/Inf output")
+
+    return np.clip(x, -1.0, 1.0).astype(np.float32)

multiafx/chain.py

@@ -0,0 +1,336 @@
+"""FXChain: list-like container of effect dicts, pedalboard-style."""
+
+from __future__ import annotations
+
+import json
+import math
+import pickle
+import random
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterable
+
+import numpy as np
+import yaml
+
+from multiafx.apply import apply_chain
+from multiafx.registry import registry, INTEGER_PARAMS
+from multiafx.types import MacroCategory
+
+
+# Process-wide lock + seed/restore for the FX chain's critical section.
+# Several upstream effects (audiomentations.AddGaussianNoise,
+# SevenBandParametricEQ, internal PeakingFilter / HighShelfFilter, etc.)
+# consume the *global* ``np.random`` / ``random`` state inside their
+# transforms — they don't accept a per-call RNG. Without serialization,
+# two concurrent threads each calling ``np.random.seed(...)`` race on
+# that single shared state and corrupt each other's "deterministic"
+# output. The fix is to wrap the entire chain call in a lock so the
+# (seed → effect → restore) sequence is atomic across threads.
+#
+# FluidSynth rendering and other CPU-heavy work happen *outside* this
+# lock — only the FX chain itself is serialized.
+_RNG_LOCK = threading.Lock()
+
+
+@contextmanager
+def _seeded_globals(seed: int | None):
+    """Save the global RNG state, seed it from ``seed``, restore on exit.
+
+    When ``seed is None``, this is a no-op (no lock, no state change)
+    and the call behaves like vanilla audiomentations / sox.
+    """
+    if seed is None:
+        yield
+        return
+    with _RNG_LOCK:
+        np_state = np.random.get_state()
+        py_state = random.getstate()
+        np.random.seed(int(seed) & 0xFFFFFFFF)
+        random.seed(int(seed))
+        try:
+            yield
+        finally:
+            np.random.set_state(np_state)
+            random.setstate(py_state)
+
+
+class FXChain:
+    """An ordered list of audio effects applied in sequence.
+
+    Each step is a dict: ``{"effect": <name>, "params": {...}}``.
+
+    Construction::
+
+        chain = FXChain([
+            {"effect": "sox_highpass", "params": {"frequency": 80.0, "width_q": 0.7}},
+            {"effect": "sox_compand",  "params": {"attack_time": 0.005,
+                                                   "decay_time": 0.1,
+                                                   "soft_knee_db": 6.0}},
+        ])
+
+    Loading from files::
+
+        chain = FXChain.load("my_chain.yaml")   # auto-detect by extension
+        chain = FXChain.from_json("my_chain.json")
+
+    Application (pedalboard-style)::
+
+        out = chain(audio, 44100)          # __call__ shorthand
+        out = chain.process(audio, 44100)  # explicit
+    """
+
+    __slots__ = ("_steps",)
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+    def __init__(self, steps: list[dict] | None = None):
+        self._steps: list[dict] = []
+        if steps is not None:
+            for step in steps:
+                self._steps.append(self._validate_step(step))
+
+    @staticmethod
+    def _validate_step(step: dict) -> dict:
+        """Check a step has the right shape. Returns a shallow copy."""
+        if not isinstance(step, dict):
+            raise TypeError(f"Each step must be a dict, got {type(step).__name__}")
+        if "effect" not in step:
+            raise KeyError(f"Step missing 'effect' key: {step!r}")
+        name = step["effect"]
+        if name not in registry:
+            raise KeyError(f"Unknown effect: {name!r}")
+        params = step.get("params", {})
+        if not isinstance(params, dict):
+            raise TypeError(f"'params' must be a dict, got {type(params).__name__}")
+        return {"effect": name, "params": dict(params)}
+
+    # ------------------------------------------------------------------
+    # Loaders
+    # ------------------------------------------------------------------
+    @classmethod
+    def load(cls, source: str | Path | list | dict) -> "FXChain":
+        """Load from a path (json/yaml/pkl) or from a Python object (list/dict).
+
+        If given a ``list`` it's treated as the steps directly.
+        If given a ``dict`` it must have a ``chain`` or ``steps`` key.
+        Paths are dispatched by extension: .json, .yaml, .yml, .pkl, .pickle.
+        """
+        if isinstance(source, list):
+            return cls(source)
+        if isinstance(source, dict):
+            for key in ("chain", "steps"):
+                if key in source:
+                    return cls(source[key])
+            raise KeyError("dict source must contain 'chain' or 'steps' key")
+
+        path = Path(source)
+        suffix = path.suffix.lower()
+        if suffix == ".json":
+            return cls.from_json(path)
+        if suffix in (".yaml", ".yml"):
+            return cls.from_yaml(path)
+        if suffix in (".pkl", ".pickle"):
+            return cls.from_pickle(path)
+        raise ValueError(f"Unsupported file extension: {suffix!r}. "
+                         f"Use .json, .yaml, .yml, .pkl, or .pickle.")
+
+    @classmethod
+    def from_json(cls, path: str | Path) -> "FXChain":
+        with open(path, "r") as f:
+            data = json.load(f)
+        return cls(data if isinstance(data, list) else data["chain"])
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> "FXChain":
+        with open(path, "r") as f:
+            data = yaml.safe_load(f)
+        return cls(data if isinstance(data, list) else data["chain"])
+
+    @classmethod
+    def from_pickle(cls, path: str | Path) -> "FXChain":
+        with open(path, "rb") as f:
+            data = pickle.load(f)
+        if isinstance(data, cls):
+            return data
+        return cls(data if isinstance(data, list) else data["chain"])
+
+    # ------------------------------------------------------------------
+    # Savers
+    # ------------------------------------------------------------------
+    def to_list(self) -> list[dict]:
+        """Return a deep-copy list of steps, safe to serialize."""
+        return [{"effect": s["effect"], "params": dict(s["params"])} for s in self._steps]
+
+    def to_json(self, path: str | Path, *, indent: int = 2) -> None:
+        with open(path, "w") as f:
+            json.dump(self.to_list(), f, indent=indent)
+
+    def to_yaml(self, path: str | Path) -> None:
+        with open(path, "w") as f:
+            yaml.safe_dump(self.to_list(), f, sort_keys=False)
+
+    def to_pickle(self, path: str | Path) -> None:
+        with open(path, "wb") as f:
+            pickle.dump(self.to_list(), f)
+
+    # ------------------------------------------------------------------
+    # Rendering
+    # ------------------------------------------------------------------
+    def process(self, audio: np.ndarray, sr: int,
+                seed: int | None = None) -> np.ndarray:
+        """Apply every effect in sequence and return processed audio.
+
+        If ``seed`` is set, the global ``np.random`` / ``random`` state
+        is pinned to that value for the duration of the chain call and
+        restored on exit, under a process-wide lock — so concurrent
+        callers get bit-deterministic output regardless of thread
+        interleaving. When ``seed is None``, behaviour matches
+        vanilla audiomentations / sox (i.e., process-global RNG state
+        carries through; non-deterministic across threads).
+        """
+        with _seeded_globals(seed):
+            return apply_chain(audio, sr, self._steps)
+
+    def __call__(self, audio: np.ndarray, sr: int,
+                 seed: int | None = None) -> np.ndarray:
+        return self.process(audio, sr, seed=seed)
+
+    # ------------------------------------------------------------------
+    # List-like API
+    # ------------------------------------------------------------------
+    def __len__(self) -> int:
+        return len(self._steps)
+
+    def __iter__(self):
+        return iter(self._steps)
+
+    def __getitem__(self, idx):
+        if isinstance(idx, slice):
+            return FXChain(self._steps[idx])
+        return self._steps[idx]
+
+    def __setitem__(self, idx: int, step: dict) -> None:
+        self._steps[idx] = self._validate_step(step)
+
+    def __delitem__(self, idx) -> None:
+        del self._steps[idx]
+
+    def append(self, step: dict) -> None:
+        self._steps.append(self._validate_step(step))
+
+    def insert(self, idx: int, step: dict) -> None:
+        self._steps.insert(idx, self._validate_step(step))
+
+    def pop(self, idx: int = -1) -> dict:
+        return self._steps.pop(idx)
+
+    def clear(self) -> None:
+        self._steps.clear()
+
+    def extend(self, steps: Iterable[dict]) -> None:
+        for s in steps:
+            self.append(s)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+    def add(self, effect: str, **params) -> "FXChain":
+        """Append an effect by name with params as kwargs. Returns self for chaining."""
+        self.append({"effect": effect, "params": params})
+        return self
+
+    @property
+    def effects(self) -> list[str]:
+        """Ordered list of effect names."""
+        return [s["effect"] for s in self._steps]
+
+    def categories(self) -> list[MacroCategory]:
+        """Macro category of each step, in order."""
+        return [registry.get(s["effect"]).macro_category for s in self._steps]
+
+    # ------------------------------------------------------------------
+    # Equality & representation
+    # ------------------------------------------------------------------
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, FXChain):
+            return NotImplemented
+        return self._steps == other._steps
+
+    def __repr__(self) -> str:
+        return f"FXChain(num_effects={len(self._steps)})"
+
+    def __str__(self) -> str:
+        if not self._steps:
+            return "FXChain([])"
+        lines = ["FXChain(["]
+        for step in self._steps:
+            lines.append(f"  {step!r},")
+        lines.append("])")
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Chain generation
+# ---------------------------------------------------------------------------
+def generate_random_chain(
+    num_fx: int | tuple[int, int],
+    seed: int | None = None,
+    *,
+    exclude_effects: Iterable[str] = (),
+    exclude_categories: Iterable[str | MacroCategory] = (),
+    no_consecutive_same_category: bool = True,
+) -> FXChain:
+    """Generate a random FXChain.
+
+    Args:
+        num_fx: Number of effects, or (min, max) for a random count.
+        seed: RNG seed for reproducibility.
+        exclude_effects: Effect names to skip.
+        exclude_categories: Macro categories to skip entirely.
+        no_consecutive_same_category: If True, the same macro category can't
+            appear in two consecutive slots (e.g. avoids EQ→EQ).
+    """
+    rng = random.Random(seed)
+
+    excluded_cats = {MacroCategory(c) if isinstance(c, str) else c for c in exclude_categories}
+    excluded_names = set(exclude_effects)
+
+    available = [
+        eff for eff in registry
+        if eff.name not in excluded_names and eff.macro_category not in excluded_cats
+    ]
+    if not available:
+        raise ValueError("No effects remain after exclusions.")
+
+    if isinstance(num_fx, tuple):
+        n = rng.randint(int(num_fx[0]), int(num_fx[1]))
+    else:
+        n = int(num_fx)
+
+    chain = FXChain()
+    prev_cat: MacroCategory | None = None
+    for _ in range(n):
+        pool = available
+        if no_consecutive_same_category and prev_cat is not None:
+            pool = [e for e in available if e.macro_category != prev_cat]
+            if not pool:
+                pool = available
+
+        eff = rng.choice(pool)
+        params = {}
+        for pname, prange in eff.param_ranges.items():
+            if prange.log_scale:
+                val = math.exp(rng.uniform(math.log(prange.min_val), math.log(prange.max_val)))
+            else:
+                val = rng.uniform(prange.min_val, prange.max_val)
+            if pname in INTEGER_PARAMS:
+                val = int(round(val))
+            params[pname] = val
+
+        chain.append({"effect": eff.name, "params": params})
+        prev_cat = eff.macro_category
+
+    return chain

multiafx/effects/__init__.py

@@ -0,0 +1,20 @@
+"""Effect implementations grouped by source library.
+
+Each module exposes plain functions with signature:
+    (audio: np.ndarray, sr: int, **params) -> np.ndarray
+
+Audio is always (channels, samples) float32. Functions return the same shape
+unless the effect inherently changes channel count (e.g. stereo synthesis).
+"""
+
+from multiafx.effects import (
+    audiomentations_effects as am,
+    librosa_effects as lib,
+    numpy_effects as npy,
+    pyloudnorm_effects as pln,
+    scipy_effects as sci,
+    sox_effects as sx,
+    torchaudio_effects as ta,
+)
+
+__all__ = ["am", "lib", "npy", "pln", "sci", "sx", "ta"]