diff --git a/Source/TransformFunctions/arm_mfcc_f16.c b/Source/TransformFunctions/arm_mfcc_f16.c
index 2fd668f7..5caaa06d 100755
--- a/Source/TransformFunctions/arm_mfcc_f16.c
+++ b/Source/TransformFunctions/arm_mfcc_f16.c
@@ -50,6 +50,41 @@
MFCC Transform
There are separate functions for floating-point, Q15, and Q31 data types.
+
+ @par Processing convention
+ Each call processes one frame whose length is the configured FFT length. The
+ function applies the configured window, computes the FFT magnitude, applies
+ the configured Mel filter bank, takes the natural logarithm after adding a
+ data-type-specific positive floor, and multiplies the result by the configured
+ DCT matrix.
+
+ The Mel filters operate on the magnitude spectrum, not the squared magnitude
+ (power spectrum). When comparing with an API that exposes a power exponent,
+ use power=1.0.
+
+ The window, Mel filter bank, and DCT matrix are supplied during instance
+ initialization, so the MFCC functions do not impose a particular window,
+ Mel-scale normalization, DCT type, or DCT normalization. Comparisons with
+ another MFCC implementation must use the same coefficient arrays.
+
+ The cmsisdsp.mfcc Python helper generates triangular filters on
+ the HTK Mel scale
+
+ \f[
+ m(f) = 1127 \ln\left(1 + \frac{f}{700}\right)
+ \f]
+
+ without area normalization. Its DCT helper generates a type-II matrix. For
+ M Mel filters, its entries are
+
+ \f[
+ D_{k,n} = \sqrt{\frac{2}{M}}
+ \cos\left(\frac{\pi k(n + 1/2)}{M}\right).
+ \f]
+
+ The factor \f$\sqrt{2/M}\f$ is applied to every row, including
+ k=0. This differs from an orthonormal DCT-II, whose first row uses
+ \f$\sqrt{1/M}\f$.
*/
diff --git a/cmsisdsp/mfcc.py b/cmsisdsp/mfcc.py
index 2ec2b9a5..e0b2701c 100755
--- a/cmsisdsp/mfcc.py
+++ b/cmsisdsp/mfcc.py
@@ -3,7 +3,9 @@
def frequencyToMelSpace(freq):
"""
- Convert a frequency in Hz to Mel space value
+ Convert a frequency in Hz to an HTK Mel-space value.
+
+ The conversion is ``1127 * log(1 + freq / 700)``.
:param freq: Frequency in Hz.
:type freq: float
@@ -27,7 +29,11 @@ def melSpaceToFrequency(mels):
def melFilterMatrix(dtype,fmin, fmax, numOfMelFilters,fs,FFTSize):
"""
- Sparse matrix in a specific format and encoding the filters in Mel space
+ Generate a sparse matrix encoding triangular filters in Mel space.
+
+ Filter centers are equally spaced on the HTK Mel scale. The triangular
+ weights are evaluated at the FFT bin center frequencies and are not area
+ normalized.
:param dtype: The datatype to use for the matrix coefficients.
:type dtype: int
@@ -91,7 +97,12 @@ def melFilterMatrix(dtype,fmin, fmax, numOfMelFilters,fs,FFTSize):
def dctMatrix(dtype,numOfDctOutputs, numOfMelFilters):
"""
- Dct matrix in a specific format
+ Generate the type-II DCT matrix used by the MFCC helper.
+
+ For ``M = numOfMelFilters``, element ``(k, n)`` is
+ ``sqrt(2 / M) * cos(pi * k * (n + 0.5) / M)``. The ``sqrt(2 / M)``
+ factor is applied to every row, including ``k = 0``. This differs from an
+ orthonormal DCT-II, whose first row is scaled by ``sqrt(1 / M)``.
:param dtype: The datatype to use for the matrix coefficients.
:type dtype: int