or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdconvenience-functions.mddevice-management.mdindex.mdstream-processing.mdutilities.md
tile.json

tessl/pypi-sounddevice

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/sounddevice@0.5.x

To install, run

npx @tessl/cli install tessl/pypi-sounddevice@0.5.0

index.mddocs/

sounddevice

Python bindings for the PortAudio library, providing cross-platform audio input and output functionality. The library enables playing and recording NumPy arrays containing audio signals, with support for real-time streaming, callback-based processing, and integration with scientific computing workflows.

Package Information

  • Package Name: sounddevice
  • Language: Python
  • Installation: pip install sounddevice

Core Imports

import sounddevice as sd

Alternative imports:

import sounddevice
from sounddevice import play, rec, query_devices

Basic Usage

import sounddevice as sd
import numpy as np

# Record audio for 5 seconds
duration = 5.0  # seconds
samplerate = 44100  # Hz
recording = sd.rec(int(duration * samplerate), samplerate=samplerate, channels=2)
sd.wait()  # Wait until recording is finished
print("Recording complete!")

# Play the recorded audio
sd.play(recording, samplerate=samplerate)
sd.wait()  # Wait until playback is finished

# Query available audio devices
devices = sd.query_devices()
print(devices)

# Set default device and parameters
sd.default.device = 'USB Audio Device'
sd.default.samplerate = 48000
sd.default.channels = 2

Architecture

sounddevice provides multiple levels of abstraction for audio processing:

  • Convenience Functions: High-level functions for simple audio operations (play(), rec(), playrec())
  • Stream Classes: Low-level stream objects for advanced control and real-time processing
  • Raw Streams: Buffer-based streams when NumPy is not available
  • Device Management: Functions to query and configure audio hardware
  • Platform Integration: OS-specific settings classes for optimal performance

Capabilities

Convenience Functions

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.

def play(data, samplerate=None, mapping=None, blocking=False, loop=False, **kwargs): ...
def rec(frames=None, samplerate=None, channels=None, dtype=None, out=None, mapping=None, blocking=False, **kwargs): ...  
def playrec(data, samplerate=None, channels=None, dtype=None, out=None, input_mapping=None, output_mapping=None, blocking=False, **kwargs): ...
def wait(ignore_errors=True): ...
def stop(ignore_errors=True): ...
def get_status(): ...
def get_stream(): ...

Convenience Functions

Device Management

Functions to discover, query, and validate audio devices and host APIs. Essential for configuring audio hardware and ensuring compatibility across different systems.

def query_devices(device=None, kind=None): ...
def query_hostapis(index=None): ...
def check_input_settings(device=None, channels=None, dtype=None, extra_settings=None, samplerate=None): ...
def check_output_settings(device=None, channels=None, dtype=None, extra_settings=None, samplerate=None): ...

Device Management

Stream Processing

Low-level stream classes for advanced audio processing with full control over buffering, callbacks, and real-time operation. Supports both NumPy arrays and raw Python buffers.

class Stream: ...
class InputStream: ...
class OutputStream: ...
class RawStream: ...
class RawInputStream: ...
class RawOutputStream: ...

Stream Processing

Configuration and Settings

Module-wide defaults and platform-specific audio settings for optimal performance on different operating systems.

class default: ...
class AsioSettings: ...
class CoreAudioSettings: ...
class WasapiSettings: ...

Configuration and Settings

Utilities and Error Handling

Utility functions and exception classes for audio processing workflows and error management.

def sleep(msec): ...
def get_portaudio_version(): ...

class PortAudioError(Exception): ...
class CallbackStop(Exception): ...
class CallbackAbort(Exception): ...

Utilities and Error Handling

Types

class DeviceList(tuple):
    """Special tuple subclass containing device information."""
    
class CallbackFlags:
    """Status flags for stream callback functions."""
    input_underflow: bool
    input_overflow: bool
    output_underflow: bool
    output_overflow: bool
    priming_output: bool

class PortAudioError(Exception):
    """Exception raised for PortAudio-related errors."""

class CallbackStop(Exception):
    """Exception to signal stream callback should stop gracefully."""

class CallbackAbort(Exception):
    """Exception to signal stream callback should abort immediately."""

Module Attributes

__version__: str  # Module version string (e.g., '0.5.2')