{"id":2392,"library":"asteroid-filterbanks","title":"Asteroid Filterbanks","description":"Asteroid's filterbanks is a Python library providing various filterbank implementations for audio signal processing within deep learning contexts, primarily using PyTorch. It is designed to be a modular toolkit for researchers working on audio source separation. The library is actively maintained with frequent updates, particularly concerning PyTorch compatibility, with the current version being 0.4.0.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/asteroid-team/asteroid-filterbanks","tags":["audio","signal-processing","deep-learning","pytorch","source-separation","filterbanks","dsp"],"install":[{"cmd":"pip install asteroid-filterbanks","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Core deep learning framework for all operations. Version compatibility is crucial.","package":"torch","optional":false}],"imports":[{"note":"Main classes for defining, encoding, and decoding with filterbanks.","symbol":"Filterbank, Encoder, Decoder","correct":"from asteroid_filterbanks.enc_dec import Filterbank, Encoder, Decoder"},{"note":"Commonly used predefined filterbank types.","symbol":"FreeFB, STFTFB, ParamSincFB, MelGram","correct":"from asteroid_filterbanks import FreeFB, STFTFB, ParamSincFB, MelGram"},{"note":"Per-Channel Energy Normalization module.","symbol":"PCEN","correct":"from asteroid_filterbanks.pcen import PCEN"},{"note":"Utility function to create congruent encoder/decoder pairs.","symbol":"make_enc_dec","correct":"from asteroid_filterbanks.enc_dec import make_enc_dec"}],"quickstart":{"code":"import torch\nfrom asteroid_filterbanks.enc_dec import Encoder, Decoder\nfrom asteroid_filterbanks import FreeFB\n\n# Define parameters for the filterbank\nn_filters = 256\nkernel_size = 128\nstride = 64\nsample_rate = 16000\n\n# 1. Instantiate a filterbank (e.g., a fully learnable Free Filterbank)\nfb = FreeFB(n_filters=n_filters, kernel_size=kernel_size, stride=stride, sample_rate=sample_rate)\n\n# 2. Wrap it with an Encoder to get the time-frequency representation\nencoder = Encoder(fb)\n\n# 3. Create a dummy waveform (batch, channels, time)\nwaveform = torch.randn(1, 1, sample_rate * 4) # 4 seconds of audio\n\n# 4. Encode the waveform into a spectrogram-like representation\nspec_like = encoder(waveform)\nprint(f\"Input waveform shape: {waveform.shape}\")\nprint(f\"Encoded spectrogram-like shape: {spec_like.shape}\")\n\n# 5. Instantiate a Decoder (can use the same filterbank or a different one)\ndecoder = Decoder(fb) # For reconstruction, often use the same filterbank\n\n# 6. Decode the spectrogram-like representation back to waveform\nout_waveform = decoder(spec_like)\nprint(f\"Decoded waveform shape: {out_waveform.shape}\")","lang":"python","description":"This quickstart demonstrates how to instantiate a `FreeFB` filterbank, wrap it with an `Encoder` to transform a waveform into a time-frequency representation, and then use a `Decoder` to reconstruct the waveform. This is a common pattern for learnable front-ends in audio processing models."},"warnings":[{"fix":"Upgrade PyTorch to version 1.8.0 or newer (e.g., `pip install torch>=1.8.0`).","message":"Version 0.4.0 drops support for PyTorch versions older than 1.8.0. Ensure your PyTorch installation is `torch>=1.8.0`.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Update code to handle complex number outputs from `torch.fft` (e.g., using `abs()` or `torch.view_as_real()` if magnitude/phase is needed) and retrain models if necessary to adapt to the new FFT behavior.","message":"Beginning with version 0.3.1, the library moved from `torch.rfft` (deprecated and removed in newer PyTorch versions) to `torch.fft`. This change affects the output format, which now consistently returns complex numbers, potentially breaking models trained with older versions or assumptions.","severity":"breaking","affected_versions":">=0.3.1"},{"fix":"To create a custom filterbank, inherit from `asteroid_filterbanks.Filterbank` and implement its abstract methods. Then, instantiate `Encoder(my_custom_filterbank_instance)` or `Decoder(my_custom_filterbank_instance)`.","message":"The `Encoder` and `Decoder` classes are wrappers designed to augment `Filterbank` instances with encoding/decoding methods. They are not intended to be subclassed directly for implementing new filterbanks; instead, subclass `Filterbank` and then wrap it.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult the `make_enc_dec` documentation for correct usage of `who_is_pinv` (e.g., 'encoder', 'decoder') or manually set `is_pinv=True` on the appropriate wrapper if building the pair separately.","message":"When using `asteroid_filterbanks.enc_dec.make_enc_dec` or manually setting up `Encoder` and `Decoder` for reconstruction, pay close attention to the `is_pinv` and `who_is_pinv` parameters if you intend one to be the pseudo-inverse of the other.","severity":"gotcha","affected_versions":"All"},{"fix":"After installation, explicitly restart the kernel or Python process if you encounter import errors.","message":"If performing a development installation (`pip install -e .`) or installing `asteroid` (which includes `asteroid-filterbanks`), you might need to restart your Python runtime (especially in notebooks like Jupyter or Colab) for `asteroid_filterbanks` modules to import correctly.","severity":"gotcha","affected_versions":"All"},{"fix":"Thoroughly test `TorchSTFTFB` with your specific `torch.stft` parameters if ONNX export or exact matching is critical, and review its documentation for current limitations.","message":"The `TorchSTFTFB` filterbank aims to replicate `torch.stft` behavior for ONNX compatibility, but it may not cover all options and edge cases of `torch.stft`. Be cautious when expecting perfect equivalence for all configurations.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}