Chris@103: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@103: 
Chris@103: /*
Chris@103:     Vamp feature extraction plugin using the MATCH audio alignment
Chris@103:     algorithm.
Chris@103: 
Chris@103:     Centre for Digital Music, Queen Mary, University of London.
Chris@236:     Copyright (c) 2007-2020 Simon Dixon, Chris Cannam, and Queen Mary
Chris@230:     University of London, Copyright (c) 2014-2015 Tido GmbH.
Chris@103:     
Chris@103:     This program is free software; you can redistribute it and/or
Chris@103:     modify it under the terms of the GNU General Public License as
Chris@103:     published by the Free Software Foundation; either version 2 of the
Chris@103:     License, or (at your option) any later version.  See the file
Chris@103:     COPYING included with this distribution for more information.
Chris@103: */
Chris@103: 
Chris@103: #ifndef FEATURE_CONDITIONER_H
Chris@103: #define FEATURE_CONDITIONER_H
Chris@103: 
Chris@187: #include "MatchTypes.h"
Chris@103: 
Chris@103: /**
Chris@103:  * Take a series of feature vectors and apply conditioning of some
Chris@103:  * sort, such as normalisation or first-order derivative.
Chris@103:  *
Chris@103:  * Note that FeatureConditioner maintains internal frame-to-frame
Chris@103:  * state: use one FeatureConditioner per audio source, and construct a
Chris@103:  * new one for each new source.
Chris@103:  */
Chris@103: class FeatureConditioner
Chris@103: {
Chris@103: public:
Chris@103:     enum Normalisation {
Chris@103: 
Chris@103:         /** Do not normalise */
Chris@103:         NoNormalisation,
Chris@103:         
Chris@103:         /** Normalise each feature vector to have a sum of 1 */
Chris@103:         NormaliseToSum1,
Chris@103:         
Chris@103:         /** Normalise each feature vector by the long-term average of
Chris@103:          *  the summed energy */
Chris@103:         NormaliseToLTAverage,
Chris@103:     };
Chris@103: 
Chris@103:     enum OutputOrder {
Chris@103: 
Chris@103: 	/** Output the normalised features without further processing */
Chris@103: 	OutputFeatures,
Chris@103: 
Chris@103: 	/** Output the half-wave rectified difference between the
Chris@116: 	 *  previous and current features instead of the straight
Chris@116: 	 *  feature values. */
Chris@103: 	OutputRectifiedDerivative,
Chris@116: 
Chris@130: 	/** Output the absolute difference between the previous and
Chris@130: 	 *  current features instead of the straight feature
Chris@130: 	 *  values. */
Chris@116: 	OutputDerivative,
Chris@103:     };
Chris@103: 
Chris@103:     struct Parameters {
Chris@103: 
Chris@103: 	Parameters() :
Chris@103: 	    norm(NormaliseToSum1),
Chris@103: 	    order(OutputRectifiedDerivative),
Chris@151: 	    silenceThreshold(0.01),
Chris@103: 	    decay(0.99)
Chris@103: 	{}
Chris@103: 
Chris@103: 	/** Feature normalisation. */
Chris@103: 	Normalisation norm;
Chris@103: 
Chris@103: 	/** Type of output to generate (plain feature, derivative etc). */
Chris@103: 	OutputOrder order;
Chris@103: 
Chris@103: 	/** Silence threshold. If non-zero, any feature whose total
Chris@103: 	 *  energy (simply the sum of feature values) is below that
Chris@130: 	 *  threshold will be rounded down to all zeros. Note that
Chris@134: 	 *  this refers to the energy of the pre-norm feature, not of
Chris@134: 	 *  its derivative even if that is what is being returned. */
Chris@103: 	double silenceThreshold;
Chris@103: 
Chris@103:         /** Frame-to-frame decay factor in calculating long-term average */
Chris@103: 	double decay;
Chris@103:     };
Chris@103: 	
Chris@103:     /**
Chris@114:      * Construct a FeatureConditioner with the given parameters.
Chris@103:      *
Chris@114:      * Note that FeatureConditioner maintains internal frame-to-frame
Chris@114:      * state: use one FeatureConditioner per audio source, and construct
Chris@103:      * a new one for each new source.
Chris@103:      */
Chris@140:     FeatureConditioner(Parameters parameters);
Chris@103: 
Chris@103:     /**
Chris@103:      * Process the given feature and return the conditioned feature.
Chris@103:      */
Chris@185:     feature_t process(const feature_t &feature);
Chris@103: 
Chris@103: protected:
Chris@103:     Parameters m_params;
Chris@103:     
Chris@103:     /** Long term average feature energy. */
Chris@103:     double m_ltAverage;
Chris@103: 
Chris@103:     /** The most recent feature, used for calculating the feature to
Chris@103:      *  feature difference. This is therefore not yet normalised. */
Chris@185:     feature_t m_prev;
Chris@103: };
Chris@103: 
Chris@103: #endif