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 sounddeviceVerified import paths — ran on the pinned version, not inferred.
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.
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`.
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.
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.
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.
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.
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.
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()`.
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.