GitHub - worldveil/musical_mel_transform_torch: Musical mel transform for semi/quarter-tone features, written in ONNX-compatible PyTorch for audio AI neural networks

pip install musical-mel-transform

import torch
from musical_mel_transform import MusicalMelTransform

mel_transform = MusicalMelTransform(
    sample_rate=44100,            # Audio sample rate
    frame_size=2048,              # FFT size
    interval=1.0,                 # Musical interval in semitones
    f_min=None,                   # Minimum frequency (Hz)
    f_max=10_000,                 # Maximum frequency (Hz)
    passthrough_cutoff_hz=8_000,  # High-freq passthrough threshold
    norm=True,                    # Normalize filterbank
    min_bins=2,                   # Minimum filter width
    adaptive=True,                # Adaptive filter sizing
    passthrough_grouping_size=3,  # High-freq bin grouping
    use_conv_fft=True,            # Use convolution-based FFT
    learnable_weights="mel",      # What kind, if any, of learnable weights to use
    power=2,                      # which power to raise output to
    post_transform_type="db",     # "db", "log", "log1p", or None (raw)
)
batch_size, frame_size = 4, 2048
audio_frames = torch.randn(batch_size, frame_size)
mel_feats, fft_power = mel_transform.forward_frame(audio_frames)

import torch
from musical_mel_transform import MusicalMelTransform

mel_transform = MusicalMelTransform(
    sample_rate=44100,
    frame_size=2048,
    hop_size=512,                 # Required for waveform mode
    center=True,                  # Pad waveform for centered frames
    window_type="hann",
    window_periodic=True,         # Periodic window (STFT convention)
    post_transform_type="log",    # log(x + eps) scaling
)
waveform = torch.randn(1, 44100)   # [B, num_samples]
mel = mel_transform(waveform)       # [B, n_mel, num_frames]

import torch
import torch.nn as nn
from musical_mel_transform import MusicalMelTransform

class SimpleAudioClassifier(nn.Module):
    """Simple audio classifier using musical mel features"""
    def __init__(self, n_classes: int = 10):
        super().__init__()

        self.mel_transform = MusicalMelTransform(
            # sample rate in Hz
            sample_rate=44100,

            # number of samples to include / the size of the FFT
            frame_size=2048,

            # hop size and center are required for waveform-level forward()
            hop_size=512,
            center=True,

            # periodic hann window (matches torchaudio STFT convention)
            window_type="hann",
            window_periodic=True,

            # interval in semitones at which to place a mel bin
            interval=0.5,  # quarter tone resolution

            # the minimum frequency to capture. just leave this None
            # generally speaking. this transform will go as low as the
            # FFT num you've specified above will allow!
            f_min=None,

            # ignore FFT bins altogether above this frequency
            f_max=10_000,

            # between this frequency threshold and `f_max` simply 
            # let the FFT bins "pass through". this is useful because as
            # frequency increases, mel bins become spaced at *larger* 
            # intervals than FFT bins -- the opposite of low frequencies!
            passthrough_cutoff_hz=8_000,

            # dimensionality reduction technique. with passthrough FFT bins, 
            # there can be a lot of bins in upper freqs. this simply groups 
            # those bins together in ordered chunks. so a `passthrough_grouping_size=2`
            # would reduce your passthrough FFT bins by half. =1 would simply 
            # pass them all through, unchanged. 3 would reduce by 1/3 etc. 
            # the energy from the bins is simply summed into new result bin
            passthrough_grouping_size=3,

            # normalize each mel bin to unit weight?
            norm=True,

            # the minimum number of FFT bins to widen to in order to fill 
            # a mel bin. definitely want this >1, otherwise you'll 
            # just be copying nearest FFT bin!
            min_bins=2,

            # highly recommend this to be True. This does some adaptive 
            # widening to ensure that both high and low frequency bins 
            # have around the same "spread" to neighboring FFT bins
            adaptive=True,

            # this will slow down your network! but it will allow you to
            # export ONNX with dynamo=True and still have FFT. whenever 
            # onnx folks finally add complex number support this won't 
            # be needed anymore, but until then....
            use_conv_fft=True,

            # what kind, if any, learnable weights to use. Options are: 
            #   { None, "fft", "mel" }
            # if "fft", then a learnable parameter is used to 
            # elementwise multiply the raw  FFT bins before mel transform. 
            # if "mel", then elementwise multiply is after.
            # If None, then no reweighting is done and this transform has
            # no learnable parameters at all!
            learnable_weights="fft",

            # which power to raise magnitudes to. 1 is mag, 2 is power, etc
            power=2,

            # post transform type: "db", "log", "log1p", or None (raw)
            post_transform_type="log",
        )

        # Simple classifier head (pool over time, then classify)
        self.pool = nn.AdaptiveAvgPool1d(1)
        self.classifier = nn.Sequential(
            nn.Linear(self.mel_transform.n_mel, 128),
            nn.ReLU(),
            nn.Dropout(0.2),
            nn.Linear(128, n_classes)
        )

    def forward(self, waveform):
        """
        Args:
            waveform: [batch_size, num_samples] - raw audio waveform
        Returns:
            logits: [batch_size, n_classes] - Classification scores
        """
        mel = self.mel_transform(waveform)       # [B, n_mel, T]
        pooled = self.pool(mel).squeeze(-1)      # [B, n_mel]
        return self.classifier(pooled)

# Example usage
model = SimpleAudioClassifier(n_classes=10)

# Process a batch of 1-second audio clips
batch_size = 4
waveform = torch.randn(batch_size, 44100)

with torch.no_grad():
    predictions = model(waveform)
    print(f"Predictions shape: {predictions.shape}")  # [4, 10]

# Export to ONNX
torch.onnx.export(
    model,
    waveform,
    "audio_classifier.onnx",
    export_params=True,
    opset_version=18,
    input_names=['waveform'],
    output_names=['predictions'],
    dynamic_axes=None,  # I recommend this for best performance
)
print("Model exported to audio_classifier.onnx")

pip install musical-mel-transform

cd musical_mel_transform_torch/
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

source .venv/bin/activate
pytest tests/ -v

chromatic_transform = MusicalMelTransform(interval=1.0)
quarter_tone_transform = MusicalMelTransform(interval=0.5)

from musical_mel_transform import MusicalMelTransform, plot_low_filters

# Visualize the mel filterbank
transform = MusicalMelTransform()

plot_low_filters(
    transform,
    bank_idx_to_show=[0, 5, 10, 15, 20, 25],
    x_max_hz=1000,
    legend=True
)

# Run all demos
musical-mel-demo

# Run specific demos
musical-mel-demo --demo basic           # Basic usage
musical-mel-demo --demo params          # Parameter comparison
musical-mel-demo --demo filters         # Filterbank visualization
musical-mel-demo --demo performance     # Performance benchmarks
musical-mel-demo --demo onnx            # ONNX export
musical-mel-demo --demo musical         # Musical analysis

musical-mel-demo --demo plot_spectrums

musical-mel-demo --demo plot_spectrogram_comparison \
    --top-freq 250 \
    --segment-seconds 3

# or plot a comparison graph with your own music file! 
musical-mel-demo \
    --demo plot_spectrogram_comparison \
    --top-freq 250 \
    --segment-seconds 2 \
    --audio data/gummies.wav

# or, run all, but skip plot generation
musical-mel-demo --no-plots

# Run all tests
pytest

# Run with coverage
pytest --cov=musical_mel_transform --cov-report=html

# Run specific test categories
pytest tests/test_fft.py -v                    # FFT tests
pytest tests/test_onnx_export.py -v           # ONNX tests

# Run performance benchmarks
pytest tests/test_fft.py::test_exact_fft_transform_matches_torch_rfft -v
pytest tests/test_fft.py::test_exact_mel_transform_matches_torch_rfft -v

# Format code
black src/ tests/
isort src/ tests/

pip install --upgrade build twine

# 1) Bump version
# Edit src/musical_mel_transform/__init__.py (e.g., __version__ = "0.1.1")

# 2) Clean previous builds
rm -rf dist/ build/ *.egg-info

# 3) Build wheel and sdist
python -m build

# 4) Verify the artifacts
python -m twine check dist/*

# 5) (Optional) Upload to Test PyPI and verify install
python -m twine upload --repository testpypi dist/*
python -m pip install --index-url https://test.pypi.org/simple/ --no-deps musical-mel-transform

# 6) Upload to real PyPI
python -m twine upload dist/*

# 7) Verify works in a new env (if you want)
python -m venv .test_venv
source .test_venv/bin/activate
python -m pip install musical-mel-transform

MusicalMelTransform(
    sample_rate: int = 44100,              # Audio sample rate
    frame_size: int = 2048,                # FFT size / window length
    interval: float = 1.0,                 # Musical interval in semitones
    f_min: Optional[float] = None,         # Minimum frequency (Hz), default A0
    f_max: Optional[float] = None,         # Maximum frequency (Hz), default Nyquist
    passthrough_cutoff_hz: float = 20000,  # High-freq passthrough threshold
    norm: bool = True,                     # L1-normalize filterbank columns
    min_bins: int = 2,                     # Minimum filter width in FFT bins
    adaptive: bool = True,                 # Adaptive filter sizing
    passthrough_grouping_size: int = 3,    # High-freq bin grouping
    use_conv_fft: bool = False,            # Use ONNX-compatible convolutional FFT
    window_type: str = None,               # "hann", "hamming", or None (rectangular)
    learnable_weights: str = None,         # None, "fft", or "mel"
    power: int = 2,                        # Power exponent (1=magnitude, 2=power)
    post_transform_type: str = None,       # "db", "log", "log1p", or None (raw)
    hop_size: Optional[int] = None,        # Hop size for waveform mode forward()
    center: bool = True,                   # Pad waveform for centered frames
    window_periodic: bool = True,          # True=periodic (STFT), False=symmetric
)

ConvFFT(
    frame_size: int, # size of FFT
    window_type: str = {None, "hann", "hamming"}
)

@software{musical_mel_transform,
  title={Musical Mel Transform: PyTorch-based musical mel-frequency transform},
  author={Will Drevo},
  url={https://github.com/worldveil/musical_mel_transform_torch},
  year={2025}
}