{"id":1716,"library":"sounddevice","title":"Sounddevice","description":"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.","status":"active","version":"0.5.5","language":"en","source_language":"en","source_url":"https://github.com/spatialaudio/python-sounddevice/","tags":["audio","sound","playback","recording","portaudio","microphone","speaker"],"install":[{"cmd":"pip install sounddevice","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Used for Python bindings to the PortAudio C library.","package":"cffi"}],"imports":[{"symbol":"sounddevice","correct":"import sounddevice as sd"}],"quickstart":{"code":"import sounddevice as sd\nimport numpy as np\nimport time\n\nsamplerate = 44100  # samples per second\nduration = 2.5      # seconds\nfrequency = 440     # Hz (A4 note)\n\n# Generate a sine wave\nt = np.linspace(0., duration, int(samplerate * duration), endpoint=False)\namplitude = 0.5 # To avoid clipping\ndata = amplitude * np.sin(2 * np.pi * frequency * t)\n\n# Ensure data is float32, as recommended by sounddevice\ndata = data.astype(np.float32)\n\nprint(f\"Playing a {frequency} Hz sine wave for {duration} seconds...\")\nsd.play(data, samplerate)\nsd.wait() # Wait until playback is finished\nprint(\"Playback finished.\")\n\n# Example of recording (e.g., 2 seconds of stereo audio)\nprint(\"Recording 2 seconds of stereo audio...\")\nrecording = sd.rec(int(2 * samplerate), samplerate=samplerate, channels=2, dtype='float32')\nsd.wait() # Wait until recording is finished\nprint(\"Recording finished.\")\nprint(f\"Recorded data shape: {recording.shape}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.4.5"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}