For simple usage, the matlab-like API is the simplest to use. For example, if you want to read a wav file, you can do it in one function call
from audiolab import wavread
data, fs, enc = wavread('test.wav')
This read the file test.wav, and returns the data, sampling rate as well as the encoding as a string. Similar function exists for writing, and for other formats: wav, aiff, au, ircam, ogg and flac formats are supported through this simple API.
For more control (for example writing with a non default encoding, controlling output array dtype), the Sndfile class should be used. Internally, the simple functions are just wrappers around this class. Let’s see a simple example on how to use the Sndfile class for reading:
import numpy as np
from scikits.audiolab import Sndfile
f = Sndfile('test.wav', 'r')
# Sndfile instances can be queried for the audio file meta-data
fs = f.samplerate
nc = f.channels
enc = f.encoding
# Reading is straightfoward
data = f.read_frames(1000)
# This reads the next 1000 frames, e.g. from 1000 to 2000, but as single precision
data_float = f.read_frames(1000, dtype=np.float32)
As you can see the usage for reading is straightforward. A Sndfile instance first created, and the instance is used for reading, as well as for querying meta-data about the file, like the sampling rate or the number of channels.
The read_frames method can optionally take a dtype argument like many numpy functions, to select the dtype of the output array. The exact semantics are more complicated than with numpy though, because of audio encoding specifies (see encoding section).
Writing audio file from data in numpy arrays is a bit more complicated, because you need to tell the Sndfile class about the file type, encoding and endianness, as well as the sampling rate and number of channels. For simplicity, the file format, encoding and endianness is controlled from an helper class, Format:
import numpy as np
from scikits.audiolab import Format, Sndfile
filename = 'foo.wav'
# Create some data to save as audio data: one second of stereo white noise
data = np.random.randn(48000, 2)
# Create a Sndfile instance for writing wav files @ 48000 Hz
format = Format('wav')
f = Sndfile(filename, 'w', format, 2, 48000)
# Write the first 500 frames of the signal. Note that the write_frames method
# uses tmp's numpy dtype to determine how to write to the file; sndfile also
# converts the data on the fly if necessary
f.write_frames(data[:500])
f.close()
The Format class can be used to control more precisely the encoding or the endianness of the written file:
from scikits.audiolab import Format, Sndfile
# Use 24 bits encoding, big endian
format = Format('wav', 'pcm24', 'big')
f = Sndfile('foo.wav', 'w', format, 2, 48000)
Not all file formats and encodings combinations are possible. Also, the exact number of file formats and encodings available depend on your version of libsndfile. Both can be queried at runtime with the functions available_file_formats and available_encodings. The following example print all available file formats and encodings (the output depends on your installed libsndfile):
from scikits.audiolab import available_file_formats, available_encodings
for format in available_file_formats():
print "File format %s is supported; available encodings are:" % format
for enc in available_encodings(format):
print "\t%s" % enc
print ""
audiolab now has some facilities to output sound from numpy arrays:
import numpy as np
from scikits.audiolab import play
# output one second of stereo gaussian white noise at 48000 hz
play(0.05 * np.random.randn(2, 48000))