Full API — audiolab v0.10.2 documentation

### Navigation

- index
- next |
- previous |
- audiolab v0.10.2 documentation »

# Full API

## Audio file IO

### The `Format` class

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

class `scikits.audiolab.` `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 the major file format (wav, etc...). encoding : str the encoding (pcm16, etc..). endianness : str the endianess.

  See also

  `Sndfile`

  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.

`Format.` `file_format`
  Returns the file format.

`Sndfile.` `file_format_description`
  Returns the full description of the file format.

`Sndfile.` `encoding`
  Returns the encoding.

`Sndfile.` `encoding_description`
  Returns the full description of the encoding.

`Sndfile.` `endianness`
  Returns the endianness.

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

`scikits.audiolab.` `available_file_formats`()
  available_file_formats() Return lists of available file formats supported by audiolab.

`scikits.audiolab.` `available_encodings`()
  available_encodings(major) Return lists of available encoding for the given major format.

### The `Sndfile` class

Sndfile is the main class for audio file IO.

class `scikits.audiolab.` `Sndfile`

  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 name of the file to open (string), or file descriptor (integer) mode : string ‘r’ for read, ‘w’ for write, or ‘rw’ for read and write. format : Format Required when opening a new file for writing, or to read raw audio files (without header). channels : int number of channels. samplerate : int sampling rate.
  Returns: | sndfile: as Sndfile instance. :

  Notes

  format, channels and samplerate need to be given only in the write modes and for raw files.

#### Read methods

`Sndfile.` `read_frames`()

  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 number of frames to read. dtype : numpy dtype dtype of the returned array containing read data (see note).

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

#### Write methods

`Sndfile.` `write_frames`()

  Sndfile.write_frames(self, ndarray input) write given number frames into file.

  Parameters: | input : ndarray array containing data to write.

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

  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

#### Meta-data

`Sndfile.` `samplerate`
  Returns the sampling rate of the file

`Sndfile.` `channels`
  Returns the number of channels

`Sndfile.` `frames`
  Returns the number of frames in the file

`Sndfile.` `format`
  Returns the Format instance attached to the file.

#### Encoding and array dtype

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.

## Sound output

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.

`scikits.audiolab.` `play`(input, fs=44100)

  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 : input signal of rank 2. Each row is assumed to be one channel. fs: int : sampling rate (in Hz)

  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.

### Navigation

- index
- next |
- previous |
- audiolab v0.10.2 documentation »