Table Of Contents

Previous topic

Download and installation

Next topic

Full API

This Page


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.

Sndfile class

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


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 ""

Sound output

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))