Loris::Analyzer Class Reference

#include <Analyzer.h>

List of all members.

Public Types

enum  { Default_ResidueBandwidth_RegionWidth = 2000, Default_ConvergenceBandwidth_TolerancePct = 10 }
enum  { Default_FundamentalEnv_ThreshDb = -60, Default_FundamentalEnv_ThreshHz = 8000 }

Public Member Functions

 Analyzer (double resolutionHz)
 Analyzer (double resolutionHz, double windowWidthHz)
 Analyzer (const Envelope &resolutionEnv, double windowWidthHz)
 Analyzer (const Analyzer &other)
 ~Analyzer (void)
 Destroy this Analyzer.
Analyzer & operator= (const Analyzer &rhs)
void configure (double resolutionHz)
void configure (double resolutionHz, double windowWidthHz)
void configure (const Envelope &resolutionEnv, double windowWidthHz)
void analyze (const std::vector< double > &vec, double srate)
void analyze (const double *bufBegin, const double *bufEnd, double srate)
void analyze (const std::vector< double > &vec, double srate, const Envelope &reference)
void analyze (const double *bufBegin, const double *bufEnd, double srate, const Envelope &reference)
double ampFloor (void) const
double cropTime (void) const
double freqDrift (void) const
double freqFloor (void) const
double freqResolution (double time=0.0) const
double hopTime (void) const
double sidelobeLevel (void) const
double windowWidth (void) const
bool phaseCorrect (void) const
void setAmpFloor (double x)
void setCropTime (double x)
void setFreqDrift (double x)
void setFreqFloor (double x)
void setFreqResolution (double x)
void setFreqResolution (const Envelope &e)
void setHopTime (double x)
void setSidelobeLevel (double x)
void setWindowWidth (double x)
void setPhaseCorrect (bool TF=true)
void storeResidueBandwidth (double regionWidth=Default_ResidueBandwidth_RegionWidth)
void storeConvergenceBandwidth (double tolerancePct=0.01 *(double) Default_ConvergenceBandwidth_TolerancePct)
void storeNoBandwidth (void)
bool bandwidthIsResidue (void) const
bool bandwidthIsConvergence (void) const
double bwRegionWidth (void) const
double bwConvergenceTolerance (void) const
bool associateBandwidth (void) const
void setBwRegionWidth (double x)
 Deprecated, use storeResidueBandwidth or storeNoBandwidth instead.
PartialList & partials (void)
const PartialList & partials (void) const
void buildFundamentalEnv (double fmin, double fmax, double threshDb=Default_FundamentalEnv_ThreshDb, double threshHz=Default_FundamentalEnv_ThreshHz)
const LinearEnvelope & fundamentalEnv (void) const
const LinearEnvelope & ampEnv (void) const
void buildAmpEnv (bool TF=true)
void buildFundamentalEnv (bool TF=true)

Detailed Description

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.

See also:
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/.

Constructor & Destructor Documentation

Loris::Analyzer::Analyzer ( double  resolutionHz  )  [explicit]

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.

Parameters:
resolutionHz is the frequency resolution in Hz.
Loris::Analyzer::Analyzer ( double  resolutionHz,
double  windowWidthHz 
)

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.

Parameters:
resolutionHz is the frequency resolution in Hz.
windowWidthHz is the main lobe width of the Kaiser analysis window in Hz.
Loris::Analyzer::Analyzer ( const Envelope &  resolutionEnv,
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.

Parameters:
resolutionHz is the frequency resolution in Hz.
windowWidthHz is the main lobe width of the Kaiser analysis window in Hz.
Loris::Analyzer::Analyzer ( const Analyzer &  other  ) 

Construct a new Analyzer having identical parameter configuration to another Analyzer. The list of collected Partials is not copied.

Parameters:
other is the Analyzer to copy.

Member Function Documentation

const LinearEnvelope& Loris::Analyzer::ampEnv ( void   )  const

Return the overall amplitude estimate envelope constructed during the most recent analysis performed by this Analyzer.

double Loris::Analyzer::ampFloor ( void   )  const

Return the amplitude floor (lowest detected spectral amplitude), in (negative) dB, for this Analyzer.

void Loris::Analyzer::analyze ( const double *  bufBegin,
const double *  bufEnd,
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.

Parameters:
bufBegin is a pointer to a buffer of floating point samples
bufEnd is (one-past) the end of a buffer of floating point samples
srate is the sample rate of the samples in the buffer
reference is an Envelope having the approximate frequency contour expected of the resulting Partials.
void Loris::Analyzer::analyze ( const std::vector< double > &  vec,
double  srate,
const Envelope &  reference 
)

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.

Parameters:
vec is a vector of floating point samples
srate is the sample rate of the samples in the vector
reference is an Envelope having the approximate frequency contour expected of the resulting Partials.
void Loris::Analyzer::analyze ( const double *  bufBegin,
const double *  bufEnd,
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).

Parameters:
bufBegin is a pointer to a buffer of floating point samples
bufEnd is (one-past) the end of a buffer of floating point samples
srate is the sample rate of the samples in the buffer
void Loris::Analyzer::analyze ( const std::vector< double > &  vec,
double  srate 
)

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).

Parameters:
vec is a vector of floating point samples
srate is the sample rate of the samples in the vector
bool Loris::Analyzer::associateBandwidth ( void   )  const [inline]

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 Loris::Analyzer::bandwidthIsConvergence ( void   )  const

Return true if this Analyzer is configured to compute bandwidth envelopes using the mixed derivative convergence indicator, and false otherwise.

bool Loris::Analyzer::bandwidthIsResidue ( void   )  const

Return true if this Analyzer is configured to compute bandwidth envelopes using the spectral residue after peaks have been identified, and false otherwise.

void Loris::Analyzer::buildFundamentalEnv ( double  fmin,
double  fmax,
double  threshDb = Default_FundamentalEnv_ThreshDb,
double  threshHz = Default_FundamentalEnv_ThreshHz 
)

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.

Parameters:
fmin is the lower bound on the fundamental frequency estimate
fmax is the upper bound on the fundamental frequency estimate
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.
threshHz is the upper bound on the frequency of a spectral peak that will constribute to the fundamental frequency estimate. Default is 8 kHz.
double Loris::Analyzer::bwConvergenceTolerance ( 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 Loris::Analyzer::bwRegionWidth ( 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.

void Loris::Analyzer::configure ( const Envelope &  resolutionEnv,
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.

Parameters:
resolutionEnv is the time-varying frequency resolution in Hz.
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 Loris::Analyzer::configure ( double  resolutionHz,
double  windowWidthHz 
)

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.

Parameters:
resolutionHz is the frequency resolution in Hz.
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 Loris::Analyzer::configure ( double  resolutionHz  ) 

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.

Parameters:
resolutionHz is the frequency resolution in Hz.
double Loris::Analyzer::cropTime ( 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 Loris::Analyzer::freqDrift ( void   )  const

Return the maximum allowable frequency difference between consecutive Breakpoints in a Partial envelope for this Analyzer.

double Loris::Analyzer::freqFloor ( void   )  const

Return the frequency floor (minimum instantaneous Partial frequency), in Hz, for this Analyzer.

double Loris::Analyzer::freqResolution ( double  time = 0.0  )  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.

Parameters:
time is the time in seconds at which to evaluate the frequency resolution
const LinearEnvelope& Loris::Analyzer::fundamentalEnv ( void   )  const

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.

double Loris::Analyzer::hopTime ( void   )  const

Return the hop time (which corresponds approximately to the average density of Partial envelope Breakpoint data) for this Analyzer.

Analyzer& Loris::Analyzer::operator= ( const Analyzer &  rhs  ) 

Construct a new Analyzer having identical parameter configuration to another Analyzer. The list of collected Partials is not copied.

Parameters:
rhs is the Analyzer to copy.
const PartialList& Loris::Analyzer::partials ( void   )  const

Return an immutable (const) reference to this Analyzer's list of analyzed Partials.

PartialList& Loris::Analyzer::partials ( void   ) 

Return a mutable reference to this Analyzer's list of analyzed Partials.

bool Loris::Analyzer::phaseCorrect ( 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.)

void Loris::Analyzer::setAmpFloor ( double  x  ) 

Set the amplitude floor (lowest detected spectral amplitude), in (negative) dB, for this Analyzer.

Parameters:
x is the new value of this parameter.
void Loris::Analyzer::setCropTime ( 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.

Parameters:
x is the new value of this parameter.
void Loris::Analyzer::setFreqDrift ( double  x  ) 

Set the maximum allowable frequency difference between consecutive Breakpoints in a Partial envelope for this Analyzer.

Parameters:
x is the new value of this parameter.
void Loris::Analyzer::setFreqFloor ( double  x  ) 

Set the frequency floor (minimum instantaneous Partial frequency), in Hz, for this Analyzer.

Parameters:
x is the new value of this parameter.
void Loris::Analyzer::setFreqResolution ( const Envelope &  e  ) 

Set the time-varying frequency resolution (minimum instantaneous frequency difference between Partials) for this Analyzer. (Does not cause other parameters to be recomputed.)

Parameters:
e is the envelope to copy for this parameter.
void Loris::Analyzer::setFreqResolution ( double  x  ) 

Set the frequency resolution (minimum instantaneous frequency difference between Partials) for this Analyzer. (Does not cause other parameters to be recomputed.)

Parameters:
x is the new value of this parameter.
void Loris::Analyzer::setHopTime ( double  x  ) 

Set the hop time (which corresponds approximately to the average density of Partial envelope Breakpoint data) for this Analyzer.

Parameters:
x is the new value of this parameter.
void Loris::Analyzer::setPhaseCorrect ( bool  TF = true  ) 

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.)

Parameters:
TF is a flag indicating whether or not to construct phase-corrected Partials
void Loris::Analyzer::setSidelobeLevel ( 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.

Parameters:
x is the new value of this parameter.
void Loris::Analyzer::setWindowWidth ( double  x  ) 

Set the frequency-domain main lobe width (measured between zero-crossings) of the analysis window used by this Analyzer.

Parameters:
x is the new value of this parameter.
double Loris::Analyzer::sidelobeLevel ( 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.

void Loris::Analyzer::storeConvergenceBandwidth ( double  tolerancePct = 0.01 *(double) Default_ConvergenceBandwidth_TolerancePct  ) 

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).

Parameters:
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 Loris::Analyzer::storeNoBandwidth ( void   ) 

Disable bandwidth envelope construction. Bandwidth will be zero for all Breakpoints in all Partials.

void Loris::Analyzer::storeResidueBandwidth ( double  regionWidth = Default_ResidueBandwidth_RegionWidth  ) 

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.

Parameters:
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.
double Loris::Analyzer::windowWidth ( void   )  const

Return the frequency-domain main lobe width (measured between zero-crossings) of the analysis window used by this Analyzer.

The documentation for this class was generated from the following file:
Generated by  doxygen 1.6.2