PySoundIo¶
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
List the available input and output devices on the system and their properties.
python devices.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
Plays a wav file through the speakers. Supports specifying backend, device, block size.
python play.py in.wav --device 0
Plays a sine wave through the speakers. Supports specifying backend, device, sample rate, block size.
python sine.py --freq 442
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