#include <Analyzer.h>
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) |
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.
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/.
| Loris::Analyzer::Analyzer | ( | double | resolutionHz | ) | [explicit] |
| 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.
| 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.
| 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 | ) |
| const LinearEnvelope& Loris::Analyzer::ampEnv | ( | void | ) | const |
Return the overall amplitude estimate envelope constructed during the most recent analysis performed by this Analyzer. Will be empty unless buildAmpEnv was invoked to enable the construction of this envelope during analysis.
| 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.
| 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.
| 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).
| 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).
| 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.
| 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.
| resolutionEnv | is the time-varying frequency resolution in Hz. | |
| windowWidthHz | is the main lobe width of the Kaiser analysis window in Hz. |
| 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.
| resolutionHz | is the frequency resolution in Hz. | |
| windowWidthHz | is the main lobe width of the Kaiser analysis window in Hz. |
| 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.
| 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 |
| double Loris::Analyzer::freqFloor | ( | void | ) | const |
| 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.
| 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. Will be empty if fundamental estimation eas disabled.
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.
| 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.)
| TF | is a flag indicating whether or not to construct phase-corrected Partials |
| void Loris::Analyzer::setAmpFloor | ( | double | x | ) |
Set the amplitude floor (lowest detected spectral amplitude), in (negative) dB, for this Analyzer.
| 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.
| x | is the new value of this parameter. |
| void Loris::Analyzer::setFreqDrift | ( | double | x | ) |
| void Loris::Analyzer::setFreqFloor | ( | double | x | ) |
| 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.)
| 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.)
| 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.
| 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.)
| 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.
| 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.
| 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).
| 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.
| 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.
1.5.7