Sounddevice

Warnings

• gotcha The `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`.
• breaking Beginning 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.
• gotcha When 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.
• gotcha Audio 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.
• breaking Since 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.

Install

• pip install sounddevice Install stable release

Imports

• sounddevice

  import sounddevice as sd

Quickstart

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}")