Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

FEAPI Documentation

Introduction

Researchers in the field of Music Information Retrieval often require a large amount of different audio features to be computed and evaluated. Although many of these features are algorithmically not necessarily demanding, some development effort is required to adapt previously implemented features to new projects or to implement features that have been implemented by others before. Therefore, many researchers have to invest a lot of time into redundant and unnecessary programming work that may be avoided by using a generalized interface for low level feature extraction, which is proposed here.
FEAPI is a Feature Extraction plugin API (Application Programming Interface) with a C programming language interface. It is designed to extract low level features from successive input blocks of audio data. The advantages of a well defined API are:

A plugin API should be designed with two main goals in mind: on the one hand the definition of an easy to understand API with as few functions and parameters as possible to allow fast plugin development and easy host implementation, and on the other hand the definition of an API that is as general as possible to allow for the most diverse use cases and features. Unfortunately, these two requirements tend to contradict each other, so a compromise has to be found.
For the sake of simplicity, the following restrictions have been accepted:

Due to the diversity of features to be extracted, the API has to support: Further requirements are cross-platform compatibility of the API and compatibility with as many programming languages as possible, while using a widely used programming language that allows efficient implementation of signal processing routines. The best compromise here seems to be the programming language ANSI C, since C compilers are available on all computing platforms, it is widely known and it is often used in the field of audio signal processing. Furthermore, many other programming languages and environments allow for the integration of C-libraries.



API documentation

The API declaration and short function descriptions can be found in the file FEAPI.h. Note that the function pointer declarations are used as synonyms for the function names themselves.

Naming conventions

When talking about samples, the number of audio samples in one channel is meant. If the sample size is 32 bit, one sample has a memory usage of 4 bytes. Frames are defined to be the number of samples per channel. A block of frames of length N consists therefore of (N * channels) samples.
Configuration settings that can be defined by the plugin user are called parameters, the algorithm output or the features being extracted are called results. Input data as well as result data have the properties of so called signals.

Function description

Instance controlling

Before using a plugin, an instance has to be created. After using a plugin, this previously created instance has to be destroyed to free the allocated memory and resources.

Information about the plugin

The functions described in this section allow to retrieve information about the plugin itself.

Input description functions

In most cases, the data inputs will be audio inputs and the number of data inputs will equal the number of audio channels. However, other input signals are allowed. The host can poll for information about all input channels in the format of structure FEAPI_SignalDescription_t.

Parameter control functions

Parameters can be used to control the plugin algorithm configuration. For each single parameter, several properties are defined in the FEAPI_ParameterDescription_t structure, which contains information like name, unit, range, default value, description, parameter quantization and "real-timeness". Each parameter has to be in float format. Note the property FEAPI_ParameterDescription_t::bIsChangeableInRealTime that, if it is set to non-realtime, requires a call to FEAPI_InitializePlugin_t after changing the parameter value.

Process functions

Result handling functions

The Feature Extraction plugin API allows the calculation of one or more features at a time. For each single result, several properties are defined in the FEAPI_SignalDescription_t structure, which contains name, unit, range, description, result quantization and output sample rate (if it is constant).
A single result can be a single value, or can be an array of values (like e.g. a magnitude spectrum). Furthermore, depending on the size of the process input buffer, there may be several consecutive results with different time stamps at one time.

Other functions

Calling conventions

In the current state, the API functions are not intended to be thread safe. Therefore, host developers should avoid to call more than one function at the same time. For an example of how the API functions can be called, please read the FEAPI Host Tutorial. Note however, that all plugins still have to be capable of running multiple instances at the same time!



Platform specific definitions

The Feature Extraction plugin API is designed to be platform independent. The specific implementation and usage of plugin and host may have to be platform dependent to some extent. Note that in its current state, FEAPI was only implemented and tested on Win32 and MacOSX. The following recommendations refer to these platforms.

FEAPI plugin directories

The following directories should be the default directories for FEAPI plugins: This is however only the default location, and host implementations should allow the user to specify one or more additional directories to be searched for plugins.

Plugin extensions

The host has to test possible plugins for FEAPI compliance by checking the exported functions of the library. Therefore, the used file extension is not of much importance. It is recommended however, that the following file extensions are used:

License

The Feature Extraction plugin API is released under a BSD license. Therefore, static linking of the API without publishing other sources of the project is allowed and the code may be used in open source as well as in commercial products with the small restrictions mentioned in the license itself (see FEAPI.h).
Please keep the authors or contributors informed about any extensions or fixes of the source files.
The exact license is:

Copyright (c) 2004-2007, FEAPI development team All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the FEAPI development team nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.





Coding style minimal overview

Variable names have a prefix characters indicating their types:
unsigned: u
pointer: p
array: a
class: C
bool: b
char: c
short (int16): s
int (int32): i
__int64: l
float (float32): f
double (float64): d
For example, a pointer to a buffer of unsigned ints will be named puiBufferName.



Contact

web: http://feapi.sourceforge.net
feapi mailing list: feapi-discussion@lists.sourceforge.net

Generated on Fri Mar 23 10:28:52 2007 for FEAPI Documentation by  doxygen 1.3.9.1