PySoundIo

https://github.com/joextodd/pysoundio/workflows/tests/badge.svg https://coveralls.io/repos/github/joextodd/pysoundio/badge.svg https://readthedocs.org/projects/pysoundio/badge/?version=latest

A simple Pythonic interface for libsoundio.

libsoundio is a robust, cross-platform solution for real-time audio. It performs no buffering or processing on your behalf, instead exposing the raw power of the underlying backend.

Installation

You can use pip to download and install the latest release with a single command.

pip3 install pysoundio

Examples

See examples directory.

Some of the examples require PySoundFile

pip3 install soundfile

On Windows and OS X, this will also install the library libsndfile. On Linux you will need to install the library as well.

  • Ubuntu / Debian

    apt-get install libsndfile1
    

devices.py

List the available input and output devices on the system and their properties.

python devices.py

record.py

Records data from microphone and saves to a wav file. Supports specifying backend, device, sample rate, block size.

python record.py out.wav --device 0 --rate 44100

play.py

Plays a wav file through the speakers. Supports specifying backend, device, block size.

python play.py in.wav --device 0

sine.py

Plays a sine wave through the speakers. Supports specifying backend, device, sample rate, block size.

python sine.py --freq 442

Testing

To run the test suite.

tox -r

Advanced

If you wish to use your own build of libsoundio (perhaps you want Jack enabled) then build from source and install it globally and reinstall pysoundio.

Note: PySoundIo only works with libsoundio versions >= 1.1.0

Contributing

If you find any bugs or other things that need improvement, please create an issue or a pull request at https://github.com/joextodd/pysoundio/. Contributions are always welcome!

You should get the latest version from GitHub:

git clone https://github.com/joextodd/pysoundio.git
cd pysoundio

To install the package for development, first build the library

python3 pysoundio/builder/soundio.py

and then install with pip.

pip3 install .

Before submitting a pull request, make sure all tests are passing, and all of the example scripts run as they as should.

If you make changes to the documentation, you can locally re-create the HTML pages using Sphinx. You can install it and the read the docs theme with:

pip3 install -r docs/requirements.txt

To create the HTML pages, use:

python3 setup.py build_sphinx

The generated files will be available in the directory docs/_build/html.

Backends

Value Backend Description
pysoundio.SoundIoBackendJack JACK Audio
pysoundio.SoundIoBackendPulseAudio Pulse Audio
pysoundio.SoundIoBackendAlsa ALSA Audio
pysoundio.SoundIoBackendCoreAudio Core Audio
pysoundio.SoundIoBackendWasapi WASAPI Audio
pysoundio.SoundIoBackendDummy Dummy backend

Formats

Value Format Description
pysoundio.SoundIoFormatS8 Signed 8 bit
pysoundio.SoundIoFormatU8 Unsigned 8 bit
pysoundio.SoundIoFormatS16LE Signed 16 bit Little Endian
pysoundio.SoundIoFormatS16BE Signed 16 bit Big Endian
pysoundio.SoundIoFormatU16LE Unsigned 16 bit Little Endian
pysoundio.SoundIoFormatU16BE Unsigned 16 bit Little Endian
pysoundio.SoundIoFormatS24LE Signed 24 bit Little Endian using low three bytes in 32-bit word
pysoundio.SoundIoFormatS24BE Signed 24 bit Big Endian using low three bytes in 32-bit word
pysoundio.SoundIoFormatU24LE Unsigned 24 bit Little Endian using low three bytes in 32-bit word
pysoundio.SoundIoFormatU24BE Unsigned 24 bit Big Endian using low three bytes in 32-bit word
pysoundio.SoundIoFormatS32LE Signed 32 bit Little Endian
pysoundio.SoundIoFormatS32BE Signed 32 bit Big Endian
pysoundio.SoundIoFormatU32LE Unsigned 32 bit Little Endian
pysoundio.SoundIoFormatU32BE Unsigned 32 bit Big Endian
pysoundio.SoundIoFormatFloat32LE Float 32 bit Little Endian, Range -1.0 to 1.0
pysoundio.SoundIoFormatFloat32BE Float 32 bit Big Endian, Range -1.0 to 1.0
pysoundio.SoundIoFormatFloat64LE Float 64 bit Little Endian, Range -1.0 to 1.0
pysoundio.SoundIoFormatFloat64BE Float 64 bit Big Endian, Range -1.0 to 1.0

API Reference

Changelog

v2.0.0

  • Updated to use CFFI
  • Improved performance
  • Bundled in libraries for macOS, Linux, Windows and Raspbian
  • Fixes issue where multiple instances cause a crash
  • Added command line scripts for examples

v1.1.0

  • Added support for libsoundio v2.0.0
  • Added support for Windows (thanks @cameronmaske)
  • Fixes for malloc errors

v1.0.0

  • Initial release

Index