tessl/pypi-sounddevice

Python bindings for PortAudio library providing cross-platform audio I/O functionality with NumPy integration.

—

Pending

Overview

Eval results

Files

Convenience Functions

Name: tessl/pypi-sounddevice
Author: tessl

High-level functions for simple audio playback, recording, and simultaneous operations. These functions provide the easiest way to work with audio data using NumPy arrays, handling most of the complexity internally while offering essential control parameters.

Capabilities

Audio Playback

Play back NumPy arrays containing audio data with support for non-blocking operation, looping, and custom device mapping.

def play(data, samplerate=None, mapping=None, blocking=False, loop=False, **kwargs):
    """
    Play back NumPy array containing audio data.
    
    Parameters:
    - data (array_like): Audio data to play back
    - samplerate (float, optional): Sample rate in Hz  
    - mapping (array_like, optional): Channel mapping to output devices
    - blocking (bool): If True, wait until playback is finished
    - loop (bool): If True, loop the audio indefinitely
    - **kwargs: Additional parameters for stream creation
    
    Returns:
    None
    """

Audio Recording

Record audio input into NumPy arrays with configurable duration, sample rate, channels, and data type.

def rec(frames=None, samplerate=None, channels=None, dtype=None, out=None, mapping=None, blocking=False, **kwargs):
    """
    Record audio into NumPy array.
    
    Parameters:
    - frames (int, optional): Number of frames to record
    - samplerate (float, optional): Sample rate in Hz
    - channels (int or array_like, optional): Number of input channels
    - dtype (str or numpy.dtype, optional): Data type of output array
    - out (numpy.ndarray, optional): Output array to write data into
    - mapping (array_like, optional): Channel mapping from input devices  
    - blocking (bool): If True, wait until recording is finished (default: False)
    - **kwargs: Additional parameters for stream creation
    
    Returns:
    numpy.ndarray: Recorded audio data
    """

Simultaneous Playback and Recording

Perform simultaneous audio playback and recording, useful for real-time audio processing applications and system response measurements.

def playrec(data, samplerate=None, channels=None, dtype=None, out=None, input_mapping=None, output_mapping=None, blocking=False, **kwargs):
    """
    Simultaneous playback and recording.
    
    Parameters:
    - data (array_like): Audio data to play back
    - samplerate (float, optional): Sample rate in Hz
    - channels (int, optional): Number of input channels for recording
    - dtype (str or numpy.dtype, optional): Data type of recorded output array
    - out (numpy.ndarray, optional): Output array to write recorded data into
    - input_mapping (array_like, optional): Channel mapping for input devices
    - output_mapping (array_like, optional): Channel mapping for output devices
    - blocking (bool): If True, wait until operation is finished (default: False)
    - **kwargs: Additional parameters for stream creation
    
    Returns:
    numpy.ndarray or type(out): Recorded audio data
    """

Operation Control

Control and monitor current audio operations with functions to wait for completion, stop operations, and check status.

def wait(ignore_errors=True):
    """
    Wait for current audio operation to complete.
    
    Parameters:
    - ignore_errors (bool): If True, ignore PortAudio errors
    
    Returns:
    CallbackFlags or None: Status information about buffer over-/underruns, or None
    """

def stop(ignore_errors=True):
    """
    Stop current audio operation.
    
    Parameters:
    - ignore_errors (bool): If True, ignore PortAudio errors
    
    Returns:
    None
    """

def get_status():
    """
    Get current playback/recording status.
    
    Returns:
    CallbackFlags: Object containing status flags for current operation
    """

def get_stream():
    """
    Get currently active stream object.
    
    Returns:
    Stream, InputStream, or OutputStream: Current active stream object
    """

Usage Examples

Basic Recording and Playback

import sounddevice as sd
import numpy as np

# Record 3 seconds of audio
duration = 3.0
samplerate = 44100
print("Recording...")
recording = sd.rec(int(duration * samplerate), samplerate=samplerate, channels=1)
sd.wait()  # Wait until recording is finished
print("Recording complete!")

# Play back the recorded audio
print("Playing back...")
sd.play(recording, samplerate=samplerate)
sd.wait()  # Wait until playback is finished
print("Playback complete!")

Non-blocking Operations

import sounddevice as sd
import numpy as np
import time

# Start non-blocking playback
duration = 5.0
samplerate = 44100
t = np.linspace(0, duration, int(samplerate * duration))
audio = 0.5 * np.sin(2 * np.pi * 440 * t)  # 440 Hz sine wave

sd.play(audio, samplerate=samplerate, blocking=False)
print("Audio started playing...")

# Do other work while audio plays
for i in range(5):
    time.sleep(1)
    status = sd.get_status()
    print(f"Status: {status}")

sd.wait()  # Wait for completion
print("Playback finished!")

Simultaneous Playback and Recording

import sounddevice as sd
import numpy as np

# Generate test signal
duration = 2.0
samplerate = 48000
frequency = 1000  # 1 kHz
t = np.linspace(0, duration, int(samplerate * duration))
test_signal = 0.5 * np.sin(2 * np.pi * frequency * t)

# Play test signal and record system response
print("Playing test signal and recording...")
recorded = sd.playrec(test_signal, samplerate=samplerate, channels=1)
sd.wait()
print("Operation complete!")

# Now 'recorded' contains the system's response to the test signal
print(f"Recorded {len(recorded)} samples")

Install with Tessl CLI