![](../images/maaate.gif)
Documentation
Related Information
|
Introduction
Maaate is designed to allow high level audio content analysis
on different audio file format. The Maaate toolkit includes two
main tiers, and so the Maaate API should be consider in two parts:
The Maaate API includes a C++ API and a C
API.
Maaate C++ API
C++ Tier 1 API
This is the API of the SOUNDfile class. It gives access to
relevant information about the sound file (name, file format,
channels, duration, etc.), and allows the analysis of that sound
file on pre-processed frequency
values and format specific fields.
The analysis is performed on one window at a time. The windows
are indexed on the whole file, 0 being the begining of the file.
So at any one time, the analysis window should be at only one
position in a file, namely the file pointer position. There are
functions available to move the analysis window.
The frequency (subband) values are available at different
resolutions:
- NO: Means that only the file format specific fields
are available, no subband values are available.
- LOW: Means that the analysis is done with a low
frequency resolution (high temporal resolution).
- HIGH: Means that the analysis is done with a high
frequency resolution (low temporal resolution).
- PCM: Means that the analysis is done on PCM samples.
When analysing a file you should stick with one resolution level
because the results will otherwise not be consistent over the
file. It is however possible to change the resolution level half
way through the file, though this will probably attract a delay.
- Constructors and destructor:
SOUNDfile ().
SOUNDfile (string filestr): Create a
SOUNDfile instance allowing to handle the sound file filestr.
virtual ~SOUNDfile (): Destroy that SOUNDfile
instance.
- File information:
string file (): give the file name.
Format file_type(): give file format type
(MPEG,...).
bool is_stereo (): true if the file is a
stereo file.
int channels (): give the number of channels.
double samplingrate (): give the pcm sampling
rate in KHz.
- Time information:
float at_time (): return the actual time
position in sec.
float file_duration (): file duration in sec.
float sample_duration ( Resolution res = LOW ):
sample duration in sec = time resolution.
bool seek_time ( float t ): go to time
position t in sec.
float window_duration (): window duration in
sec.
- Window information:
long at_window (): actual window number
long file_window_number (): total number of
windows in the file.
unsigned int timeticks ( Resolution res = LOW ):
number of samples in one window.
bool seek_window ( long w_nb ): go to window
nb w_nb.
- Matching functions:
long time2window ( float t ): convert second
into window number.
float window2time ( long w_nb ): convert
window number into second.
- Extraction and Skip function:
bool next_window (Resolution res = LOW): go
to next window and analyse it with res.
bool skip_window (): go to next window
without analysing it.
- Access information function:
double freq_value ( unsigned int ch, unsigned int
sb, unsigned int nb = 0, Resolution res = LOW ): subband
samples of the current window.
unsigned int nb_subbands ( Resolution res = LOW ):
number of subbands for that res.
- Analyse functions:
- Time resolution = 1 subband sample:
double freqvalue_st_mean ( unsigned int sb,
unsigned int nb = 0, Resolution res = LOW): give the
mean of samples nb in subband sb over channels if
available.
double freqvalue_st_rms ( unsigned int sb,
unsigned int nb = 0, Resolution res = LOW): give the
rms of samples nb in subband sb over channels if
available.
double normalised_sb_nrj ( unsigned int sb,
unsigned int nb = 0, Resolution res = LOW): give the
normalised subband energy samples.
- Time resolution = 1 window:
double subband_scalefactor ( unsigned int sb,
Resolution res = LOW): give an approximation
of the value in that subband.
double subband_mean ( unsigned int sb,
Resolution res = LOW): give the
mean of samples over the current window.
double subband_rms ( unsigned int sb,
Resolution res = LOW): give the
rms of samples over the current window.
double subband_nrj ( unsigned int sb,
Resolution res = LOW): give the
normalised subband energy over the current window.
- PCM Decoder:
long decode (short * buffer, long windows,
Channels ch): fill buffer with pcm samples corresponding
to the "windows" windows following the current
window. This moves the current file pointer while decoding and
returns the number of samples in buffer.
- Format Specific information access:
AllFormat *format: File format specific
pointer to an instance of AllFormat.
C++ Tier 2 API
This part of the Maaate API, provides all necessary functions
and classes to create, handle, and use modules and module
libraries. For further information about this API, you should read
the module writer's guide and have
a look at module.H and plugins.H. Here a brief overview is given
of the plugins.H API and module.H
API.
C++ Tier 2 module.H API
This part of the API defines the module
class, as well as the parameters of
the modules.
ModuleParam class API
Class to contain all different possible parameter types.
- Constructors:
Constructors:
ModuleParam (SOUNDfile * f): creates a
parameter from a SOUNDfile.
ModuleParam (SegmentTable * s): creates a
parameter from a SegmentTable.
ModuleParam (SegmentData * s): creates a
parameter from a SegmentData.
ModuleParam (bool bb): creates a parameter
from a boolean.
ModuleParam (int ii): creates a parameter from
an integer.
ModuleParam (double rr): creates a parameter
from a double.
ModuleParam (char * ss): creates a parameter
from a string.
ModuleParam (const ModuleParam& mp): copy
constructor.
- Information functions:
bool isZero (): checks if a parameter is zero
(NULL, 0, 0.0).
MaaateType getType (): returns the type of a
parameter.
- Setting functions:
bool set (SOUNDfile * spf).
bool set (SegmentTable * sgt).
bool set (SegmentData * sgd).
bool set (bool bl).
bool set (int it).
bool set (double rl).
bool set (char * sg).
- Getting functions:
SOUNDfile * get_sf ().
SegmentTable * get_st ().
SegmentData * get_sd ().
bool get_b ()
int get_i ()
double get_r ()
char * get_s ()
ModuleParamSpec class API
Class to contain the specification of one module parameter.
- Constructor:
ModuleParamSpec (string n, string d, MaaateType
t, ModuleParam * p, MaaateConstraint * c = NULL): creates
a parameter specification including a module parameter name,
description, type, default value and constraint specification.
- Access functions:
string name ().
string desc ().
MaaateType type ().
ModuleParam * defaultValue ().
MaaateConstraint * constraint ().
- Setting functions:
void setDefaultValue (ModuleParam * def).
void setConstraint (MaaateConstraint * con).
Module class API
Class to contain everything necessary to handle a module (an
anlysis algorithm).
- Constructor and destructor:
Module (): loads an analysis module with all
its functions and parameter specifications (performs
initialisation with the initF, too).
~Module (): destroys an analysis module.
- Member access:
bool sane (): is it a valid module.
string name (): return module's name.
string desc (): return module's description.
string author (): return module's author.
string copyright (): return module's
copyright info.
string url (): return a url containing more
info on the module.
- Member setting:
void set_name (string nm).
void set_desc (string ds).
void set_author (string au).
void set_copyright (string cp).
void set_url (string ur).
- Specification of input and output
parameters:
<list ModuleParamSpec> * inputSpecs ():
return input parameter specification.
<list ModuleParamSpec> * outputSpecs ():
return output parameter specification.
- Module functions:
<list ModuleParam> * defaultValues ():
returns default parameter values for a parameter list which
might be calculated from some of the parameters provided or
might be a single default value as stored with the parameter
spec.
void suggestValues (<list ModuleParam> *
paramsIn): suggests parameter values given that some of
the input parameters have already been set.
<list ModuleParam> * apply (<list
ModuleParam> * paramsIn): works on input parameters and
returns output parameters (executes the algorithm).
void reset (): resets the module's data.
bool checkConstraints (<list ModuleParam> *
paramsIn): ensures parameters are within the given
constraints.
C++ Tier 2 plugins.H API
This part of the API provides the handling of module libraries,
and allow to load modules from those libraries.
- Default constructor:
Plugins (): creates a handler for loading
plugin libraries and administrating a list of the modules
contained therein.
- Add functions:
void AddLibrariesMaaatePath (): load every
module that Maaate is aware of.
void AddStaticModules (): add statically
linked modules to the module list.
Functions to open libraries, thus creating PluginLibrary
instances, and appending to the class' module list:
bool AddLibrary (string filename): all
modules contained in one library.
void AddLibraries (string dirname): all
modules contained in all libraries in a directory.
void AddLibrariesPath (string pathlist):
all modules contained in all libraries of all directories
specified in a colon-separated path list.
void AddModule (Module * module): a module
of a library (only if removed before).
- Remove functions:
void RemoveLibrary (string name): destructs a
PluginLibrary and unloads all its modules.
void RemoveModule (Module * module): removes
one module from the module list and adds it to the removed
list.
- List functions:
<list Module> * Modules (): return a
list of available modules for an application.
<list Module> * LibraryModules (string
name): return a list of available modules for a library.
- Get function:
Module * GetModule (string name): get a
specific module of a given name.
Maaate C API
Basically the C API is analogous to the C++ API, just giving C
functions. You should have a better idea of that API by looking at
SOUNDfile.H for tier 1 and plugins.H and module.H for tier 2.
|