path: root/src/loris/Analyzer.h

#ifndef INCLUDE_ANALYZER_H
#define INCLUDE_ANALYZER_H
/*
 * This is the Loris C++ Class Library, implementing analysis, 
 * manipulation, and synthesis of digitized sounds using the Reassigned 
 * Bandwidth-Enhanced Additive Sound Model.
 *
 * Loris is Copyright (c) 1999-2010 by Kelly Fitz and Lippold Haken
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY, without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 *
 * Analyzer.h
 *
 * Definition of class Loris::Analyzer.
 *
 * Kelly Fitz, 5 Dec 99
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */
#include <memory>
#include <vector>
#include "LinearEnvelope.h"
#include "Partial.h"
#include "PartialList.h"
#include "SpectralPeaks.h"

//  begin namespace
namespace Loris {

class Envelope;
class LinearEnvelopeBuilder;
//  oooo, this is nasty, need to fix it!
// class SpectralPeak;
// typedef std::vector< SpectralPeak > Peaks;

// ---------------------------------------------------------------------------
//  class Analyzer
//
//! Class Analyzer represents a configuration of parameters for
//! performing Reassigned Bandwidth-Enhanced Additive Analysis
//! of sampled sounds. The analysis process yields a collection 
//! of Partials, each having a trio of synchronous, non-uniformly-
//! sampled breakpoint envelopes representing the time-varying 
//! frequency, amplitude, and noisiness of a single bandwidth-
//! enhanced sinusoid. These Partials are accumulated in the
//! Analyzer.
//!
//! The core analysis parameter is the frequency resolution, the 
//! minimum instantaneous frequency spacing between partials. Most 
//! other parameters are initially configured according to this 
//! parameter (and the analysis window width, if specified).
//! Subsequent parameter mutations are independent.
//! 
//! Bandwidth enhancement:
//! Two different strategies are available for computing bandwidth
//! (or noisiness) envelope: 
//! 
//! One strategy is to construct bandwidth envelopes during analysis
//! by associating residual energy in the spectrum (after peak 
//! extraction) with the selected spectral peaks that are used 
//! to construct Partials. This is the original bandwidth enhancement
//! algorithm, and bandwidth envelopes constructed in this way may
//! be suitable for use in bandwidth-enhanced synthesis. 
//! 
//! Another stategy is to construct bandwidth envelopes during 
//! analysis by storing the mixed derivative of short-time phase, 
//! scaled and shifted so that a value of 0 corresponds
//! to a pure sinusoid, and a value of 1 corresponds to a
//! bandwidth-enhanced sinusoid with maximal energy spread
//! (minimum convergence in frequency). These bandwidth envelopes
//! are not suitable for bandwidth-enhanced synthesis, be sure
//! to set the bandwidth to 0, or to disable bandwidth enhancement
//! before rendering.
//! 
//! The Analyzer may be configured to use either of these two
//! strategies for bandwidth-enhanced analysis, or to construct
//! no bandwidth envelopes at all. If unspecified, the default
//! Analyzer configuration uses spectral residue to construct
//! bandwidth envelopes.
//! 
//! \sa storeResidueBandwidth, storeConvergenceBandwidth, storeNoBandwidth
//! 
//! For more information about Reassigned Bandwidth-Enhanced 
//! Analysis and the Reassigned Bandwidth-Enhanced Additive Sound 
//! Model, refer to the Loris website: www.cerlsoundgroup.org/Loris/.
//
class Analyzer
{
//  -- public interface --
public:

//  -- construction --

    //! Construct a new Analyzer configured with the given  
    //! frequency resolution (minimum instantaneous frequency   
    //! difference between Partials). All other Analyzer parameters     
    //! are computed from the specified frequency resolution.   
    //! 
    //! \param resolutionHz is the frequency resolution in Hz.
    explicit Analyzer( double resolutionHz );
    
    //! Construct a new Analyzer configured with the given  
    //! frequency resolution (minimum instantaneous frequency   
    //! difference between Partials) and analysis window width
    //! (main lobe, zero-to-zero). All other Analyzer parameters    
    //! are computed from the specified resolution and window width.    
    //! 
    //! \param resolutionHz is the frequency resolution in Hz.
    //! \param windowWidthHz is the main lobe width of the Kaiser
    //! analysis window in Hz.
    Analyzer( double resolutionHz, double windowWidthHz );

    //! Construct a new Analyzer configured with the given time-varying
    //! frequency resolution (minimum instantaneous frequency   
    //! difference between Partials) and analysis window width
    //! (main lobe, zero-to-zero). All other Analyzer parameters    
    //! are computed from the specified resolution and window width.    
    //! 
    //! \param resolutionHz is the frequency resolution in Hz.
    //! \param windowWidthHz is the main lobe width of the Kaiser
    //! analysis window in Hz.
    Analyzer( const Envelope & resolutionEnv, double windowWidthHz );

    //! Construct  a new Analyzer having identical
    //! parameter configuration to another Analyzer. 
    //! The list of collected Partials is not copied.       
    //! 
    //! \param other is the Analyzer to copy.   
    Analyzer( const Analyzer & other );

    //! Destroy this Analyzer.
    ~Analyzer( void );

    //! Construct  a new Analyzer having identical
    //! parameter configuration to another Analyzer. 
    //! The list of collected Partials is not copied.       
    //! 
    //! \param rhs is the Analyzer to copy. 
    Analyzer & operator=( const Analyzer & rhs );

//  -- configuration --

    //! Configure this Analyzer with the given frequency resolution 
    //! (minimum instantaneous frequency difference between Partials, 
    //! in Hz). All other Analyzer parameters are (re-)computed from the 
    //! frequency resolution, including the window width, which is
    //! twice the resolution.      
    //! 
    //! \param resolutionHz is the frequency resolution in Hz.
    void configure( double resolutionHz );

    //! Configure this Analyzer with the given frequency resolution 
    //! (minimum instantaneous frequency difference between Partials)
    //! and analysis window width (main lobe, zero-to-zero, in Hz). 
    //! All other Analyzer parameters are (re-)computed from the 
    //! frequency resolution and window width.      
    //! 
    //! \param resolutionHz is the frequency resolution in Hz.
    //! \param windowWidthHz is the main lobe width of the Kaiser
    //! analysis window in Hz.
    //!     
    //! There are three categories of analysis parameters:
    //! - the resolution, and params that are usually related to (or
    //! identical to) the resolution (frequency floor and drift)
    //! - the window width and params that are usually related to (or
    //! identical to) the window width (hop and crop times)
    //! - independent parameters (bw region width and amp floor)
    void configure( double resolutionHz, double windowWidthHz );

	//! Configure this Analyzer with the given time-varying frequency resolution 
	//! (minimum instantaneous frequency difference between Partials)
	//! and analysis window width (main lobe, zero-to-zero, in Hz). 
	//! All other Analyzer parameters are (re-)computed from the 
	//! frequency resolution and window width.      
	//! 
	//! \param resolutionEnv is the time-varying frequency resolution 
	//!	in Hz.
	//! \param windowWidthHz is the main lobe width of the Kaiser
	//! analysis window in Hz.
	//!     
	//! There are three categories of analysis parameters:
	//! - the resolution, and params that are usually related to (or
	//! identical to) the resolution (frequency floor and drift)
	//! - the window width and params that are usually related to (or
	//! identical to) the window width (hop and crop times)
	//! - independent parameters (bw region width and amp floor)
	//
	void configure( const Envelope & resolutionEnv, double windowWidthHz );    
    
//  -- analysis --

    //! Analyze a vector of (mono) samples at the given sample rate         
    //! (in Hz) and store the extracted Partials in the Analyzer's 
    //! PartialList (std::list of Partials).    
    //! 
    //! \param  vec is a vector of floating point samples
    //! \param  srate is the sample rate of the samples in the vector 
    void analyze( const std::vector<double> & vec, double srate );
    
    //! Analyze a range of (mono) samples at the given sample rate      
    //! (in Hz) and store the extracted Partials in the Analyzer's
    //! PartialList (std::list of Partials).    
    //! 
    //! \param  bufBegin is a pointer to a buffer of floating point samples
    //! \param  bufEnd is (one-past) the end of a buffer of floating point 
    //!         samples
    //! \param  srate is the sample rate of the samples in the buffer
    void analyze( const double * bufBegin, const double * bufEnd, double srate );
    
//  -- tracking analysis --

    //! Analyze a vector of (mono) samples at the given sample rate         
    //! (in Hz) and store the extracted Partials in the Analyzer's
    //! PartialList (std::list of Partials). Use the specified envelope
    //! as a frequency reference for Partial tracking.
    //!
    //! \param  vec is a vector of floating point samples
    //! \param  srate is the sample rate of the samples in the vector
    //! \param  reference is an Envelope having the approximate
    //!         frequency contour expected of the resulting Partials.
    void analyze( const std::vector<double> & vec, double srate, 
                  const Envelope & reference );
    
    //! Analyze a range of (mono) samples at the given sample rate      
    //! (in Hz) and store the extracted Partials in the Analyzer's
    //! PartialList (std::list of Partials). Use the specified envelope
    //! as a frequency reference for Partial tracking.
    //! 
    //! \param  bufBegin is a pointer to a buffer of floating point samples
    //! \param  bufEnd is (one-past) the end of a buffer of floating point 
    //!         samples
    //! \param  srate is the sample rate of the samples in the buffer
    //! \param  reference is an Envelope having the approximate
    //!         frequency contour expected of the resulting Partials.
    void analyze( const double * bufBegin, const double * bufEnd, double srate,
                  const Envelope & reference );

    void analyze_peaks( const std::vector<double> & vec, double srate );
    
//  -- parameter access --

    //! Return the amplitude floor (lowest detected spectral amplitude),            
    //! in (negative) dB, for this Analyzer.                
    double ampFloor( void ) const;

    //! Return the crop time (maximum temporal displacement of a time-
    //! frequency data point from the time-domain center of the analysis
    //! window, beyond which data points are considered "unreliable")
    //! for this Analyzer.
    double cropTime( void ) const;

    //! Return the maximum allowable frequency difference between                   
    //! consecutive Breakpoints in a Partial envelope for this Analyzer.                
    double freqDrift( void ) const;

    //! Return the frequency floor (minimum instantaneous Partial               
    //! frequency), in Hz, for this Analyzer.               
    double freqFloor( void ) const;
	
	//! Return the frequency resolution (minimum instantaneous frequency        
	//! difference between Partials) for this Analyzer at the specified
	//! time in seconds. If no time is specified, then the initial resolution
	//!	(at 0 seconds) is returned.
	//! 
	//! \param time is the time in seconds at which to evaluate the 
	//!		   frequency resolution
	double freqResolution( double time = 0.0 ) const; 

    //! Return the hop time (which corresponds approximately to the 
    //! average density of Partial envelope Breakpoint data) for this 
    //! Analyzer.
    double hopTime( void ) const;

    //! Return the sidelobe attenutation level for the Kaiser analysis window in
    //! positive dB. Larger numbers (e.g. 90) give very good sidelobe 
    //! rejection but cause the window to be longer in time. Smaller numbers 
    //! (like 60) raise the level of the sidelobes, increasing the likelihood
    //! of frequency-domain interference, but allow the window to be shorter
    //! in time.
    double sidelobeLevel( void ) const;

    //! Return the frequency-domain main lobe width (measured between 
    //! zero-crossings) of the analysis window used by this Analyzer.               
    double windowWidth( void ) const;
     
    //! Return true if the phases and frequencies of the constructed
    //! partials should be modified to be consistent at the end of the
    //! analysis, and false otherwise. (Default is true.)
    bool phaseCorrect( void ) const;


//  -- parameter mutation --

    //! Set the amplitude floor (lowest detected spectral amplitude), in            
    //! (negative) dB, for this Analyzer. 
    //! 
    //! \param x is the new value of this parameter.            
    void setAmpFloor( double x );

    //! Set the crop time (maximum temporal displacement of a time-
    //! frequency data point from the time-domain center of the analysis
    //! window, beyond which data points are considered "unreliable")
    //! for this Analyzer.
    //! 
    //! \param x is the new value of this parameter.            
    void setCropTime( double x );

    //! Set the maximum allowable frequency difference between                  
    //! consecutive Breakpoints in a Partial envelope for this Analyzer.                
    //! 
    //! \param x is the new value of this parameter.            
    void setFreqDrift( double x );

    //! Set the frequency floor (minimum instantaneous Partial                  
    //! frequency), in Hz, for this Analyzer.
    //! 
    //! \param x is the new value of this parameter.            
    void setFreqFloor( double x );

    //! Set the frequency resolution (minimum instantaneous frequency       
    //! difference between Partials) for this Analyzer. (Does not cause     
    //! other parameters to be recomputed.)                                     
    //! 
    //! \param x is the new value of this parameter.            
    void setFreqResolution( double x );
    
	//! Set the time-varying frequency resolution (minimum instantaneous frequency       
	//! difference between Partials) for this Analyzer. (Does not cause     
	//! other parameters to be recomputed.)                                     
	//! 
	//! \param e is the envelope to copy for this parameter.                                        
	void setFreqResolution( const Envelope & e );    

    //! Set the hop time (which corresponds approximately to the average
    //! density of Partial envelope Breakpoint data) for this Analyzer.
    //! 
    //! \param x is the new value of this parameter.            
    void setHopTime( double x );

    //! Set the sidelobe attenutation level for the Kaiser analysis window in
    //! positive dB. More negative numbers (e.g. -90) give very good sidelobe 
    //! rejection but cause the window to be longer in time. Less negative 
    //! numbers raise the level of the sidelobes, increasing the likelihood
    //! of frequency-domain interference, but allow the window to be shorter
    //! in time.
    //! 
    //! \param x is the new value of this parameter.            
    void setSidelobeLevel( double x );

    //! Set the frequency-domain main lobe width (measured between 
    //! zero-crossings) of the analysis window used by this Analyzer.   
    //! 
    //! \param x is the new value of this parameter.            
    void setWindowWidth( double x );

    //! Indicate whether the phases and frequencies of the constructed
    //! partials should be modified to be consistent at the end of the
    //! analysis. (Default is true.)
    //!
    //! \param  TF is a flag indicating whether or not to construct
    //!         phase-corrected Partials
    void setPhaseCorrect( bool TF = true );
    
    
//  -- bandwidth envelope specification --

    enum { Default_ResidueBandwidth_RegionWidth = 2000,
           Default_ConvergenceBandwidth_TolerancePct = 10 };
           
    //! Construct Partial bandwidth envelopes during analysis
    //! by associating residual energy in the spectrum (after
    //! peak extraction) with the selected spectral peaks that
    //! are used to construct Partials. 
    //!
    //!	This is the default bandwidth-enhancement strategy.
    //! 
    //! \param regionWidth is the width (in Hz) of the bandwidth 
    //! association regions used by this process, must be positive.
    //! If unspecified, a default value is used.
    void storeResidueBandwidth( double regionWidth = Default_ResidueBandwidth_RegionWidth );
    
	//!	Construct Partial bandwidth envelopes during analysis
	//!	by storing the mixed derivative of short-time phase, 
	//!	scaled and shifted so that a value of 0 corresponds
	//!	to a pure sinusoid, and a value of 1 corresponds to a
	//! bandwidth-enhanced sinusoid with maximal energy spread
	//! (minimum sinusoidal convergence).
	//!
	//!	\param tolerance is the amount of range over which the 
	//!	mixed derivative indicator should be allowed to drift away 
	//!	from a pure sinusoid before saturating. This range is mapped
	//!	to bandwidth values on the range [0,1]. Must be positive and 
	//!	not greater than 1. If unspecified, a default value is used.
    void storeConvergenceBandwidth( double tolerancePct = 
    		0.01 * (double)Default_ConvergenceBandwidth_TolerancePct );
    
    //! Disable bandwidth envelope construction. Bandwidth 
    //! will be zero for all Breakpoints in all Partials.
    void storeNoBandwidth( void );
    
    //! Return true if this Analyzer is configured to compute
    //! bandwidth envelopes using the spectral residue after
    //! peaks have been identified, and false otherwise.
    bool bandwidthIsResidue( void ) const;
    
    //! Return true if this Analyzer is configured to compute
    //! bandwidth envelopes using the mixed derivative convergence
    //! indicator, and false otherwise.
    bool bandwidthIsConvergence( void ) const;
    
    //! Return the width (in Hz) of the Bandwidth Association regions
    //! used by this Analyzer, only if the spectral residue method is
    //! used to compute bandwidth envelopes. Return zero if the mixed
    //! derivative method is used, or if no bandwidth is computed.
    double bwRegionWidth( void ) const;

    //! Return the mixed derivative convergence tolerance (percent)
    //! only if the convergence indicator is used to compute
    //! bandwidth envelopes. Return zero if the spectral residue
    //! method is used or if no bandwidth is computed.
    double bwConvergenceTolerance( void ) const;

    //! Return true if bandwidth envelopes are to be constructed
    //!	by any means, that is, if either bandwidthIsResidue() or 
    //!	bandwidthIsConvergence() are true. Otherwise, return
    //! false.
    bool associateBandwidth( void ) const
        { return bandwidthIsResidue() || bandwidthIsConvergence(); }

    //! Deprecated, use storeResidueBandwidth or storeNoBandwidth instead.            
    void setBwRegionWidth( double x ) 
        { 
            if ( x != 0 )
            {
                storeResidueBandwidth( x ); 
            }
            else
            {
                storeNoBandwidth();
            }
        }
           

//  -- PartialList access --

    //! Return a mutable reference to this Analyzer's list of 
    //! analyzed Partials. 
    PartialList & partials( void );

    //! Return an immutable (const) reference to this Analyzer's 
    //! list of analyzed Partials. 
    const PartialList & partials( void ) const;

//  -- envelope access --

    enum { Default_FundamentalEnv_ThreshDb = -60, 
           Default_FundamentalEnv_ThreshHz = 8000 };

    //! Specify parameters for constructing a fundamental frequency 
    //! envelope for the analyzed sound during analysis. The fundamental 
    //! frequency estimate can be accessed by fundamentalEnv() after the 
    //! analysis is complete. 
    //!
    //! By default, a fundamental envelope is estimated during analysis
    //! between the frequency resolution and 1.5 times the resolution.
    //!
    //! \param  fmin is the lower bound on the fundamental frequency estimate
    //! \param  fmax is the upper bound on the fundamental frequency estimate
    //! \param  threshDb is the lower bound on the amplitude of a spectral peak
    //!         that will constribute to the fundamental frequency estimate (very
    //!         low amplitude peaks tend to have less reliable frequency estimates).
    //!         Default is -60 dB.
    //! \param  threshHz is the upper bound on the frequency of a spectral
    //!         peak that will constribute to the fundamental frequency estimate.
    //!         Default is 8 kHz.
    void buildFundamentalEnv( double fmin, double fmax, 
                              double threshDb = Default_FundamentalEnv_ThreshDb, 
                              double threshHz = Default_FundamentalEnv_ThreshHz );                                     


    //! Return the fundamental frequency estimate envelope constructed
    //! during the most recent analysis performed by this Analyzer.
    //!
    //! By default, a fundamental envelope is estimated during analysis
    //! between the frequency resolution and 1.5 times the resolution.
    const LinearEnvelope & fundamentalEnv( void ) const;

    //! Return the overall amplitude estimate envelope constructed
    //! during the most recent analysis performed by this Analyzer.
    const LinearEnvelope & ampEnv( void ) const;
    
    
//  -- legacy support --
    
    //  Fundamental and amplitude envelopes are always constructed during
    //  analysis, these members do nothing, and are retained for backwards
    //  compatibility.
    void buildAmpEnv( bool TF = true ) { TF = TF; }
    void buildFundamentalEnv( bool TF = true ) { TF = TF; }

//  -- private member variables --

private:

    std::auto_ptr< Envelope > m_freqResolutionEnv;    
    							//!  in Hz, minimum instantaneous frequency distance;
                                //!  this is the core parameter, others are, by default,
                                //!  computed from this one
    
    double m_ampFloor;          //!  dB, relative to full amplitude sine wave, absolute
                                //!  amplitude threshold (negative)
    
    double m_windowWidth;       //!  in Hz, width of main lobe; this might be more
                                //!  conveniently presented as window length, but
                                //!  the main lobe width more explicitly highlights
                                //!  the critical interaction with resolution
    
    // std::auto_ptr< Envelope > m_freqFloorEnv; 
    double m_freqFloor;         //!  lowest frequency (Hz) component extracted
                                //!  in spectral analysis
    
    double m_freqDrift;         //!  the maximum frequency (Hz) difference between two 
                                //!  consecutive Breakpoints that will be linked to
                                //!  form a Partial
    
    double m_hopTime;           //!  in seconds, time between analysis windows in
                                //!  successive spectral analyses
    
    double m_cropTime;          //!  in seconds, maximum time correction for a spectral
                                //!  component to be considered reliable, and to be eligible
                                //!  for extraction and for Breakpoint formation
    
    double m_bwAssocParam;      //!  formerly, width in Hz of overlapping bandwidth 
                                //!  association regions, or zero if bandwidth association
                                //!  is disabled, now a catch-all bandwidth association
                                //!  parameter that, if negative, indicates the tolerance (%)
                                //!  level used to construct bandwidth envelopes from the
                                //!  mixed phase derivative indicator
                                                        
    double m_sidelobeLevel;     //!  sidelobe attenutation level for the Kaiser analysis 
                                //!  window, in positive dB
                                
    bool m_phaseCorrect;        //!  flag indicating that phases/frequencies should be
                                //!  made consistent at the end of the analysis
                            
    PartialList m_partials;     //!  collect Partials here
        
    //! builder object for constructing a fundamental frequency
    //! estimate during analysis
    std::auto_ptr< LinearEnvelopeBuilder > m_f0Builder;

    //! builder object for constructing an amplitude
    //! estimate during analysis
    std::auto_ptr< LinearEnvelopeBuilder > m_ampEnvBuilder;

//  -- private auxiliary functions --
//	future development
/*

	//	These members make up the sequence of operations in an
	//	analysis. If analysis were ever to be made into a 
	//	template method, these would be the operations that
	//	derived classes could override. Or each of these could
	//	be represented by a strategy class.

	//!	Compute the spectrum of the next sequence of samples.
	void computeSpectrum( void );
	
	//!	Identify and select the spectral components that will be
	//!	used to form Partials. 
	void selectPeaks( void );
	
	//!	Compute the bandwidth coefficients for the Breakpoints
	//!	that are going to be used to form Partials. 
	void associateBandwidth( void );
	
	//!	Construct Partials from extracted spectral components.
	//!	Partials are built up frame by frame by appending
	//!	Breakpoints to Partials under construction, and giving
	//!	birth to new Partials using unmatched Peaks.
	void formPartials( Peaks & peaks );
*/
    //  Reject peaks that are too close in frequency to a louder peak that is
    //  being retained, and peaks that are too quiet. Peaks that are retained,
    //  but are quiet enough to be in the specified fadeRange should be faded.
    //  
    //  Rejected peaks are placed at the end of the peak collection.
    //  Return the first position in the collection containing a rejected peak,
    //  or the end of the collection if no peaks are rejected.
    Peaks::iterator thinPeaks( Peaks & peaks, double frameTime  );
                
    //  Fix the bandwidth value stored in the specified Peaks. 
    //  This function is invoked if the spectral residue method is
    //  not used to compute bandwidth (that method overwrites the
    //  bandwidth already). If the convergence method is used to 
    //  compute bandwidth, the appropriate scaling is applied
    //  to the stored mixed phase derivative. Otherwise, the
    //  Peak bandwidth is set to zero.
    void fixBandwidth( Peaks & peaks );
                    
};  //  end of class Analyzer

}   //  end of namespace Loris

#endif /* ndef INCLUDE_ANALYZER_H */