Registry / data / sounddevice

sounddevice

JSON →
library0.5.6pypypi✓ verified 25d ago

Sounddevice is a Python library that provides a high-level API to play and record sound, built upon the PortAudio library. It allows for easy integration with NumPy for handling audio data. The current version is 0.5.5, and it maintains a relatively active release cadence with frequent patch and minor updates.

pip install sounddevice
INSTALL
IMPORT
SIG · SOUNDDEVICE
S
sounddevice
datapythonv0.5.6
Install
1.9s avg
Import
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.9s · import 0.000s · 20MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

sounddevice
import sounddevice as sd

This quickstart demonstrates playing a sine wave and then recording 2 seconds of stereo audio. It highlights the use of `numpy` for audio data generation and processing, and the `sd.play()` and `sd.rec()` functions with `sd.wait()` for blocking execution until audio operations complete.

import sounddevice as sd import numpy as np import time samplerate = 44100 # samples per second duration = 2.5 # seconds frequency = 440 # Hz (A4 note) # Generate a sine wave t = np.linspace(0., duration, int(samplerate * duration), endpoint=False) amplitude = 0.5 # To avoid clipping data = amplitude * np.sin(2 * np.pi * frequency * t) # Ensure data is float32, as recommended by sounddevice data = data.astype(np.float32) print(f"Playing a {frequency} Hz sine wave for {duration} seconds...") sd.play(data, samplerate) sd.wait() # Wait until playback is finished print("Playback finished.") # Example of recording (e.g., 2 seconds of stereo audio) print("Recording 2 seconds of stereo audio...") recording = sd.rec(int(2 * samplerate), samplerate=samplerate, channels=2, dtype='float32') sd.wait() # Wait until recording is finished print("Recording finished.") print(f"Recorded data shape: {recording.shape}")
Debug
Known issues
gotchaThe `sounddevice` library requires the system-level PortAudio library, which is not automatically installed by `pip`. Missing PortAudio often leads to `PortAudioError` during runtime or installation failures.
fix
Install PortAudio via your system's package manager (e.g., `apt install portaudio19-dev` on Debian/Ubuntu, `brew install portaudio` on macOS) or download pre-compiled binaries on Windows before installing `sounddevice`.
affects: All versions
breakingBeginning with version 0.5.0, ASIO support was removed from the bundled Windows DLLs. Users requiring ASIO on Windows must now explicitly enable it by setting the `SD_ENABLE_ASIO` environment variable and ensure an ASIO-enabled PortAudio DLL is available.
fix
Set `SD_ENABLE_ASIO=1` and ensure an ASIO-enabled `portaudio_x64.dll` (or similar) is accessible on your PATH or specified. If this is not feasible, consider pinning to `sounddevice<0.5.0` for the old behavior.
affects: >=0.5.0
gotchaWhen using `sd.play()` or `sd.rec()` in a non-blocking context (e.g., a script that immediately exits), the audio playback/recording might stop prematurely. These functions initiate the audio stream but don't wait for completion by default.
fix
Call `sd.wait()` after `sd.play()` or `sd.rec()` to block until the audio stream finishes. For continuous or advanced control, consider using `sd.Stream` objects.
affects: All versions
gotchaAudio data passed to `sounddevice` (especially NumPy arrays) must have an appropriate `dtype` (e.g., `float32`, `int16`). Incorrect data types can lead to `ValueError` or distorted audio during playback or recording.
fix
Ensure NumPy arrays are created with a compatible `dtype`, for example: `np.random.uniform(-1, 1, size=(samplerate, 2), dtype='float32')` for float audio. Use `sd.default.dtype` to check the default input/output types.
affects: All versions
breakingSince version 0.4.5, `sounddevice` requires Python 3.7 or newer. Older Python versions are no longer supported and will lead to installation errors or `Requires-Python` conflicts during `pip` installation.
fix
Upgrade your Python environment to 3.7 or higher. If unable to upgrade, use `pip install 'sounddevice<0.4.5'` to install a compatible older version.
affects: >=0.4.5
Errors
Common errors & fixes
OSError: No PortAudio library found.
The Python `sounddevice` package requires the PortAudio C library to be installed system-wide, which is not automatically included with the Python package.
fix
Install PortAudio using your system's package manager: e.g., `brew install portaudio` on macOS, `sudo apt-get install portaudio19-dev` on Debian/Ubuntu, `pacman -S portaudio` on Arch Linux, or via MSYS2 for Windows.
RuntimeError: No default input device available
The operating system does not have a recognized default audio input (or output) device configured, or `sounddevice` cannot access it.
fix
Identify available devices with `sd.query_devices()` and explicitly select one by passing its index (e.g., `device=1`) to functions like `sd.rec()` or `sd.play()`.
sounddevice.PortAudioError: Error opening PA stream: Unanticipated host error (-9986)
On macOS, the application (e.g., terminal, IDE) running the Python script lacks permission to access the microphone.
fix
On macOS, go to System Settings > Privacy & Security > Microphone and grant permission to the terminal application or IDE from which you are running the Python script.
Upgrade
Version history
0.5.6latest on PyPI · released Aug 17, 2026
Audit
Dependencies
cffirequiredUsed for Python bindings to the PortAudio C library.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources
sounddevice — pip install sounddevice · libregistry