The Format class is used to control meta-data specific to one type of audio file (file format, encoding and endianness). It is mainly useful when writing files or reading raw (header-less) audio files. A Format instance can be queried for its related meta-data:
>>> from scikits.audiolab import Format
>>> a = Format() # By default, 16 bits PCM wav file
>>> print a # Will print a detail description of the format
Format(type=wav, encoding=pcm16, endianness=file) This class represents an audio file format. It knows about audio file format (wav, aiff, etc...), encoding (pcm, etc...) and endianness.
| Parameters: | type : str
encoding : str
endianness : str
|
|---|
See also
Notes
The possible values for type, and encoding depend on your installed libsndfile. You can query the possible values with the functions available_file_formats and available_encodings.
The following two functions can be used to query the available formats and encodings. The exact list of formats depend on the libsndfile audiolab was built against.
>>> from scikits.audiolab import available_encodings
>>> # List encodings supported for the wav format
>>> print available_encodings('wav')
Sndfile is the main class for audio file IO.
Sndfile(filename, mode=r, Format format=None, int channels=0, int samplerate=0) Sndfile is the core class to read/write audio files. Once an instance is created, it can be used to read and/or writes data from numpy arrays, query the audio file meta-data, etc...
| Parameters: | filename : string or int
mode : string
format : Format
channels : int
samplerate : int
|
|---|---|
| Returns: | sndfile: as Sndfile instance. : |
Notes
format, channels and samplerate need to be given only in the write modes and for raw files.
Methods
Sndfile.read_frames(self, scikits.audiolab.pysndfile.sndfile.sf_count_t nframes, dtype=<???>) Read the given number of frames and put the data into a numpy array of the requested dtype.
| Parameters: | nframes : int
dtype : numpy dtype
|
|---|
Notes
if float are requested when the file contains integer data, you will get normalized data (that is the max possible integer will be 1.0, and the minimal possible value -1.0).
if integers are requested when the file contains floating point data, it may give wrong results because there is an ambiguity: if the floating data are normalized, you can get a file with only 0 ! Getting integer data from files encoded in normalized floating point is not supported (this is an audiolab limitation: sndfile supports it).
Sndfile.write_frames(self, ndarray input) write given number frames into file.
| Parameters: | input : ndarray
|
|---|
Notes
One column per channel.
updates the write pointer.
if the input type is float, and the file encoding is an integer type, you should make sure the input data are normalized normalized data (that is in the range [-1..1] - which will corresponds to the maximum range allowed by the integer bitwidth).
Sndfile.sync(self) call the operating system’s function to force the writing of all file cache buffers to disk the file.
No effect if file is open as read
The most common encoding for common audio files like wav of aiff is signed 16 bits integers. Sndfile and hence audiolab enables many more encodings like unsigned 8 bits, floating point. Generally, when using the data for processing, the encoding of choice is floating point; the exact type is controlled through the array dtype. When the array dtype and the file encoding don’t match, there has to be some conversion.
When converting between integer PCM formats of differing size (i.e. both file encoding and input/output array dtype is an integer type), the Sndfile class obeys one simple rule:
- Whenever integer data is moved from one sized container to another sized container, the most significant bit in the source container will become the most significant bit in the destination container.
When either the encoding is an integer but the numpy array dtype is a float type, different rules apply. The default behavior when reading floating point data (array dtype is float) from a file with integer data is normalization. Regardless of whether data in the file is 8, 16, 24 or 32 bit wide, the data will be read as floating point data in the range [-1.0, 1.0]. Similarly, data in the range [-1.0, 1.0] will be written to an integer PCM file so that a data value of 1.0 will be the largest allowable integer for the given bit width.
audiolab now has some facilities to output sound from numpy arrays: the function play is a wrapper around a platform-specific audio backend. For now, only ALSA backend (Linux) and Core Audio backend (Mac OS X) are implemented. Other backends (for windows, OSS for Solaris/BSD) may be added later, although it is not a priority for me. Patches are welcomed, particularly for windows.
Play the signal in vector input to the default output device.
Only floating point input are supported: input is assumed to be in the -1..1 range. Any values outside this range will be clipped by the device.
| Parameters: | input: array :
fs: int :
|
|---|
Notes
It will fail if the sampling rate is not supported by your device. In particular, no automatic resampling is done. Mono signals are doubled for fake stereo for the CoreAudio framework, as it seemse CoreAudio does not handle mono on its own.