Loudia Documentation

0.1

Author:

Ricard Marxer

Loudia is a C++ library with Python bindings. It is used to create audio applications.

Loudia is specially targeted for researchers. The algorithms are not necessarily tuned for performance but rather for: Ease of use Flexibility and clarity of the algorithms Variety of algorithms

Features

The following algorithms are implemented:

• Window
• Unwrap
• Fast Fourier Transform (FFT / IFFT) (wrapper around libfftw [http://www.fftw.org/])
• Discrete Cosine Transform (DCT)
• Filter and BandFilter (based on Scipy implementation):
  • Band type
    • LowPass
    • HighPass
    • BandPass
    • BandStop
  • Filter type
    • Chebyshev I
    • Chebyshev II
    • Bessel
    • Butterworth
• Correlation / Autocorrelation
  • Direct calculation
  • FFT based calculation
• Resample (wrapper around libsamplerate [http://www.mega-nerd.com/SRC/])
• Onset Detection Functions:
  • High Frequency Content (HFC)
  • Flux
  • Phase Deviation
  • Complex Domain
  • Modified Kullback-Liebler
  • Peak Center of Gravity
• Pitch Estimation:
  • Autocorrelation Function based (ACF)
  • Inverse Problem based
• Spectral Bands
  • Mel bands
• MFCC
• LPC
• Sinusoidal Modelling:
  • Peak Detection
  • Peak Interpolation
  • Peak Tracking
• Spectral Whitening
• Spectral Noise Suppression
• Non-negative Matrix Factorization (NMF)
• Other experimental and/or unfinished algorithm implementations
  • Spectral Reassignment
  • Adaptative Optimized Kernel (AOK) (modification of AOK 4.1 [http://www.macunix.net/aok.html])
  • Peak Synthesis
  • Incremental Non-negative Matrix Factorization (INMF)
  • LPC residual

Numerous examples which can also be used for testing in some cases can be found in python/ Some of the examples require an audio WAVE filename as input argument.

Dependencies

The C++ library Libaudio requires:

• At run time:
  • libsamplerate-dev >=0.1.3
  • libfftw3-dev >=3.1.2
• At compile time:
  • gcc
  • python >=2.5

The Python bindings Libaudio require:

• At run time:
  • numpy
• At compile time:
  • swig
  • numpy-dev
  • python-dev

Libaudio uses a template library called Eigen (http://eigen.tuxfamily.org).

In C++ all algorithms use Eigen::Matrix types as inputs and outputs.

In the Python bindings use Numpy arrays as inputs and outputs.

Build and installation

To build and install Loudia run:

./waf configure --prefix=/some/install/dir
./waf build
sudo ./waf install

To uninstall it run:

sudo ./waf uninstall

Several options allow different building modes.

To build without Python bindings run:

./waf configure --no-python-bindings
./waf build

To build the documentation run:

./waf configure --doc
./waf build

To build in debug mode run:

./waf configure --debug
./waf build

All the above options can be combined.

Overview

The library is composed by algorithms. Algorithms are classes that represent a processing unit.

All algorithms share two methods:

• setup()
• reset()

Additionally a method called process() is also always present. Depending on the algorithm the method will take different number and types of arguments.

The algorithms return the results in a C-style way. The process() method also takes as input arguments pointers to matrices where the results will be written.

All inputs and outputs to the process() methods are of type Eigen::Matrix.

Quick howto

From Python you may create algorithm, change its parameters and call the process method:

import numpy
import pylab
import loudia

data_frame = numpy.arange( 128 )

fft = loudia.FFT()
fft.setFftSize( 128 )

result = fft.process( data_frame )
pylab.plot( result[0,:] ) # Note that the results of the FFT algorithm are stacked in rows (we only plot the first)

# When setting several parameters we might not want the algorithm to reconfigure itself
# method after each parameter setting, and we will call the setup() manually 
fft.setFftSize( 256, False )
fft.setZeroPhase( True, False )
fft.setup()

result = fft.process( data_frame )
pylab.plot( abs( result[0,:] ) ) # Note that the results of the FFT algorithm are stacked in rows (we only plot the first)

pylab.show()

Limitations

A few assumptions are used when using the library:

• Loudia has no algorithm for loading audio frames

• All algorithms take Eigen::Matrix types as inputs and outputs in the process() methods

• Loudia does NOT have a streaming mode. All algorithms mantain a state which can be reset using reset(). And the process() methods may act on preallocated matrices. Therefore with the use of Eigen::Map, Loudia can be used inside streaming libraries that expose the buffers.