[Feature]: Implement Mel-Filterbank and Mel-Spectrogram Computation

[gabyfle]

Initial Checklist

• I have searched the existing issues to ensure this feature has not already been requested.

Problem Statement & User Value

As a machine learning engineer, I want to convert standard audio spectrograms into a mel scale representation (mel-spectrogram), so that I can extract features for training deep learning models on tasks like speech recognition, audio classification, and music information retrieval.

Acceptance Criteria (Definition of Done)

Core Functionality

• A new function is available to generate the mel-filterbank matrix.
• A new function is available to convert a standard STFT spectrogram into a mel spectrogram using a pre-computed filterbank.
• A utility function power_to_db is available to convert a power spectrogram to a logarithmic (decibel) scale, which is a standard final step.

Parameterization & Configuration

• The function that creates the mel-filterbank matrix must support the following key parameters: sample_rate, n_fft, n_mels, f_min, and f_max.
• The implementation must support the two mel-scale formulations: the O'Shaughnessy/HTK scale and the Slaney scale, selectable via a parameter.
• The implementation must support two normalization schemes for the filterbank: peak normalization and Slaney-style area normalization.
• The function that converts a regular spectrogram into a mel-spectrogram must correctly handle both magnitude and power spectrogram inputs via a power parameter, defaulting to 2.0 to convert magnitude to power.
• The power_to_db function must include parameters for numerical stability (amin) and reference-level normalization (ref).

Validation & Correctness

• The output of the entire pipeline must be numerically equivalent (within an acceptable floating-point tolerance) to the output of librosa.feature.melspectrogram when configured with the Slaney scale and normalization.
• The output must be numerically equivalent to a reference HTK implementation (e.g., torchaudio's default) when configured with the HTK scale.
• Unit tests must be created for mel-scale conversion functions (hz_to_mel, mel_to_hz) for both HTK and Slaney scales.

Documentation

• All new public functions, types, and modules are documented with their purpose, parameters, default values, and return values.
• Documentation must clarify the difference between the HTK and Slaney scales and guide users on which to choose for compatibility with different ecosystems (e.g., torchaudio vs. librosa).

Proposed Solution or Technical Approach (Optional)

The new functionality should be housed into the Spectral module of SoundML.

• Type Definitions: To ensure type safety and clarity, we should define variant types for the primary configuration options:

type mel_scale = HTK | Slaney
type mel_norm = None | Slaney

• Filterbank Construction: We should try to maximize the use of vectorized operation with Rune. Additional +1 for JIT-compatible implementation. Big picture of the algorithm:
  • Calculate the center frequencies of the n_fft / 2 + 1 FFT bins from 0 Hz to the Nyquist frequency (sample_rate / 2).
  • Convert f_min and f_max from Hz to the selected mel scale (HTK or Slaney).
  • Create n_mels + 2 linearly spaced points in the mel domain between the mel-scaled min and max frequencies.
  • Convert these points back to Hz to serve as the start, center, and end points for the triangular filters.
  • For each of the n_mels filters, construct its triangular weights across all FFT frequency bins.
  • Apply the specified normalization scheme (None for peak=1.0, or Slaney for area normalization).
• Mel Spectrogram Computation: This is the simplest step as it require only a matrix multiplication.
  • First, the input STFT magnitude spectrogram is raised to the specified power (default 2.0) to get a power spectrogram.
  • The mel spectrogram is then computed via a single matrix multiplication of the filterbank matrix and the power spectrogram.
• Logarithmic Scaling (power_to_db): This utility function will apply the standard decibel conversion: 10 * log10(max(amin, S) / ref).

Additional Context (Mockups, Links, etc.)

No response

References

• Primary Reference (Slaney Scale): librosa.feature.melspectrogram - https://librosa.org/doc/main/generated/librosa.feature.melspectrogram.html
• Primary Reference (HTK Scale): torchaudio.transforms.MelSpectrogram -(https://pytorch.org/audio/main/generated/torchaudio.transforms.MelSpectrogram.html)
• Algorithmic Tutorial: "Speech Processing for Machine Learning: Filter Banks, Mel-Frequency Cepstral Coefficients (MFCCs) and What's In-Between" - https://haythamfayek.com/2016/04/21/speech-processing-for-machine-learning.html
• Theoretical Background: Mel Scale - Wikipedia - https://en.wikipedia.org/wiki/Mel_scale

Code of Conduct

• I agree to follow this project's Code of Conduct.