cysox 0.1.4__cp311-cp311-macosx_11_0_arm64.whl

cysox/fx/reverb.py

@@ -0,0 +1,215 @@
+"""Reverb and spatial effects."""
+
+from typing import List
+
+from .base import Effect
+
+
+class Reverb(Effect):
+    """Add reverberation effect.
+
+    Args:
+        reverberance: Reverb time as percentage 0-100 (default: 50).
+        hf_damping: High frequency damping percentage 0-100 (default: 50).
+        room_scale: Room size percentage 0-100 (default: 100).
+        stereo_depth: Stereo spread percentage 0-100 (default: 100).
+        pre_delay: Pre-delay in milliseconds (default: 0).
+        wet_gain: Wet signal gain in dB (default: 0).
+        wet_only: Output only wet signal, no dry (default: False).
+
+    Example:
+        >>> fx.Reverb()                           # Default reverb
+        >>> fx.Reverb(reverberance=80)            # Long reverb
+        >>> fx.Reverb(room_scale=50, pre_delay=20)  # Small room with pre-delay
+    """
+
+    def __init__(
+        self,
+        reverberance: float = 50,
+        hf_damping: float = 50,
+        room_scale: float = 100,
+        stereo_depth: float = 100,
+        pre_delay: float = 0,
+        wet_gain: float = 0,
+        *,
+        wet_only: bool = False
+    ):
+        self.reverberance = reverberance
+        self.hf_damping = hf_damping
+        self.room_scale = room_scale
+        self.stereo_depth = stereo_depth
+        self.pre_delay = pre_delay
+        self.wet_gain = wet_gain
+        self.wet_only = wet_only
+
+    @property
+    def name(self) -> str:
+        return "reverb"
+
+    def to_args(self) -> List[str]:
+        args = []
+        if self.wet_only:
+            args.append("-w")
+        args.extend([
+            str(self.reverberance),
+            str(self.hf_damping),
+            str(self.room_scale),
+            str(self.stereo_depth),
+            str(self.pre_delay),
+            str(self.wet_gain),
+        ])
+        return args
+
+
+class Echo(Effect):
+    """Add echo effect.
+
+    Args:
+        gain_in: Input gain (0-1, default: 0.8).
+        gain_out: Output gain (0-1, default: 0.9).
+        delays: List of delay times in milliseconds.
+        decays: List of decay values (0-1) for each delay.
+
+    Example:
+        >>> fx.Echo(delays=[100], decays=[0.5])  # Single echo
+        >>> fx.Echo(delays=[100, 200], decays=[0.6, 0.3])  # Multi-tap
+    """
+
+    def __init__(
+        self,
+        delays: List[float],
+        decays: List[float],
+        *,
+        gain_in: float = 0.8,
+        gain_out: float = 0.9
+    ):
+        if len(delays) != len(decays):
+            raise ValueError("delays and decays must have same length")
+        self.gain_in = gain_in
+        self.gain_out = gain_out
+        self.delays = delays
+        self.decays = decays
+
+    @property
+    def name(self) -> str:
+        return "echo"
+
+    def to_args(self) -> List[str]:
+        args = [str(self.gain_in), str(self.gain_out)]
+        for delay, decay in zip(self.delays, self.decays):
+            args.extend([str(delay), str(decay)])
+        return args
+
+
+class Chorus(Effect):
+    """Add chorus effect.
+
+    Args:
+        gain_in: Input gain (0-1, default: 0.7).
+        gain_out: Output gain (0-1, default: 0.9).
+        delay: Base delay in milliseconds (default: 55).
+        decay: Decay factor (default: 0.4).
+        speed: Modulation speed in Hz (default: 0.25).
+        depth: Modulation depth in milliseconds (default: 2).
+        shape: Modulation shape 's' (sine) or 't' (triangle) (default: 's').
+
+    Example:
+        >>> fx.Chorus()  # Default chorus
+        >>> fx.Chorus(depth=4, speed=0.5)  # Deeper, faster modulation
+    """
+
+    def __init__(
+        self,
+        *,
+        gain_in: float = 0.7,
+        gain_out: float = 0.9,
+        delay: float = 55,
+        decay: float = 0.4,
+        speed: float = 0.25,
+        depth: float = 2,
+        shape: str = "s"
+    ):
+        if shape not in ("s", "t"):
+            raise ValueError("shape must be 's' (sine) or 't' (triangle)")
+        self.gain_in = gain_in
+        self.gain_out = gain_out
+        self.delay = delay
+        self.decay = decay
+        self.speed = speed
+        self.depth = depth
+        self.shape = shape
+
+    @property
+    def name(self) -> str:
+        return "chorus"
+
+    def to_args(self) -> List[str]:
+        return [
+            str(self.gain_in),
+            str(self.gain_out),
+            str(self.delay),
+            str(self.decay),
+            str(self.speed),
+            str(self.depth),
+            f"-{self.shape}",
+        ]
+
+
+class Flanger(Effect):
+    """Add flanger effect.
+
+    Args:
+        delay: Base delay in milliseconds (default: 0).
+        depth: Modulation depth in milliseconds (default: 2).
+        regen: Regeneration/feedback percentage -95 to 95 (default: 0).
+        width: Wet/dry mix percentage (default: 71).
+        speed: Modulation speed in Hz (default: 0.5).
+        shape: Modulation shape 'sine' or 'triangle' (default: 'sine').
+        phase: Phase offset percentage for stereo (default: 25).
+        interp: Interpolation 'linear' or 'quadratic' (default: 'linear').
+
+    Example:
+        >>> fx.Flanger()  # Default flanger
+        >>> fx.Flanger(depth=5, speed=0.3, regen=50)  # Deeper effect
+    """
+
+    def __init__(
+        self,
+        *,
+        delay: float = 0,
+        depth: float = 2,
+        regen: float = 0,
+        width: float = 71,
+        speed: float = 0.5,
+        shape: str = "sine",
+        phase: float = 25,
+        interp: str = "linear"
+    ):
+        if shape not in ("sine", "triangle"):
+            raise ValueError("shape must be 'sine' or 'triangle'")
+        if interp not in ("linear", "quadratic"):
+            raise ValueError("interp must be 'linear' or 'quadratic'")
+        self.delay = delay
+        self.depth = depth
+        self.regen = regen
+        self.width = width
+        self.speed = speed
+        self.shape = shape
+        self.phase = phase
+        self.interp = interp
+
+    @property
+    def name(self) -> str:
+        return "flanger"
+
+    def to_args(self) -> List[str]:
+        return [
+            str(self.delay),
+            str(self.depth),
+            str(self.regen),
+            str(self.width),
+            str(self.speed),
+            self.shape,
+            str(self.phase),
+            self.interp,
+        ]

cysox/fx/time.py

@@ -0,0 +1,248 @@
+"""Time-based effects (trim, pad, speed, tempo, etc.)."""
+
+from typing import List, Optional
+
+from .base import Effect
+
+
+class Trim(Effect):
+    """Extract a portion of the audio.
+
+    Specify either `end` or `duration`, not both.
+
+    Args:
+        start: Start time in seconds (default: 0).
+        end: End time in seconds (mutually exclusive with duration).
+        duration: Duration in seconds (mutually exclusive with end).
+
+    Example:
+        >>> fx.Trim(start=1.5, end=10.0)    # From 1.5s to 10s
+        >>> fx.Trim(start=5.0)              # From 5s to end
+        >>> fx.Trim(end=30.0)               # First 30 seconds
+        >>> fx.Trim(start=0, duration=10)   # First 10 seconds
+    """
+
+    def __init__(
+        self,
+        start: float = 0,
+        end: Optional[float] = None,
+        *,
+        duration: Optional[float] = None
+    ):
+        if end is not None and duration is not None:
+            raise ValueError("Cannot specify both 'end' and 'duration'")
+        self.start = start
+        self.end = end
+        self.duration = duration
+
+    @property
+    def name(self) -> str:
+        return "trim"
+
+    def to_args(self) -> List[str]:
+        args = [str(self.start)]
+        if self.duration is not None:
+            args.append(str(self.duration))
+        elif self.end is not None:
+            args.append(f"={self.end}")
+        return args
+
+
+class Pad(Effect):
+    """Add silence to the beginning and/or end.
+
+    Args:
+        before: Seconds of silence to add at the beginning (default: 0).
+        after: Seconds of silence to add at the end (default: 0).
+
+    Example:
+        >>> fx.Pad(before=1.0)           # Add 1s silence at start
+        >>> fx.Pad(after=2.0)            # Add 2s silence at end
+        >>> fx.Pad(before=0.5, after=1.0)  # Add both
+    """
+
+    def __init__(self, before: float = 0, after: float = 0):
+        self.before = before
+        self.after = after
+
+    @property
+    def name(self) -> str:
+        return "pad"
+
+    def to_args(self) -> List[str]:
+        return [str(self.before), str(self.after)]
+
+
+class Speed(Effect):
+    """Change playback speed (affects pitch).
+
+    Args:
+        factor: Speed multiplier. 2.0 = double speed (higher pitch),
+                0.5 = half speed (lower pitch).
+
+    Example:
+        >>> fx.Speed(factor=2.0)   # Double speed, octave up
+        >>> fx.Speed(factor=0.5)   # Half speed, octave down
+    """
+
+    def __init__(self, factor: float):
+        if factor <= 0:
+            raise ValueError("factor must be positive")
+        self.factor = factor
+
+    @property
+    def name(self) -> str:
+        return "speed"
+
+    def to_args(self) -> List[str]:
+        return [str(self.factor)]
+
+
+class Tempo(Effect):
+    """Change tempo without affecting pitch.
+
+    Args:
+        factor: Tempo multiplier. 2.0 = double tempo, 0.5 = half tempo.
+        audio_type: Optimize for 'm' (music), 's' (speech), or 'l' (linear).
+                   Default: None (auto-detect).
+        quick: Use quicker, lower-quality algorithm (default: False).
+
+    Example:
+        >>> fx.Tempo(factor=1.5)                    # 50% faster
+        >>> fx.Tempo(factor=0.8, audio_type='s')   # Slower speech
+    """
+
+    def __init__(
+        self,
+        factor: float,
+        *,
+        audio_type: Optional[str] = None,
+        quick: bool = False
+    ):
+        if factor <= 0:
+            raise ValueError("factor must be positive")
+        if audio_type is not None and audio_type not in ("m", "s", "l"):
+            raise ValueError("audio_type must be 'm', 's', or 'l'")
+        self.factor = factor
+        self.audio_type = audio_type
+        self.quick = quick
+
+    @property
+    def name(self) -> str:
+        return "tempo"
+
+    def to_args(self) -> List[str]:
+        args = []
+        if self.quick:
+            args.append("-q")
+        if self.audio_type:
+            args.append(f"-{self.audio_type}")
+        args.append(str(self.factor))
+        return args
+
+
+class Pitch(Effect):
+    """Change pitch without affecting tempo.
+
+    Args:
+        cents: Pitch shift in cents (100 cents = 1 semitone).
+        quick: Use quicker, lower-quality algorithm (default: False).
+
+    Example:
+        >>> fx.Pitch(cents=100)    # Up one semitone
+        >>> fx.Pitch(cents=-200)   # Down two semitones
+    """
+
+    def __init__(self, cents: float, *, quick: bool = False):
+        self.cents = cents
+        self.quick = quick
+
+    @property
+    def name(self) -> str:
+        return "pitch"
+
+    def to_args(self) -> List[str]:
+        args = []
+        if self.quick:
+            args.append("-q")
+        args.append(str(self.cents))
+        return args
+
+
+class Reverse(Effect):
+    """Reverse the audio.
+
+    Example:
+        >>> fx.Reverse()
+    """
+
+    @property
+    def name(self) -> str:
+        return "reverse"
+
+    def to_args(self) -> List[str]:
+        return []
+
+
+class Fade(Effect):
+    """Apply fade in and/or fade out.
+
+    Args:
+        fade_in: Fade-in duration in seconds (default: 0).
+        fade_out: Fade-out duration in seconds (default: 0).
+        type: Fade curve type - 'q' (quarter sine), 'h' (half sine),
+              't' (linear), 'l' (logarithmic), 'p' (parabola) (default: 't').
+
+    Example:
+        >>> fx.Fade(fade_in=0.5)                    # 0.5s fade in
+        >>> fx.Fade(fade_out=2.0)                   # 2s fade out
+        >>> fx.Fade(fade_in=1.0, fade_out=1.0, type='l')  # Log fades
+    """
+
+    def __init__(
+        self,
+        fade_in: float = 0,
+        fade_out: float = 0,
+        *,
+        type: str = "t"
+    ):
+        if type not in ("q", "h", "t", "l", "p"):
+            raise ValueError("type must be 'q', 'h', 't', 'l', or 'p'")
+        self.fade_in = fade_in
+        self.fade_out = fade_out
+        self.type = type
+
+    @property
+    def name(self) -> str:
+        return "fade"
+
+    def to_args(self) -> List[str]:
+        # sox fade type fade_in [stop_time [fade_out]]
+        args = [self.type, str(self.fade_in)]
+        if self.fade_out > 0:
+            # Using 0 for stop_time means end of file
+            args.extend(["0", str(self.fade_out)])
+        return args
+
+
+class Repeat(Effect):
+    """Repeat the audio.
+
+    Args:
+        count: Number of times to repeat (in addition to original).
+
+    Example:
+        >>> fx.Repeat(count=2)  # Play 3 times total
+    """
+
+    def __init__(self, count: int):
+        if count < 1:
+            raise ValueError("count must be at least 1")
+        self.count = count
+
+    @property
+    def name(self) -> str:
+        return "repeat"
+
+    def to_args(self) -> List[str]:
+        return [str(self.count)]

cysox/fx/volume.py

@@ -0,0 +1,98 @@
+"""Volume and gain effects."""
+
+from typing import List
+
+from .base import Effect
+
+
+class Volume(Effect):
+    """Adjust volume level.
+
+    Args:
+        db: Volume adjustment in decibels. Positive = louder, negative = quieter.
+        limiter: Apply limiter to prevent clipping (default: False).
+
+    Example:
+        >>> fx.Volume(db=3)          # Increase by 3dB
+        >>> fx.Volume(db=-6)         # Decrease by 6dB
+        >>> fx.Volume(db=6, limiter=True)  # Boost with limiting
+    """
+
+    def __init__(self, db: float = 0, *, limiter: bool = False):
+        self.db = db
+        self.limiter = limiter
+
+    @property
+    def name(self) -> str:
+        return "vol"
+
+    def to_args(self) -> List[str]:
+        args = [f"{self.db}dB"]
+        if self.limiter:
+            args.append("limiter")
+        return args
+
+
+class Gain(Effect):
+    """Apply gain with various options.
+
+    Args:
+        db: Gain in decibels.
+        normalize: Normalize to 0dBFS before applying gain.
+        limiter: Apply limiter to prevent clipping.
+        balance: Balance channels (for stereo).
+
+    Example:
+        >>> fx.Gain(db=-3)
+        >>> fx.Gain(db=0, normalize=True)  # Normalize only
+    """
+
+    def __init__(
+        self,
+        db: float = 0,
+        *,
+        normalize: bool = False,
+        limiter: bool = False,
+        balance: bool = False
+    ):
+        self.db = db
+        self.normalize = normalize
+        self.limiter = limiter
+        self.balance = balance
+
+    @property
+    def name(self) -> str:
+        return "gain"
+
+    def to_args(self) -> List[str]:
+        args = []
+        if self.normalize:
+            args.append("-n")
+        if self.limiter:
+            args.append("-l")
+        if self.balance:
+            args.append("-B")
+        args.append(str(self.db))
+        return args
+
+
+class Normalize(Effect):
+    """Normalize audio to a target level.
+
+    Args:
+        level: Target level in dB (default: -1 dBFS).
+
+    Example:
+        >>> fx.Normalize()           # Normalize to -1 dBFS
+        >>> fx.Normalize(level=-3)   # Normalize to -3 dBFS
+    """
+
+    def __init__(self, level: float = -1):
+        self.level = level
+
+    @property
+    def name(self) -> str:
+        return "norm"
+
+    def to_args(self) -> List[str]:
+        return [str(self.level)]

cysox/utils.py

@@ -0,0 +1,47 @@
+# Version utility functions
+
+
+def lib_version(major: int, minor: int, patch: int) -> int:
+    """Compute a 32-bit integer API version from three 8-bit parts."""
+    return ((major) << 16) + ((minor) << 8) + (patch)
+
+
+def lib_version_code() -> int:
+    """Get the current libSoX version code."""
+    return lib_version(14, 4, 2)
+
+
+def int_min(bits: int) -> int:
+    """Returns the smallest (negative) value storable in a twos-complement signed
+    integer with the specified number of bits, cast to an unsigned integer.
+
+    for example, SOX_INT_MIN(8) = 0x80, SOX_INT_MIN(16) = 0x8000, etc.
+    @param bits Size of value for which to calculate minimum.
+    @returns the smallest (negative) value storable in a twos-complement signed
+    integer with the specified number of bits, cast to an unsigned integer.
+    """
+    return 1 << ((bits) - 1)
+
+
+def int_max(bits: int) -> int:
+    """Returns the largest (positive) value storable in a twos-complement signed
+    integer with the specified number of bits, cast to an unsigned integer.
+
+    for example, SOX_INT_MAX(8) = 0x7F, SOX_INT_MAX(16) = 0x7FFF, etc.
+    @param bits Size of value for which to calculate maximum.
+    @returns the largest (positive) value storable in a twos-complement signed
+    integer with the specified number of bits, cast to an unsigned integer.
+    """
+    return (-1 + 2**32) >> (33 - (bits))
+
+
+def uint_max(bits: int) -> int:
+    """Returns the largest value storable in an unsigned integer with the specified
+    number of bits;
+
+    for example, SOX_UINT_MAX(8) = 0xFF, SOX_UINT_MAX(16) = 0xFFFF, etc.
+    @param bits Size of value for which to calculate maximum.
+    @returns the largest value storable in an unsigned integer with the specified
+    number of bits.
+    """
+    return int_min(bits) | int_max(bits)

cysox/utils.pyi

@@ -0,0 +1,21 @@
+# Type stubs for cysox.utils
+
+def lib_version(major: int, minor: int, patch: int) -> int:
+    """Compute a 32-bit integer API version from three 8-bit parts."""
+    ...
+
+def lib_version_code() -> int:
+    """Get the current libSoX version code."""
+    ...
+
+def int_min(bits: int) -> int:
+    """Returns the smallest (negative) value storable in a twos-complement signed integer."""
+    ...
+
+def int_max(bits: int) -> int:
+    """Returns the largest (positive) value storable in a twos-complement signed integer."""
+    ...
+
+def uint_max(bits: int) -> int:
+    """Returns the largest value storable in an unsigned integer."""
+    ...