Google

Go to CSIRO.AU Home Page
Go to Mathematical & Information Sciences home page
HOME RESEARCH CONTACT DOING BUSINESS POSITIONS VACANT MEDIA EVENTS PUBLICATIONS PRODUCTS

 

Australian audio analysis tools

Maaate API


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:
  • 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.

 

Applications Download Code FAQ Sceen Snapshots Project Team

last updated 10/01/2002
Silvia.Pfeiffer@csiro.au

© Copyright 1997-2002, CSIRO Australia
Use of this web site and information available from
it is subject to our
Legal Statement