Platform independent interfacing of numpy arrays of floats with audio files and devices.
The AudioIO modules try to use whatever audio packages are installed on your system to achieve their tasks. AudioIO itself does not provide own code for decoding files and accessing audio hardware.
- Audio data are always numpy arrays of floats (
np.float64) with values ranging between -1 and 1 ...
- ... independent of how the data are stored in an audio file.
load_audio()function for loading a whole audio file.
- Blockwise random-access loading of large audio files (
blocks()generator for iterating over blocks of data with optional overlap.
write_audio()function for writing data to an audio file.
- Platform independent playback of numpy arrays (
- Synchronous (blocking) and asynchronous (non blocking) playback.
- Automatic resampling of data for playback to match supported sampling rates.
- Detailed and platform specific installation instructions (pip, conda, Debian and RPM based Linux packages, homebrew for MacOS) for all supported audio packages.
Simply run (as superuser):
pip install audioio
Then you can use already installed audio packages for reading and writing audio files and for playing audio data. However, audio file formats supported by the python standard library are limited to basic wave files and playback capabilities are poor. If you need support for additional audio file formats or proper sound output, you need to install additional packages.
See installation for further instructions and recommendations on additional audio packages.
See API Reference for detailed information.
import audioio as aio
Loading audio data
Load an audio file into a numpy array:
data, samplingrate = aio.load_audio('audio/file.wav')
The read in data are always numpy arrays of floats ranging between -1 and 1. The arrays are always 2-D arrays with first axis time and second axis channel, even for single channel data.
Plot the first channel:
import numpy as np import matplotlib.pyplot as plt time = np.arange(len(data))/samplingrate plt.plot(time, data[:,0]) plt.show()
You can also randomly access chunks of data of an audio file, without loading the entire file into memory. This is really handy for analysing very long sound recordings:
# open audio file with a buffer holding 60 seconds of data: with aio.open_audio_loader('audio/file.wav', 60.0) as data: block = 1000 rate = data.samplerate for i in range(len(data)//block): x = data[i*block:(i+1)*block] # ... do something with x and rate
Even simpler, iterate in blocks over the file with overlap:
from scipy.signal import spectrogram nfft = 2048 with aio.AudioLoader('some/audio.wav') as data: for x in data.blocks(100*nfft, nfft//2): f, t, Sxx = spectrogram(x, nperseg=nfft, noverlap=nfft//2)
See API documentation of the audioloader module for details.
Writing audio data
Write a 1-D or 2-D numpy array into an audio file (data values between -1 and 1):
aio.write_audio('audio/file.wav', data, samplerate)
Again, in 2-D arrays the first axis (rows) is time and the second axis the channel (columns).
See API documentation of the audiowriter module for details.
Converting audio files
AudioIO provides a simple command line script to convert audio files:
> audioconverter -e float -o test.wav test.mp3
See API documentation of the audioconverter module for details.
Fade in and out and play a 1-D or 2-D numpy array as a sound (first axis is time and second axis the channel):
aio.fade(data, samplingrate, 0.2) aio.play(data, samplingrate)
Beep for half a second and 440 Hz:
aio.beep(0.5, 440.0) aio.beep(0.5, 'a4')
Musical notes are translated into frequency with the
See API documentation of the playaudio module for details.
Managing audio modules
Simply run in your terminal
to see which audio modules you have already installed on your system, which ones are recommended to install, and how to install them.
See API documentation of the audiomodules module for details.
All the audio modules AudioIO is using.
Reading and writing audio files:
- wave: simple wave file interface of the python standard library.
- ewave: extended wave files.
- scipy.io.wavfile: simple scipy wave file interface.
- SoundFile: support of many open source audio file formats via libsndfile.
- wavefile: support of many open source audio file formats via libsndfile.
- audioread: mpeg file support.
- Pydub: mpeg support for reading and writing, playback via simlpeaudio or pyaudio.
- scikits.audiolab: seems to be no longer active.
- sounddevice: wrapper for portaudio.
- PyAudio: wrapper for portaudio.
- simpleaudio: uses ALSA on Linux, runs well on windows.
- ossaudiodev: playback via the outdated OSS interface of the python standard library.
- winsound: native windows audio playback of the python standard library, asynchronous playback only with wave files.
- SoundCard: Uses native audio libraries.
Related audio software: