diff --git a/release-packaging/HelpSource/Classes/FluidMFCC.schelp b/release-packaging/HelpSource/Classes/FluidMFCC.schelp index 0323617..a54a5a0 100644 --- a/release-packaging/HelpSource/Classes/FluidMFCC.schelp +++ b/release-packaging/HelpSource/Classes/FluidMFCC.schelp @@ -1,55 +1,146 @@ TITLE:: FluidMFCC SUMMARY:: Mel-Frequency Cepstral Coefficients as Spectral Descriptors in Real-Time CATEGORIES:: Libraries>FluidCorpusManipulation -RELATED:: Guides/FluidCorpusManipulation, Classes/FluidMelBands - +RELATED:: Classes/FluidBufMFCC,Classes/FluidPitch,Classes/FluidMelBands,Classes/FluidLoudness,Classes/FluidSpectralShape,Guides/FluidCorpusManipulationToolkit DESCRIPTION:: -This class implements a classic spectral descriptor, the Mel-Frequency Cepstral Coefficients (https://en.wikipedia.org/wiki/Mel-frequency_cepstrum). The input is first filtered in to STRONG::numBands:: perceptually-spaced bands, as in LINK::Classes/FluidMelBands::. It is then analysed into STRONG::numCoeffs:: number of cepstral coefficients. It has the avantage of being amplitude invarient, except for the first coefficient. It is part of the LINK:: Guides/FluidCorpusManipulation##Fluid Corpus Manipulation Toolkit::. For more explanations, learning material, and discussions on its musicianly uses, visit http://www.flucoma.org/ -The process will return a multichannel control steam of STRONG::maxNumCoeffs::, which will be repeated if no change happens within the algorythm, i.e. when the hopSize is larger than the server's kr period. + + This class implements a classic spectral descriptor, the Mel-Frequency Cepstral Coefficients (MFCCs) + + + + See LINK::https://en.wikipedia.org/wiki/Mel-frequency_cepstrum::. The input is first decomposed into perceptually spaced bands (the number of bands specified by numBands), just as in the MelBands object. It is then analysed in numCoefs number of cepstral coefficients. It has the avantage to be amplitude invarient, except for the first coefficient. + + The process will return a multichannel control steam of maxNumCoeffs, which will be repeated if no change happens within the algorithm, i.e. when the hopSize is larger than the host vector size. + CLASSMETHODS:: METHOD:: kr - The audio rate in, control rate out version of the object. ARGUMENT:: in - The audio to be processed. + + Audio-rate signal to analyze ARGUMENT:: numCoeffs - The number of cepstral coefficients to be outputed. It is limited by the maxNumCoeffs parameter. When the number is smaller than the maximum, the output is zero-padded. + + + The number of cepstral coefficients to be outputed. It is limited by the maxNumCoefs parameter. When the number is smaller than the maximum, the output is zero-padded. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 2 + + ## + Maximum: MIN(CODE::numBands::, CODE::maxNumCoeffs::) + + :: ARGUMENT:: numBands - The number of bands that will be perceptually equally distributed between minFreq and maxFreq to describe the spectral shape before it is converted to cepstral coefficients. + + + The number of bands that will be perceptually equally distributed between minFreq and maxFreq to describe the spectral shape before it is converted to cepstral coefficients. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: MAX(CODE::numCoeffs::, 2) + + ## + Maximum: CODE::(FFT Size / 2) + 1:: (see fft settings) + + :: ARGUMENT:: startCoeff - The lowest index of the output cepstral coefficient, zero-counting. + + + The lowest index of the output cepstral coefficient, zero-counting. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + ## + Maximum: 1 + + :: ARGUMENT:: minFreq - The lower boundary of the lowest band of the model, in Hz. + + + The lower boundary of the lowest band of the model, in Hz. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: ARGUMENT:: maxFreq - The highest boundary of the highest band of the model, in Hz. + + + The highest boundary of the highest band of the model, in Hz. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: ARGUMENT:: windowSize - The window size. As MFCC computation relies on spectral frames, we need to decide what precision we give it spectrally and temporally, in line with Gabor Uncertainty principles. http://www.subsurfwiki.org/wiki/Gabor_uncertainty + + + The window size. As MFCC computation relies on spectral frames, we need to decide what precision we give it spectrally and temporally, in line with Gabor Uncertainty principles. LINK::http://www.subsurfwiki.org/wiki/Gabor_uncertainty:: + ARGUMENT:: hopSize - The window hop size. As MFCC computation relies on spectral frames, we need to move the window forward. It can be any size but low overlap will create audible artefacts. The -1 default value will default to half of windowSize (overlap of 2). + + + The window hop size. As MFCC computation relies on spectral frames, we need to move the window forward. It can be any size but low overlap will create audible artefacts. The -1 default value will default to half of windowSize (overlap of 2). + ARGUMENT:: fftSize - The inner FFT/IFFT size. It should be at least 4 samples long, at least the size of the window, and a power of 2. Making it larger allows an oversampling of the spectral precision. The -1 default value will use the next power of 2 equal or above the windowSize. -ARGUMENT:: maxFFTSize - How large can the FFT be, by allocating memory at instantiation time. This cannot be modulated. + + The inner FFT/IFFT size. It should be at least 4 samples long, at least the size of the window, and a power of 2. Making it larger allows an oversampling of the spectral precision. The -1 default value will default to windowSize. + + ARGUMENT:: maxNumCoeffs - The maximum number of cepstral coefficients that can be computed. This sets the number of channels of the output, and therefore cannot be modulated. -RETURNS:: - A KR signal of STRONG::maxNumCoeffs:: channels. The latency is windowSize. + + The maximum number of cepstral coefficients that can be computed. This sets the number of channels of the output, and therefore cannot be modulated. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 2 + + ## + Maximum: (max FFFT Size / 2) + 1`` (see maxFFTSize) + + :: + +ARGUMENT:: maxFFTSize + + + How large can the FFT be, by allocating memory at instantiation time. This cannot be modulated. + + +INSTANCEMETHODS:: + EXAMPLES:: code::