Maaate API

Documentation

• Maaate API
• Maaate FAQ
• Modules information
• License
• Credits



• more on MPEG
  audio file structure:
  more on Header
  more on Layer 1
  more on Layer 2
  more on Layer 3

Related Information

• Official MPEG Audio FAQ
• BSD Port of Maaate

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:

• Tier 1 API
• Tier 2 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.

• 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

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.