sounddevice

The sounddevice module provides three primary classes for handling audio data via streams: Stream, InputStream, and OutputStream. These classes are designed to work seamlessly with NumPy arrays for high-performance audio processing.

• Stream: A general-purpose class for simultaneous input and output.
• InputStream: Specifically for recording audio from an input device.
• OutputStream: Specifically for playing audio through an output device.

When using these streams, audio data is typically passed to or received from callbacks as NumPy arrays, allowing for efficient manipulation of audio buffers.

The sounddevice module provides specialized settings classes to configure low-level audio drivers on different operating systems. Use these classes to fine-tune audio behavior when using specific backend APIs:

• ASIO: For high-performance audio on Windows.
• CoreAudio: For macOS audio.
• WASAPI: For Windows Audio Session API.

These settings are typically passed to functions that interact with the audio device to ensure optimal performance or specific driver-level configurations.

When working with stream callbacks, you can use specific exceptions to control the lifecycle of the stream:

• CallbackStop: Raising this exception inside a callback tells the stream to stop gracefully.
• CallbackAbort: Raising this exception tells the stream to stop immediately (aborting the current processing).

The sounddevice module provides RawStream classes for low-level, high-performance audio input and output. Unlike standard streams that might handle data conversion, raw streams allow you to interact directly with the audio buffer.

Key classes include:

• RawStream: The base class for raw audio streams.
• RawInputStream: Used for capturing raw audio data from an input device.
• RawOutputStream: Used for sending raw audio data to an output device.

For continuous recording, real-time processing, or low-latency requirements, use the lower-level Stream classes (e.g., Stream, InputStream, OutputStream, RawStream) with a callback function.

Convenience functions like play() and rec() are intended for simple scripts, whereas Stream provides a non-blocking interface where a callback is invoked whenever audio data is available.

RawStream can be used if you do not want to depend on NumPy.

import sounddevice as sd
duration = 5.5

# Non-blocking callback stream
def callback(indata, outdata, frames, time, status):
    if status:
        print(status)
    outdata[:] = indata

with sd.Stream(channels=2, callback=callback):
    sd.sleep(int(duration * 1000))

# Using RawStream (no NumPy required)
with sd.RawStream(channels=2, dtype='int24', callback=callback):
    sd.sleep(int(duration * 1000))

If you use conda or mamba, you can install sounddevice from the conda-forge channel.

Note: The PortAudio package provided by conda-forge does not have ASIO support.

conda install -c conda-forge python-sounddevice

To install the latest development version (master branch) from GitHub instead of the PyPI release, follow these steps:

1. Clone the repository recursively to ensure submodules are included:

   git clone --recursive https://github.com/spatialaudio/python-sounddevice.git
   cd python-sounddevice

2. Install the package in editable mode:

   python -m pip install -e .

3. Run the build script:

   python sounddevice_build.py

Note: If you did not use the --recursive flag during cloning, you must manually initialize submodules using git submodule update --init. If the sounddevice_build.py file is modified (via pull, branch switch, or manual edit), you must run it again.

Install the sounddevice module using pip. It is recommended to use a virtual environment (e.g., via venv or conda) before installation.

On macOS and Windows, pip will automatically install the required PortAudio library. On other platforms, you may need to install PortAudio manually using your system's package manager (e.g., libportaudio2).

Note: If you install PortAudio via a package manager or conda, it will likely override the version installed by pip.

python -m pip install sounddevice

If you are contributing to the documentation, you can build the HTML pages locally using Sphinx.

1. Install documentation dependencies:

   python -m pip install -e . --group doc

2. Build the HTML files:

   python -m sphinx doc _build

   The output will be located in the _build/ directory.
3. Auto-reload documentation (requires sphinx-autobuild): To automatically re-build and reload the browser whenever you make changes, use:

   python -m sphinx_autobuild doc _build --open-browser