Add matchboxnet
Author: Panga-az
Pull request: yes

# What does this PR do?

This PR adds a new audio classification model: MatchboxNet, implementing the 1D Time-Channel Separable Convolutional Neural Network architecture for keyword spotting / speech commands recognition as described in the paper:
> MatchboxNet: 1D Time-Channel Separable Convolutional Neural Network Architecture for Speech Commands Recognition  
> https://arxiv.org/abs/2004.08531

Specifically, it introduces:
- `MatchboxConfig` (`configuration_matchboxnet.py`) to store hyperparameters (input_channels, num_classes, B, R, C, kernel_sizes, MFCC settings, etc.).
- `MatchboxFeatureExtractor` (`feature_extraction_matchboxnet.py`) to extract MFCC features via torchaudio, pad/truncate to fixed length.
- `MatchboxForAudioClassification` (`modeling_matchboxnet.py`) wrapping the MatchboxNet PyTorch module into a `PreTrainedModel` for HF Trainer/pipeline compatibility.
- Auto mappings:
  - In `modeling_auto.py`: import `MatchboxConfig`, `MatchboxForAudioClassification` and add to `MODEL_FOR_AUDIO_CLASSIFICATION_MAPPING` and `MODEL_FOR_AUDIO_CLASSIFICATION_MAPPING_NAMES`.
  - In `feature_extraction_auto.py`: import `MatchboxConfig`, `MatchboxFeatureExtractor` and add to `FEATURE_EXTRACTOR_MAPPING`.
  - In `configuration_auto.py`: add `"matchboxnet": "MatchboxConfig"` to `CONFIG_MAPPING_NAMES`, and map `MatchboxConfig` accordingly.
- Tests under `tests/models/matchboxnet/` covering:
  - Configuration serialization/deserialization.
  - Feature extractor output shape and save/load.
  - Model forward, loss/backward with minimal sizes.
  - Pipeline audio-classification end-to-end on random input.
- Updates to the top-level mapping imports in `src/transformers/models/auto/...`.

No existing issue was open; this is a new feature addition.

## Before submitting

- [x] This PR adds new model code, docs, and tests, not only a typo/docs fix.
- [x] I have read the [contributor guideline](https://github.com/huggingface/transformers/blob/main/CONTRIBUTING.md#create-a-pull-request), Pull Request section.
- [ ] (Optionally) If there was an existing discussion, link it here.  
       For now, no issue was opened beforehand; feedback on design is welcome.
- [x] Documentation is coming soon.
- [x] New necessary tests are added under `tests/models/matchboxnet/`.
- [x] Code is formatted with `black`/linted.
- [x] I have run the full test suite locally (`pytest`) and all tests pass.

## Who can review?

Anyone in the community is free to review once tests have passed. For speech/audio models, you may tag:
- @eustlb  (speech models)
- @SunMarc (Trainer/Accelerate)
- @Rocketknight1 (pipelines)  
Feel free to suggest others if relevant.

---

### Additional context / Motivation

MatchboxNet is lightweight and efficient for keyword spotting, and it complements the existing audio models (e.g., Wav2Vec2, Whisper). By integrating it into Transformers:
- Users can train custom keyword-spotting tasks with HF Trainer easily.
- The feature extractor handles MFCCs transparently.
- The model is available via `AutoModelForAudioClassification` and `pipeline("audio-classification")`.
- It enriches the HF audio model zoo for on-device or low-resource settings.

No extra dependencies beyond existing ones (`torch`, `torchaudio`, `transformers`, `datasets`, `numpy`) are introduced.

---

### Files changed

- `src/transformers/models/matchboxnet/configuration_matchboxnet.py`
- `src/transformers/models/matchboxnet/feature_extraction_matchboxnet.py`
- `src/transformers/models/matchboxnet/modeling_matchboxnet.py`
- `src/transformers/models/matchboxnet/__init__.py`
- `src/transformers/__init__.py`
- `src/transformers/models/auto/configuration_auto.py` (add `"matchboxnet"`)
- `src/transformers/models/auto/modeling_auto.py` (map MatchboxNetConfig → MatchboxNetForAudioClassification)
- `src/transformers/models/auto/feature_extraction_auto.py` (map MatchboxNetConfig → MatchboxNetForAudioClassification)
- `tests/models/matchboxnet/test_configuration_matchboxnet.py`
- `tests/models/matchboxnet/test_feature_extraction_matchboxnet.py`
- `tests/models/matchboxnet/test_modeling_matchboxnet.py`
- `tests/models/matchboxnet/test_pipeline_matchboxnet.py`

---

### How to test locally

1. **Install editable**:
   ```bash
   pip install -e .


Comments:
Hey @Panga-az, any specific reasons why you closed this PR?

> Hey @Panga-az, any specific reasons why you closed this PR?

Hey, Hmm the code wasn't enough for my liking, I'm still working on it, in the week I'll make another PR.

What are the motivations for adding this model to Transformers? Have you received any community signals suggesting it would gain traction? The model seems a bit outdated and niche, and I’m concerned that the integration and ongoing maintenance effort may not be worthwhile. Perhaps uploading the weights to the Hub with remote code would be a better solution in this case.

May be yeah, Currently I am a little bit interested in embedded system, so
when I saw Matchboxnet paper, I was interested in the paper, I implemented
it and I tested it on a dataset to recognize 3 labels (awכ, ayi and foyi)
which mean respectively (yes, no, nothing). And I had good results when I
tested it in the real world. Also I am working on ASR models for our
low-resource local languages. And also I am planning to do some fine-tuning
of of our ASR models for Bambara with Matchboxnet either for speech command
recognition or classification or keyword spotting, wake world. By doing
this, the models would be small and could be used in embedded systems.
These are largely my motivations.

On Mon, Jun 30, 2025, 10:20 AM eustlb ***@***.***> wrote:

> *eustlb* left a comment (huggingface/transformers#39025)
> <https://github.com/huggingface/transformers/pull/39025#issuecomment-3018603671>
>
> What are the motivations for adding this model to Transformers? Have you
> received any community signals suggesting it would gain traction? The model
> seems a bit outdated and niche, and I’m concerned that the integration and
> ongoing maintenance effort may not be worthwhile. Perhaps uploading the
> weights to the Hub with remote code would be a better solution in this case.
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/huggingface/transformers/pull/39025#issuecomment-3018603671>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AQ2DD5JX7YVXGJQO67JSEKD3GEFQTAVCNFSM6AAAAACACCQAH6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTAMJYGYYDGNRXGE>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>


Okay, I get that, thanks. Then I think the remote code option is more suitable!

Thanks too. I got it.

On Mon, Jun 30, 2025, 12:49 PM eustlb ***@***.***> wrote:

> *eustlb* left a comment (huggingface/transformers#39025)
> <https://github.com/huggingface/transformers/pull/39025#issuecomment-3019028565>
>
> Okay, I get that, thanks. Then I think the remote code option is more
> suitable!
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/huggingface/transformers/pull/39025#issuecomment-3019028565>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AQ2DD5N6HDXDFU7AY67YNVT3GEW5VAVCNFSM6AAAAACACCQAH6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTAMJZGAZDQNJWGU>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>