pysoniq 0.1.0__tar.gz

pysoniq-0.1.0/LICENSE

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

pysoniq-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: pysoniq
+Version: 0.1.0
+Summary: Lightweight, pure-Python cross-platform audio playback library
+Author: laelume
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/laelume/pysoniq
+Project-URL: Repository, https://github.com/laelume/pysoniq
+Project-URL: Issues, https://github.com/laelume/pysoniq/issues
+Keywords: audio,sound,playback,music,cross-platform,pure-python,audio-playback,audio-player,sound-playback,wav
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Players
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.19.0
+Dynamic: license-file
+
+# pysoniq
+
+Minimal, pure-Python cross-platform audio playback library.
+
+- **Pure Python** - No compiled extensions
+- **Cross-platform** - Windows, macOS, Linux
+- **Minimal dependencies** - Only numpy
+- **Simple API** - Play, pause, stop, loop
+
+## Installation
+```bash
+pip install pysoniq
+```
+
+## Use in context
+```python
+import pysoniq as ps
+import numpy as np
+
+# Play WAV file
+ps.play('audio.wav')
+
+# Play as numpy array
+sr = 44100
+t = np.linspace(0, 1.0, sr)
+audio = 0.3 * np.sin(2 * np.pi * 440 * t)
+ps.play(audio, samplerate=sr)
+
+# Loop playback
+ps.set_loop(True)
+ps.play(audio, sr)
+
+# Stop
+ps.stop()
+```
+
+## Features
+
+**Playback**
+```python
+ps.play(data, samplerate)  # Play audio
+ps.stop()                   # Stop playback
+ps.pause()                  # Pause
+ps.resume()                 # Resume
+```
+
+**Looping**
+```python
+ps.set_loop(True)   # Enable loop
+ps.is_looping()     # Check status
+```
+
+**Gain Control**
+```python
+ps.set_gain(0.5)           # 50% volume
+ps.set_volume_db(-6.0)     # Set dB
+audio = ps.adjust_gain_level(audio, 1.5)
+```
+
+**Audio I/O**
+```python
+audio, sr = ps.load('file.wav')
+ps.save('output.wav', audio, sr)
+```
+
+## Platform Requirements
+
+- **Windows**: Built-in (winsound)
+- **macOS**: Built-in (afplay)
+- **Linux**: ALSA (aplay) - usually pre-installed
+
+## Limitations
+
+- WAV format only (for now)
+- Pause/resume uses time-based estimation
+- Gain changes apply on next loop iteration
+
+## License
+
+MIT
+
+## Author
+
+laelume

pysoniq-0.1.0/README.md

@@ -0,0 +1,84 @@
+# pysoniq
+
+Minimal, pure-Python cross-platform audio playback library.
+
+- **Pure Python** - No compiled extensions
+- **Cross-platform** - Windows, macOS, Linux
+- **Minimal dependencies** - Only numpy
+- **Simple API** - Play, pause, stop, loop
+
+## Installation
+```bash
+pip install pysoniq
+```
+
+## Use in context
+```python
+import pysoniq as ps
+import numpy as np
+
+# Play WAV file
+ps.play('audio.wav')
+
+# Play as numpy array
+sr = 44100
+t = np.linspace(0, 1.0, sr)
+audio = 0.3 * np.sin(2 * np.pi * 440 * t)
+ps.play(audio, samplerate=sr)
+
+# Loop playback
+ps.set_loop(True)
+ps.play(audio, sr)
+
+# Stop
+ps.stop()
+```
+
+## Features
+
+**Playback**
+```python
+ps.play(data, samplerate)  # Play audio
+ps.stop()                   # Stop playback
+ps.pause()                  # Pause
+ps.resume()                 # Resume
+```
+
+**Looping**
+```python
+ps.set_loop(True)   # Enable loop
+ps.is_looping()     # Check status
+```
+
+**Gain Control**
+```python
+ps.set_gain(0.5)           # 50% volume
+ps.set_volume_db(-6.0)     # Set dB
+audio = ps.adjust_gain_level(audio, 1.5)
+```
+
+**Audio I/O**
+```python
+audio, sr = ps.load('file.wav')
+ps.save('output.wav', audio, sr)
+```
+
+## Platform Requirements
+
+- **Windows**: Built-in (winsound)
+- **macOS**: Built-in (afplay)
+- **Linux**: ALSA (aplay) - usually pre-installed
+
+## Limitations
+
+- WAV format only (for now)
+- Pause/resume uses time-based estimation
+- Gain changes apply on next loop iteration
+
+## License
+
+MIT
+
+## Author
+
+laelume

pysoniq-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pysoniq"
+version = "0.1.0"
+description = "Lightweight, pure-Python cross-platform audio playback library"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+    {name = "laelume"}
+]
+keywords = [
+    "audio", "sound", "playback", "music", 
+    "cross-platform", "pure-python", "audio-playback",
+    "audio-player", "sound-playback", "wav"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Sound/Audio :: Players",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "numpy>=1.19.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/laelume/pysoniq"
+Repository = "https://github.com/laelume/pysoniq"
+Issues = "https://github.com/laelume/pysoniq/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pysoniq*"]
+
+[tool.setuptools.package-data]
+pysoniq = ["*.md"]

pysoniq-0.1.0/pysoniq/__init__.py

@@ -0,0 +1,22 @@
+"""pysoniq - Lightweight cross-platform audio library"""
+
+from .play import play
+from .stop import stop
+from .pause import pause, resume, is_paused
+from .loop import set_loop, is_looping
+from .io import load, save
+from .gain import (
+    set_gain, get_gain, 
+    set_volume_db, get_volume_db,
+    adjust_gain_level, normalize, compress, limiter,
+    db_to_linear, linear_to_db
+)
+
+__version__ = '0.1.0'
+__all__ = [
+    'play', 'stop', 'pause', 'resume', 'is_paused',
+    'load', 'save', 'set_loop', 'is_looping',
+    'set_gain', 'get_gain', 'set_volume_db', 'get_volume_db',
+    'adjust_gain_level', 'normalize', 'compress', 'limiter',
+    'db_to_linear', 'linear_to_db'
+]

pysoniq-0.1.0/pysoniq/gain.py

@@ -0,0 +1,184 @@
+"""Gain and volume control"""
+
+import numpy as np
+
+# Module state
+_global_gain = 1.0  # Linear gain (0.0 to 2.0+)
+_global_volume_db = 0.0  # dB (-inf to +6 dB typical)
+
+
+def set_gain(gain):
+    """
+    Set global gain (linear)
+    
+    Args:
+        gain: float, 0.0 to 2.0+ (1.0 = unity)
+    """
+    global _global_gain
+    _global_gain = max(0.0, gain)
+
+
+def get_gain():
+    """Get current global gain (linear)"""
+    return _global_gain
+
+
+def set_volume_db(db):
+    """
+    Set global volume in dB
+    
+    Args:
+        db: float, typically -60 to +6 dB (0 dB = unity)
+    """
+    global _global_volume_db, _global_gain
+    _global_volume_db = db
+    _global_gain = db_to_linear(db)
+
+
+def get_volume_db():
+    """Get current global volume in dB"""
+    return _global_volume_db
+
+
+def adjust_gain_level(audio, gain=None):
+    """
+    Adjust audio gain level
+    
+    Args:
+        audio: numpy array
+        gain: float, if None uses global gain (1.0 = unity, <1.0 = reduce, >1.0 = boost)
+    
+    Returns:
+        audio with gain adjusted (clipped to -1, 1)
+    """
+    if gain is None:
+        gain = _global_gain
+    
+    return np.clip(audio * gain, -1.0, 1.0)
+
+
+def db_to_linear(db):
+    """
+    Convert dB to linear gain
+    
+    Args:
+        db: float, decibels
+    
+    Returns:
+        linear gain
+    """
+    return 10.0 ** (db / 20.0)
+
+
+def linear_to_db(gain):
+    """
+    Convert linear gain to dB
+    
+    Args:
+        gain: float, linear gain
+    
+    Returns:
+        dB value
+    """
+    if gain <= 0:
+        return -np.inf
+    return 20.0 * np.log10(gain)
+
+
+def normalize(audio, target_db=-3.0):
+    """
+    Normalize audio to target dB level
+    
+    Args:
+        audio: numpy array
+        target_db: float, target peak level in dB (e.g., -3.0)
+    
+    Returns:
+        normalized audio
+    """
+    peak = np.max(np.abs(audio))
+    if peak == 0:
+        return audio
+    
+    target_linear = db_to_linear(target_db)
+    current_db = linear_to_db(peak)
+    gain_needed = target_linear / peak
+    
+    return audio * gain_needed
+
+
+def compress(audio, threshold_db=-20.0, ratio=4.0, attack_ms=5.0, release_ms=50.0, sr=44100):
+    """
+    Simple dynamics compression
+    
+    Args:
+        audio: numpy array (mono)
+        threshold_db: float, compression threshold
+        ratio: float, compression ratio (e.g., 4.0 = 4:1)
+        attack_ms: float, attack time in milliseconds
+        release_ms: float, release time in milliseconds
+        sr: int, sample rate
+    
+    Returns:
+        compressed audio
+    """
+    # Convert threshold to linear
+    threshold = db_to_linear(threshold_db)
+    
+    # Calculate attack/release coefficients
+    attack_samples = int(attack_ms * sr / 1000.0)
+    release_samples = int(release_ms * sr / 1000.0)
+    
+    # Simple envelope follower with compression
+    envelope = np.abs(audio)
+    gain_reduction = np.ones_like(audio)
+    
+    for i in range(len(audio)):
+        # If above threshold, calculate gain reduction
+        if envelope[i] > threshold:
+            # Calculate how much over threshold
+            over = envelope[i] / threshold
+            # Apply ratio
+            gain_reduction[i] = 1.0 / (1.0 + (over - 1.0) * (ratio - 1.0) / ratio)
+    
+    # Apply gain reduction with smoothing
+    smoothed_gain = np.copy(gain_reduction)
+    for i in range(1, len(smoothed_gain)):
+        if gain_reduction[i] < smoothed_gain[i-1]:
+            # Attack
+            alpha = 1.0 - np.exp(-1.0 / attack_samples)
+        else:
+            # Release
+            alpha = 1.0 - np.exp(-1.0 / release_samples)
+        
+        smoothed_gain[i] = alpha * gain_reduction[i] + (1.0 - alpha) * smoothed_gain[i-1]
+    
+    return audio * smoothed_gain
+
+
+def limiter(audio, threshold_db=-1.0, ceiling_db=-0.1):
+    """
+    Hard limiter to prevent clipping
+    
+    Args:
+        audio: numpy array
+        threshold_db: float, where limiting starts
+        ceiling_db: float, absolute maximum level
+    
+    Returns:
+        limited audio
+    """
+    threshold = db_to_linear(threshold_db)
+    ceiling = db_to_linear(ceiling_db)
+    
+    # Hard clip at ceiling
+    audio = np.clip(audio, -ceiling, ceiling)
+    
+    # Soft limiting above threshold
+    mask = np.abs(audio) > threshold
+    if np.any(mask):
+        # Soft knee compression above threshold
+        over = np.abs(audio[mask]) - threshold
+        audio[mask] = np.sign(audio[mask]) * (threshold + over / (1.0 + over))
+    
+    return audio

pysoniq-0.1.0/pysoniq/io.py

@@ -0,0 +1,105 @@
+"""Audio file I/O"""
+
+import numpy as np
+import wave
+from pathlib import Path
+
+def load(filepath):
+    """
+    Load audio file
+    
+    Args:
+        filepath: str or Path to audio file
+    
+    Returns:
+        audio: numpy array (normalized float32, -1 to 1)
+        samplerate: int, sample rate in Hz
+    
+    Supports: .wav
+    """
+    filepath = Path(filepath)
+    
+    if filepath.suffix.lower() == '.wav':
+        return _load_wav(filepath)
+    else:
+        raise ValueError(f"Unsupported format: {filepath.suffix}")
+
+
+def _load_wav(filepath):
+    """Load WAV file using wave module"""
+    with wave.open(str(filepath), 'rb') as wav:
+        n_channels = wav.getnchannels()
+        sampwidth = wav.getsampwidth()
+        framerate = wav.getframerate()
+        n_frames = wav.getnframes()
+        
+        # Read raw data
+        raw_data = wav.readframes(n_frames)
+    
+    # Convert to numpy array based on sample width
+    if sampwidth == 1:  # 8-bit unsigned
+        audio = np.frombuffer(raw_data, dtype=np.uint8)
+        audio = (audio.astype(np.float32) - 128) / 128.0
+    elif sampwidth == 2:  # 16-bit signed
+        audio = np.frombuffer(raw_data, dtype=np.int16)
+        audio = audio.astype(np.float32) / 32768.0
+    elif sampwidth == 3:  # 24-bit signed
+        # Expand 24-bit to 32-bit
+        audio_bytes = np.frombuffer(raw_data, dtype=np.uint8)
+        audio_int32 = np.zeros(len(audio_bytes) // 3, dtype=np.int32)
+        for i in range(len(audio_int32)):
+            audio_int32[i] = (audio_bytes[i*3] | 
+                             (audio_bytes[i*3+1] << 8) | 
+                             (audio_bytes[i*3+2] << 16))
+            # Sign extend
+            if audio_int32[i] & 0x800000:
+                audio_int32[i] |= 0xFF000000
+        audio = audio_int32.astype(np.float32) / 8388608.0
+    elif sampwidth == 4:  # 32-bit signed
+        audio = np.frombuffer(raw_data, dtype=np.int32)
+        audio = audio.astype(np.float32) / 2147483648.0
+    else:
+        raise ValueError(f"Unsupported sample width: {sampwidth}")
+    
+    # Reshape for multi-channel
+    if n_channels > 1:
+        audio = audio.reshape(-1, n_channels)
+    
+    return audio, framerate
+
+
+def save(filepath, audio, samplerate):
+    """
+    Save audio to file
+    
+    Args:
+        filepath: str or Path to output file
+        audio: numpy array (float32, -1 to 1)
+        samplerate: int, sample rate in Hz
+    
+    Supports: .wav
+    """
+    filepath = Path(filepath)
+    
+    if filepath.suffix.lower() == '.wav':
+        _save_wav(filepath, audio, samplerate)
+    else:
+        raise ValueError(f"Unsupported format: {filepath.suffix}")
+
+
+def _save_wav(filepath, audio, samplerate):
+    """Save WAV file using wave module"""
+    from .utils import to_int16
+    
+    # Convert to mono if needed
+    if audio.ndim > 1:
+        audio = np.mean(audio, axis=1)
+    
+    # Convert to 16-bit PCM
+    audio_int16 = to_int16(audio)
+    
+    with wave.open(str(filepath), 'wb') as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)
+        wav.setframerate(samplerate)
+        wav.writeframes(audio_int16.tobytes())

pysoniq-0.1.0/pysoniq/loop.py

@@ -0,0 +1,131 @@
+"""Loop control for audio playback"""
+
+import threading
+import time
+
+# Module-level state
+_loop_enabled = False
+_stop_requested = False
+_playback_thread = None
+_current_audio = None
+_current_samplerate = None
+_play_function = None
+
+
+def set_loop(enabled):
+    """Enable or disable looping"""
+    global _loop_enabled
+    _loop_enabled = enabled
+
+
+def is_looping():
+    """Check if looping is enabled"""
+    return _loop_enabled
+
+
+def stop():
+    """Stop playback but preserve loop state"""
+    global _stop_requested
+    # Note: we do NOT touch _loop_enabled here
+    _stop_requested = True
+    
+    print(f"DEBUG: loop.stop() called, loop_enabled={_loop_enabled} (preserved)")
+
+# def stop():
+#     """Stop playback and looping"""
+#     global _stop_requested, _loop_enabled
+    
+#     print(f"DEBUG: loop.stop() called from loop.py, was loop_enabled={_loop_enabled}")
+    
+#     _stop_requested = True
+#     _loop_enabled = False
+    
+#     # Platform-specific stop
+#     import sys
+#     if sys.platform == 'win32':
+#         print("DEBUG: Calling winsound.PlaySound(None, SND_PURGE)")
+#         try:
+#             import winsound
+#             winsound.PlaySound(None, winsound.SND_PURGE)
+#             print("DEBUG: winsound stop completed")
+#         except Exception as e:
+#             print(f"DEBUG: winsound stop failed: {e}")
+#     else:
+#         # Kill subprocess for macOS/Linux
+#         from . import playback
+#         if hasattr(playback, '_current_process') and playback._current_process:
+#             try:
+#                 print(f"DEBUG: Terminating process {playback._current_process.pid}")
+#                 playback._current_process.terminate()
+#                 playback._current_process = None
+#                 print("DEBUG: Process terminated")
+#             except Exception as e:
+#                 print(f"DEBUG: Process terminate failed: {e}")
+    
+#     print(f"DEBUG: loop.stop() completed, stop_requested={_stop_requested}, loop_enabled={_loop_enabled}")
+
+
+def is_stopped():
+    """Check if stop was requested"""
+    return _stop_requested
+
+
+def reset_stop():
+    """Reset stop flag"""
+    global _stop_requested
+    _stop_requested = False
+
+
+def start_loop(audio_data, samplerate, play_func):
+    """Start looping playback in background thread"""
+    global _playback_thread, _current_audio, _current_samplerate, _play_function
+    
+    print(f"DEBUG: start_loop called, loop_enabled={_loop_enabled}")
+    
+    _current_audio = audio_data
+    _current_samplerate = samplerate
+    _play_function = play_func
+    
+    # Only stop existing playback thread if one is running
+    if _playback_thread is not None and _playback_thread.is_alive():
+        global _stop_requested
+        _stop_requested = True
+        time.sleep(0.1)
+        # Don't call stop() - just set the flag
+    
+    # Reset stop flag for new playback
+    _stop_requested = False
+    
+    print(f"DEBUG: Starting thread, loop_enabled={_loop_enabled}")
+    
+    # Start loop thread
+    _playback_thread = threading.Thread(target=_loop_worker, daemon=True)
+    _playback_thread.start()
+
+
+def _loop_worker():
+    """Worker thread for looping playback"""
+    global _loop_enabled, _stop_requested
+    
+    print(f"DEBUG: Loop worker started, loop_enabled={_loop_enabled}")  # Add debug
+    
+    while _loop_enabled and not _stop_requested:
+        try:
+            # Play audio (blocking) - call the function directly, don't go through play()
+            _play_function(_current_audio, _current_samplerate, blocking=True)
+            
+            print(f"DEBUG: Playback finished, loop_enabled={_loop_enabled}, stop={_stop_requested}")  # Add debug
+            
+            # Check if we should continue looping
+            if not _loop_enabled or _stop_requested:
+                break
+                
+        except Exception as e:
+            print(f"Loop playback error: {e}")
+            import traceback
+            traceback.print_exc()
+            break
+    
+    print("DEBUG: Loop worker exiting")  # Add debug
+    # Cleanup
+    #_loop_enabled = False

pysoniq-0.1.0/pysoniq/pause.py

@@ -0,0 +1,95 @@
+"""Pause/resume playback"""
+
+import numpy as np
+import time
+
+# Module state
+_paused = False
+_pause_position = 0.0
+_pause_audio = None
+_pause_samplerate = None
+_pause_start_time = None
+_loop_was_enabled = False  # Track if loop was on when paused
+
+
+def pause():
+    """Pause current playback"""
+    global _paused, _pause_start_time, _pause_position, _loop_was_enabled
+    
+    if not _paused:
+        _paused = True
+        
+        # Save loop state before stopping
+        from . import loop as loop_module
+        _loop_was_enabled = loop_module.is_looping()
+        
+        # Estimate current position
+        if _pause_start_time is not None:
+            elapsed = time.time() - _pause_start_time
+            _pause_position += elapsed
+        
+        # Stop playback (this will disable loop)
+        from .stop import stop as stop_func
+        stop_func()
+        
+        print(f"Paused at {_pause_position:.2f}s (loop was {_loop_was_enabled})")
+
+
+def resume():
+    """Resume playback from pause point"""
+    global _paused, _pause_position, _pause_start_time, _loop_was_enabled
+    
+    if _paused and _pause_audio is not None:
+        _paused = False
+        
+        # Restore loop state
+        from . import loop as loop_module
+        if _loop_was_enabled:
+            loop_module.set_loop(True)
+        
+        # Calculate where to resume from
+        sample_position = int(_pause_position * _pause_samplerate)
+        
+        # Trim audio to resume point
+        if sample_position < len(_pause_audio):
+            remaining_audio = _pause_audio[sample_position:]
+            
+            # Play remaining audio
+            from . import play as play_module
+            _pause_start_time = time.time()
+            play_module.play(remaining_audio, _pause_samplerate)
+            
+            print(f"Resumed from {_pause_position:.2f}s (loop={_loop_was_enabled})")
+        else:
+            # Already at end
+            reset()
+
+
+def is_paused():
+    """Check if paused"""
+    return _paused
+
+
+def was_looping():
+    """Check if loop was enabled when paused"""
+    return _loop_was_enabled
+
+
+def set_playback_state(audio, samplerate):
+    """Store current playback state for pause/resume"""
+    global _pause_audio, _pause_samplerate, _pause_position, _pause_start_time
+    _pause_audio = audio.copy() if audio is not None else None
+    _pause_samplerate = samplerate
+    _pause_position = 0.0
+    _pause_start_time = time.time()
+
+
+def reset():
+    """Reset pause state"""
+    global _paused, _pause_position, _pause_audio, _pause_samplerate, _pause_start_time, _loop_was_enabled
+    _paused = False
+    _pause_position = 0.0
+    _pause_audio = None
+    _pause_samplerate = None
+    _pause_start_time = None
+    _loop_was_enabled = False

pysoniq-0.1.0/pysoniq/play.py

@@ -0,0 +1,221 @@
+"""Audio playback functionality"""
+
+import numpy as np
+import sys
+from pathlib import Path
+from .io import load
+from . import loop as loop_module
+from .utils import to_pcm, int32_to_24bit_bytes
+from . import pause as pause_module
+
+# Track current playback process for stopping
+_current_process = None
+
+def play(data, samplerate=None, blocking=False):
+    """
+    Play audio from file or array
+    
+    Args:
+        data: str/Path (audio file) or numpy array (audio data)
+        samplerate: int, required if data is array
+        blocking: bool, if True wait for playback to finish
+    """
+    # Reset stop flag when starting new playback
+    loop_module.reset_stop()
+    
+    # If string/Path, load file first
+    if isinstance(data, (str, Path)):
+        audio_array, sr = load(data)
+
+        # Store state for pause/resume
+        pause_module.set_playback_state(audio_array, sr)
+        
+        # If looping, start loop thread
+        if loop_module.is_looping():
+            loop_module.start_loop(audio_array, sr, _play_array)
+            return
+        
+        return _play_array(audio_array, sr, blocking)
+    
+    # Otherwise assume numpy array
+    if samplerate is None:
+        raise ValueError("samplerate required when playing numpy array")
+    
+    # Store state for pause/resume
+    pause_module.set_playback_state(data, samplerate)
+
+    # If looping, start loop thread
+    if loop_module.is_looping():
+        loop_module.start_loop(data, samplerate, _play_array)
+        return
+    
+    return _play_array(data, samplerate, blocking)
+
+
+def _play_array(data, samplerate, blocking):
+    """Internal: play numpy array"""
+    # Check if stopped
+    if loop_module.is_stopped():
+        return
+    # Apply main gain from gain module
+    from . import gain as gain_module
+    data = gain_module.adjust_gain_level(data)
+
+    # Determine channels
+    n_channels = 1 if data.ndim == 1 else data.shape[1]
+    
+    # Convert to mono if needed
+    if data.ndim > 1:
+        data = np.mean(data, axis=1)
+    
+    # Convert to PCM
+    sampwidth, data_int = to_pcm(data)
+    
+    # Platform-specific playback
+    if sys.platform == 'win32':
+        _play_windows(data_int, samplerate, sampwidth, n_channels, blocking)
+    elif sys.platform == 'darwin':
+        _play_macos(data_int, samplerate, sampwidth, n_channels, blocking)
+    else:  # Linux
+        _play_linux(data_int, samplerate, sampwidth, n_channels, blocking)
+
+
+def _play_windows(data, samplerate, sampwidth, n_channels, blocking):
+    """Windows playback using winsound"""
+    import winsound
+    import wave
+    import tempfile
+    import os
+    
+    if loop_module.is_stopped():
+        return
+    
+    with tempfile.NamedTemporaryFile(suffix='.wav', delete=False) as f:
+        temp_path = f.name
+        
+        with wave.open(temp_path, 'wb') as wav:
+            wav.setnchannels(n_channels)
+            wav.setsampwidth(sampwidth)
+            wav.setframerate(samplerate)
+            
+            if sampwidth == 3:
+                wav.writeframes(int32_to_24bit_bytes(data))
+            else:
+                wav.writeframes(data.tobytes())
+    
+    try:
+        flags = winsound.SND_FILENAME
+        if not blocking:
+            flags |= winsound.SND_ASYNC
+        
+        winsound.PlaySound(temp_path, flags)
+    finally:
+        if not blocking:
+            import threading
+            def cleanup():
+                import time
+                time.sleep(len(data) / samplerate + 0.5)
+                try:
+                    os.unlink(temp_path)
+                except:
+                    pass
+            threading.Thread(target=cleanup, daemon=True).start()
+        else:
+            try:
+                os.unlink(temp_path)
+            except:
+                pass
+
+
+def _play_macos(data, samplerate, sampwidth, n_channels, blocking):
+    """macOS playback using afplay"""
+    import subprocess
+    import wave
+    import tempfile
+    import os
+    
+    global _current_process
+    
+    with tempfile.NamedTemporaryFile(suffix='.wav', delete=False) as f:
+        temp_path = f.name
+        
+        with wave.open(temp_path, 'wb') as wav:
+            wav.setnchannels(n_channels)
+            wav.setsampwidth(sampwidth)
+            wav.setframerate(samplerate)
+            
+            if sampwidth == 3:
+                wav.writeframes(int32_to_24bit_bytes(data))
+            else:
+                wav.writeframes(data.tobytes())
+    
+    try:
+        if blocking:
+            _current_process = subprocess.Popen(['afplay', temp_path])
+            _current_process.wait()
+            _current_process = None
+            os.unlink(temp_path)
+        else:
+            _current_process = subprocess.Popen(['afplay', temp_path])
+            import threading
+            def cleanup():
+                import time
+                time.sleep(len(data) / samplerate + 0.5)
+                try:
+                    os.unlink(temp_path)
+                except:
+                    pass
+            threading.Thread(target=cleanup, daemon=True).start()
+    except Exception as e:
+        try:
+            os.unlink(temp_path)
+        except:
+            pass
+        raise e
+
+
+def _play_linux(data, samplerate, sampwidth, n_channels, blocking):
+    """Linux playback using aplay"""
+    import subprocess
+    import wave
+    import tempfile
+    import os
+    
+    global _current_process
+    
+    with tempfile.NamedTemporaryFile(suffix='.wav', delete=False) as f:
+        temp_path = f.name
+        
+        with wave.open(temp_path, 'wb') as wav:
+            wav.setnchannels(n_channels)
+            wav.setsampwidth(sampwidth)
+            wav.setframerate(samplerate)
+            
+            if sampwidth == 3:
+                wav.writeframes(int32_to_24bit_bytes(data))
+            else:
+                wav.writeframes(data.tobytes())
+    
+    try:
+        if blocking:
+            _current_process = subprocess.Popen(['aplay', temp_path])
+            _current_process.wait()
+            _current_process = None
+            os.unlink(temp_path)
+        else:
+            _current_process = subprocess.Popen(['aplay', temp_path])
+            import threading
+            def cleanup():
+                import time
+                time.sleep(len(data) / samplerate + 0.5)
+                try:
+                    os.unlink(temp_path)
+                except:
+                    pass
+            threading.Thread(target=cleanup, daemon=True).start()
+    except Exception as e:
+        try:
+            os.unlink(temp_path)
+        except:
+            pass
+        raise e

pysoniq-0.1.0/pysoniq/stop.py

@@ -0,0 +1,36 @@
+"""Stop playback functionality"""
+
+import sys
+from . import loop as loop_module
+
+
+def stop():
+    """Stop audio playback (preserves loop state)"""
+    # Stop playback but preserve loop setting
+    loop_module.stop()
+    
+    # Platform-specific immediate stop
+    if sys.platform == 'win32':
+        _stop_windows()
+    else:
+        _stop_unix()
+
+
+def _stop_windows():
+    """Stop Windows playback"""
+    try:
+        import winsound
+        winsound.PlaySound(None, winsound.SND_PURGE)
+    except:
+        pass
+
+
+def _stop_unix():
+    """Stop macOS/Linux playback"""
+    from . import play
+    if hasattr(play, '_current_process') and play._current_process:
+        try:
+            play._current_process.terminate()
+            play._current_process = None
+        except:
+            pass

pysoniq-0.1.0/pysoniq/utils.py

@@ -0,0 +1,93 @@
+"""Utility functions"""
+
+import numpy as np
+
+
+def to_pcm(data, target_bits=16):
+    """
+    Convert float audio to PCM with auto bit depth detection
+    
+    Args:
+        data: numpy array, float
+        target_bits: 8, 16, 24, or 32
+    
+    Returns:
+        sampwidth: bytes per sample
+        data_int: integer array
+    """
+    data_range = np.max(np.abs(data))
+    
+    if data_range <= 1.0:
+        # Normalized float - convert to PCM
+        data = np.clip(data, -1.0, 1.0)
+        
+        if target_bits == 8:
+            data_int = ((data + 1.0) * 127.5).astype(np.uint8)
+            sampwidth = 1
+        elif target_bits == 16:
+            data_int = (data * 32767).astype(np.int16)
+            sampwidth = 2
+        elif target_bits == 24:
+            data_int = (data * 8388607).astype(np.int32)
+            sampwidth = 3
+        elif target_bits == 32:
+            data_int = (data * 2147483647).astype(np.int32)
+            sampwidth = 4
+        else:
+            raise ValueError(f"Unsupported bit depth: {target_bits}")
+    else:
+        # Already integer - preserve
+        if data.dtype in [np.int16, np.uint8]:
+            sampwidth = 2 if data.dtype == np.int16 else 1
+            data_int = data.astype(np.int16) if data.dtype != np.int16 else data
+        elif data.dtype == np.int32:
+            sampwidth = 4
+            data_int = data
+        else:
+            # Unknown - normalize and convert
+            data_int = (np.clip(data, -1.0, 1.0) * 32767).astype(np.int16)
+            sampwidth = 2
+    
+    return sampwidth, data_int
+
+
+def to_int16(audio):
+    """
+    Convert float audio to 16-bit PCM
+    
+    Args:
+        audio: numpy array, float, -1 to 1
+    
+    Returns:
+        int16 array
+    """
+    audio = np.clip(audio, -1.0, 1.0)
+    return (audio * 32767).astype(np.int16)
+
+
+def int32_to_24bit_bytes(data_int32):
+    """Convert int32 array to 24-bit byte array"""
+    data_bytes = bytearray()
+    for sample in data_int32:
+        data_bytes.extend(sample.to_bytes(4, byteorder='little', signed=True)[:3])
+    return bytes(data_bytes)
+
+
+def normalize_audio(audio, target_level=-3.0):
+    """
+    Normalize audio to target dB level
+    
+    Args:
+        audio: numpy array
+        target_level: float, target dB level
+    
+    Returns:
+        normalized audio
+    """
+    rms = np.sqrt(np.mean(audio**2))
+    if rms > 0:
+        target_amplitude = 10**(target_level / 20.0)
+        audio = audio * (target_amplitude / rms)
+    return np.clip(audio, -1.0, 1.0)
+
+

pysoniq-0.1.0/pysoniq.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: pysoniq
+Version: 0.1.0
+Summary: Lightweight, pure-Python cross-platform audio playback library
+Author: laelume
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/laelume/pysoniq
+Project-URL: Repository, https://github.com/laelume/pysoniq
+Project-URL: Issues, https://github.com/laelume/pysoniq/issues
+Keywords: audio,sound,playback,music,cross-platform,pure-python,audio-playback,audio-player,sound-playback,wav
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Players
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.19.0
+Dynamic: license-file
+
+# pysoniq
+
+Minimal, pure-Python cross-platform audio playback library.
+
+- **Pure Python** - No compiled extensions
+- **Cross-platform** - Windows, macOS, Linux
+- **Minimal dependencies** - Only numpy
+- **Simple API** - Play, pause, stop, loop
+
+## Installation
+```bash
+pip install pysoniq
+```
+
+## Use in context
+```python
+import pysoniq as ps
+import numpy as np
+
+# Play WAV file
+ps.play('audio.wav')
+
+# Play as numpy array
+sr = 44100
+t = np.linspace(0, 1.0, sr)
+audio = 0.3 * np.sin(2 * np.pi * 440 * t)
+ps.play(audio, samplerate=sr)
+
+# Loop playback
+ps.set_loop(True)
+ps.play(audio, sr)
+
+# Stop
+ps.stop()
+```
+
+## Features
+
+**Playback**
+```python
+ps.play(data, samplerate)  # Play audio
+ps.stop()                   # Stop playback
+ps.pause()                  # Pause
+ps.resume()                 # Resume
+```
+
+**Looping**
+```python
+ps.set_loop(True)   # Enable loop
+ps.is_looping()     # Check status
+```
+
+**Gain Control**
+```python
+ps.set_gain(0.5)           # 50% volume
+ps.set_volume_db(-6.0)     # Set dB
+audio = ps.adjust_gain_level(audio, 1.5)
+```
+
+**Audio I/O**
+```python
+audio, sr = ps.load('file.wav')
+ps.save('output.wav', audio, sr)
+```
+
+## Platform Requirements
+
+- **Windows**: Built-in (winsound)
+- **macOS**: Built-in (afplay)
+- **Linux**: ALSA (aplay) - usually pre-installed
+
+## Limitations
+
+- WAV format only (for now)
+- Pause/resume uses time-based estimation
+- Gain changes apply on next loop iteration
+
+## License
+
+MIT
+
+## Author
+
+laelume

pysoniq-0.1.0/pysoniq.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+pysoniq/__init__.py
+pysoniq/gain.py
+pysoniq/io.py
+pysoniq/loop.py
+pysoniq/pause.py
+pysoniq/play.py
+pysoniq/stop.py
+pysoniq/utils.py
+pysoniq.egg-info/PKG-INFO
+pysoniq.egg-info/SOURCES.txt
+pysoniq.egg-info/dependency_links.txt
+pysoniq.egg-info/requires.txt
+pysoniq.egg-info/top_level.txt

pysoniq-0.1.0/pysoniq.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pysoniq-0.1.0/pysoniq.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=1.19.0

pysoniq-0.1.0/pysoniq.egg-info/top_level.txt

@@ -0,0 +1 @@
+pysoniq

pysoniq-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+