cysox 0.1.4__cp311-cp311-macosx_11_0_arm64.whl

cysox/fx/base.py

@@ -0,0 +1,168 @@
+"""Base classes for typed audio effects."""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+class Effect(ABC):
+    """Base class for all typed effects.
+
+    Subclasses must implement:
+    - name: The sox effect name
+    - to_args(): Convert parameters to sox argument list
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The sox effect name."""
+        pass
+
+    @abstractmethod
+    def to_args(self) -> List[str]:
+        """Convert effect parameters to sox argument list."""
+        pass
+
+    def _repr_args(self) -> str:
+        """Return string representation of arguments for __repr__."""
+        args = []
+        for key, value in self.__dict__.items():
+            if not key.startswith('_'):
+                args.append(f"{key}={value!r}")
+        return ", ".join(args)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self._repr_args()})"
+
+
+class CompositeEffect(Effect):
+    """Base class for effects that combine multiple sox effects.
+
+    Subclasses must implement the `effects` property returning a list
+    of Effect instances to be applied in sequence.
+
+    Example:
+        class WarmReverb(CompositeEffect):
+            def __init__(self, decay=60):
+                self.decay = decay
+
+            @property
+            def effects(self):
+                return [
+                    HighPass(frequency=80),
+                    Reverb(reverberance=self.decay),
+                    Volume(db=-2),
+                ]
+    """
+
+    @property
+    @abstractmethod
+    def effects(self) -> List[Effect]:
+        """Return list of constituent effects."""
+        pass
+
+    @property
+    def name(self) -> str:
+        return self.__class__.__name__
+
+    def to_args(self) -> List[str]:
+        raise TypeError(
+            f"CompositeEffect '{self.name}' must be expanded, not converted to args. "
+            "Use expand_effects() to get the list of constituent effects."
+        )
+
+
+class PythonEffect(Effect):
+    """Base class for custom Python-based sample processing.
+
+    Subclasses must implement the `process()` method which receives
+    samples as a numpy array and returns processed samples.
+
+    Note: Python effects require numpy and run outside the sox pipeline,
+    making them slower than native sox effects. Use for custom DSP that
+    sox doesn't support.
+
+    Example:
+        class BitCrusher(PythonEffect):
+            def __init__(self, bits=8):
+                self.bits = bits
+
+            def process(self, samples, sample_rate, channels):
+                levels = 2 ** self.bits
+                return np.round(samples * levels) / levels
+    """
+
+    @property
+    def name(self) -> str:
+        return self.__class__.__name__
+
+    def to_args(self) -> List[str]:
+        raise TypeError(
+            f"PythonEffect '{self.name}' cannot be converted to sox args. "
+            "It will be processed separately using the process() method."
+        )
+
+    @abstractmethod
+    def process(
+        self,
+        samples: "np.ndarray",
+        sample_rate: int,
+        channels: int
+    ) -> "np.ndarray":
+        """Process audio samples.
+
+        Args:
+            samples: Input samples as numpy array of shape (n_samples,) for mono
+                    or (n_samples, channels) for multi-channel.
+            sample_rate: Sample rate in Hz.
+            channels: Number of audio channels.
+
+        Returns:
+            Processed samples as numpy array with same shape as input.
+        """
+        pass
+
+
+class CEffect(Effect):
+    """Base class for custom C-level effects.
+
+    For advanced users who implement effects in C or Cython and need
+    to register them with sox.
+
+    Subclasses should:
+    1. Set _handler_ptr to the pointer returned by their Cython module
+    2. Call register() once at startup before using the effect
+    """
+
+    _handler_ptr: int = None
+
+    @classmethod
+    def register(cls) -> None:
+        """Register this effect's handler with sox.
+
+        Must be called once before using the effect.
+        """
+        if cls._handler_ptr is None:
+            raise ValueError(f"{cls.__name__}._handler_ptr is not set")
+
+        from cysox import sox
+        if hasattr(sox, 'register_effect_handler'):
+            sox.register_effect_handler(cls._handler_ptr)
+        else:
+            raise NotImplementedError(
+                "Custom C effect registration not yet implemented in low-level API"
+            )
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The registered effect name."""
+        pass
+
+    @abstractmethod
+    def to_args(self) -> List[str]:
+        """Convert parameters to sox argument list."""
+        pass

cysox/fx/convert.py

@@ -0,0 +1,128 @@
+"""Format conversion effects (rate, channels, bits)."""
+
+from typing import List, Optional
+
+from .base import Effect
+
+
+class Rate(Effect):
+    """Resample to a different sample rate.
+
+    Args:
+        sample_rate: Target sample rate in Hz.
+        quality: Resampling quality - 'quick', 'low', 'medium', 'high',
+                or 'very-high' (default: 'high').
+
+    Example:
+        >>> fx.Rate(sample_rate=48000)
+        >>> fx.Rate(sample_rate=44100, quality='very-high')
+    """
+
+    QUALITY_FLAGS = {
+        "quick": "-q",
+        "low": "-l",
+        "medium": "-m",
+        "high": "-h",
+        "very-high": "-v",
+    }
+
+    def __init__(self, sample_rate: int, *, quality: str = "high"):
+        if quality not in self.QUALITY_FLAGS:
+            raise ValueError(
+                f"quality must be one of: {', '.join(self.QUALITY_FLAGS.keys())}"
+            )
+        self.sample_rate = sample_rate
+        self.quality = quality
+
+    @property
+    def name(self) -> str:
+        return "rate"
+
+    def to_args(self) -> List[str]:
+        return [self.QUALITY_FLAGS[self.quality], str(self.sample_rate)]
+
+
+class Channels(Effect):
+    """Change the number of audio channels.
+
+    Args:
+        channels: Target number of channels (1=mono, 2=stereo, etc.).
+
+    Example:
+        >>> fx.Channels(channels=1)   # Convert to mono
+        >>> fx.Channels(channels=2)   # Convert to stereo
+    """
+
+    def __init__(self, channels: int):
+        if channels < 1:
+            raise ValueError("channels must be at least 1")
+        self.channels = channels
+
+    @property
+    def name(self) -> str:
+        return "channels"
+
+    def to_args(self) -> List[str]:
+        return [str(self.channels)]
+
+
+class Remix(Effect):
+    """Remix channels with custom mix specification.
+
+    Args:
+        mix: Channel mix specification. Each output channel is specified
+             as a string like "1,2" (mix channels 1 and 2) or "1v0.5,2v0.5"
+             (mix with volume adjustment). Use "-" for silence.
+
+    Example:
+        >>> fx.Remix(mix=["1,2"])           # Mono mixdown
+        >>> fx.Remix(mix=["1", "2"])        # Keep stereo as-is
+        >>> fx.Remix(mix=["2", "1"])        # Swap L/R
+        >>> fx.Remix(mix=["1v0.5,2v0.5"])   # Mono with equal mix
+    """
+
+    def __init__(self, mix: List[str]):
+        self.mix = mix
+
+    @property
+    def name(self) -> str:
+        return "remix"
+
+    def to_args(self) -> List[str]:
+        return self.mix
+
+
+class Dither(Effect):
+    """Apply dithering for bit-depth reduction.
+
+    Args:
+        type: Dither type - 'rectangular', 'triangular', 'gaussian',
+              or 'shaped' (default: 'shaped').
+        precision: Target precision in bits (optional).
+
+    Example:
+        >>> fx.Dither()                      # Default shaped dither
+        >>> fx.Dither(type='triangular')     # TPDF dither
+    """
+
+    def __init__(
+        self,
+        *,
+        type: str = "shaped",
+        precision: Optional[int] = None
+    ):
+        valid_types = ("rectangular", "triangular", "gaussian", "shaped")
+        if type not in valid_types:
+            raise ValueError(f"type must be one of: {', '.join(valid_types)}")
+        self.type = type
+        self.precision = precision
+
+    @property
+    def name(self) -> str:
+        return "dither"
+
+    def to_args(self) -> List[str]:
+        args = [f"-{self.type[0]}"]  # First letter
+        if self.precision is not None:
+            args.extend(["-p", str(self.precision)])
+        return args

cysox/fx/eq.py

@@ -0,0 +1,94 @@
+"""Equalization effects (bass, treble, equalizer)."""
+
+from typing import List
+
+from .base import Effect
+
+
+class Bass(Effect):
+    """Boost or cut bass frequencies.
+
+    Args:
+        gain: Amount to boost (positive) or cut (negative) in dB.
+        frequency: Center frequency in Hz (default: 100).
+        width: Filter width in octaves (default: 0.5).
+
+    Example:
+        >>> fx.Bass(gain=5)              # Boost bass by 5dB
+        >>> fx.Bass(gain=-3, frequency=80)  # Cut at 80Hz
+    """
+
+    def __init__(
+        self,
+        gain: float,
+        *,
+        frequency: float = 100,
+        width: float = 0.5
+    ):
+        self.gain = gain
+        self.frequency = frequency
+        self.width = width
+
+    @property
+    def name(self) -> str:
+        return "bass"
+
+    def to_args(self) -> List[str]:
+        return [str(self.gain), str(self.frequency), str(self.width)]
+
+
+class Treble(Effect):
+    """Boost or cut treble frequencies.
+
+    Args:
+        gain: Amount to boost (positive) or cut (negative) in dB.
+        frequency: Center frequency in Hz (default: 3000).
+        width: Filter width in octaves (default: 0.5).
+
+    Example:
+        >>> fx.Treble(gain=3)             # Boost treble by 3dB
+        >>> fx.Treble(gain=-2, frequency=4000)  # Cut at 4kHz
+    """
+
+    def __init__(
+        self,
+        gain: float,
+        *,
+        frequency: float = 3000,
+        width: float = 0.5
+    ):
+        self.gain = gain
+        self.frequency = frequency
+        self.width = width
+
+    @property
+    def name(self) -> str:
+        return "treble"
+
+    def to_args(self) -> List[str]:
+        return [str(self.gain), str(self.frequency), str(self.width)]
+
+
+class Equalizer(Effect):
+    """Peaking EQ filter at a specific frequency.
+
+    Args:
+        frequency: Center frequency in Hz.
+        width: Filter width (Q factor or bandwidth in Hz).
+        gain: Amount to boost (positive) or cut (negative) in dB.
+
+    Example:
+        >>> fx.Equalizer(frequency=1000, width=1, gain=3)  # Boost 1kHz
+    """
+
+    def __init__(self, frequency: float, width: float, gain: float):
+        self.frequency = frequency
+        self.width = width
+        self.gain = gain
+
+    @property
+    def name(self) -> str:
+        return "equalizer"
+
+    def to_args(self) -> List[str]:
+        return [str(self.frequency), str(self.width), str(self.gain)]

cysox/fx/filter.py

@@ -0,0 +1,131 @@
+"""Filter effects (highpass, lowpass, bandpass, etc.)."""
+
+from typing import List
+
+from .base import Effect
+
+
+class HighPass(Effect):
+    """High-pass filter (removes low frequencies).
+
+    Args:
+        frequency: Cutoff frequency in Hz.
+        poles: Filter order, 1 or 2 (default: 2). Higher = steeper rolloff.
+
+    Example:
+        >>> fx.HighPass(frequency=80)     # Remove rumble below 80Hz
+        >>> fx.HighPass(frequency=200, poles=1)  # Gentle rolloff
+    """
+
+    def __init__(self, frequency: float, *, poles: int = 2):
+        if poles not in (1, 2):
+            raise ValueError("poles must be 1 or 2")
+        self.frequency = frequency
+        self.poles = poles
+
+    @property
+    def name(self) -> str:
+        return "highpass"
+
+    def to_args(self) -> List[str]:
+        return [f"-{self.poles}", str(self.frequency)]
+
+
+class LowPass(Effect):
+    """Low-pass filter (removes high frequencies).
+
+    Args:
+        frequency: Cutoff frequency in Hz.
+        poles: Filter order, 1 or 2 (default: 2). Higher = steeper rolloff.
+
+    Example:
+        >>> fx.LowPass(frequency=8000)    # Remove highs above 8kHz
+        >>> fx.LowPass(frequency=4000, poles=1)  # Gentle rolloff
+    """
+
+    def __init__(self, frequency: float, *, poles: int = 2):
+        if poles not in (1, 2):
+            raise ValueError("poles must be 1 or 2")
+        self.frequency = frequency
+        self.poles = poles
+
+    @property
+    def name(self) -> str:
+        return "lowpass"
+
+    def to_args(self) -> List[str]:
+        return [f"-{self.poles}", str(self.frequency)]
+
+
+class BandPass(Effect):
+    """Band-pass filter (passes frequencies within a range).
+
+    Args:
+        frequency: Center frequency in Hz.
+        width: Filter width. Interpretation depends on width_type.
+        width_type: 'q' for Q-factor, 'h' for Hz, 'o' for octaves (default: 'q').
+        constant_skirt: Use constant skirt gain (default: False).
+
+    Example:
+        >>> fx.BandPass(frequency=1000, width=2)  # Q=2 bandpass at 1kHz
+    """
+
+    def __init__(
+        self,
+        frequency: float,
+        width: float,
+        *,
+        width_type: str = "q",
+        constant_skirt: bool = False
+    ):
+        if width_type not in ("q", "h", "o"):
+            raise ValueError("width_type must be 'q', 'h', or 'o'")
+        self.frequency = frequency
+        self.width = width
+        self.width_type = width_type
+        self.constant_skirt = constant_skirt
+
+    @property
+    def name(self) -> str:
+        return "bandpass"
+
+    def to_args(self) -> List[str]:
+        args = []
+        if self.constant_skirt:
+            args.append("-c")
+        args.append(str(self.frequency))
+        args.append(f"{self.width}{self.width_type}")
+        return args
+
+
+class BandReject(Effect):
+    """Band-reject (notch) filter.
+
+    Args:
+        frequency: Center frequency in Hz.
+        width: Filter width. Interpretation depends on width_type.
+        width_type: 'q' for Q-factor, 'h' for Hz, 'o' for octaves (default: 'q').
+
+    Example:
+        >>> fx.BandReject(frequency=60, width=10)  # Remove 60Hz hum
+    """
+
+    def __init__(
+        self,
+        frequency: float,
+        width: float,
+        *,
+        width_type: str = "q"
+    ):
+        if width_type not in ("q", "h", "o"):
+            raise ValueError("width_type must be 'q', 'h', or 'o'")
+        self.frequency = frequency
+        self.width = width
+        self.width_type = width_type
+
+    @property
+    def name(self) -> str:
+        return "bandreject"
+
+    def to_args(self) -> List[str]:
+        return [str(self.frequency), f"{self.width}{self.width_type}"]