| --- |
| license: mit |
| language: en |
| tags: |
| - audio-classification |
| - keyword-spotting |
| - tinyml |
| - pytorch |
| datasets: |
| - speech_commands |
| metrics: |
| - accuracy |
| - f1 |
| --- |
| |
| # tiny-kws — DS-CNN keyword spotter (12-class Speech Commands v2) |
|
|
| A 119,372-parameter (~0.48 MB fp32) depthwise-separable CNN for spoken |
| command recognition, trained from scratch in PyTorch. Input: 1-second 16 kHz |
| audio → 64×101 log-mel spectrogram. Output: one of 12 classes — the keywords |
| *yes, no, up, down, left, right, on, off, stop, go*, plus *unknown* and |
| *silence*. |
|
|
| - **Architecture**: DS-CNN (Zhang et al. 2017, arXiv:1711.07128): 10×4 |
| conv stem (stride 2) → 4 depthwise-separable blocks (160 ch, one stride-2) |
| → global average pooling → dropout 0.2 → linear. |
| - **Dataset**: Google Speech Commands v0.02 (Warden 2018, arXiv:1804.03209, |
| CC-BY-4.0): 105,829 one-second utterances, 35 words. Official |
| validation/testing lists (speaker-disjoint); "unknown" = seeded 10% sample |
| of the 25 non-keyword words; "silence" = background-noise crops. |
| - **Training**: 30 epochs on a free Colab T4 (GPU), AdamW lr 3e-3 |
| (cosine-annealed), batch 128, label smoothing 0.1, fp32. Best validation |
| accuracy 96.15% at epoch 30. Augmentation: ±100 ms time-shift + |
| background-noise mixing (p=0.8, vol U(0,0.1)). |
| - **Features**: log-mel, 64 mels, 25 ms window / 10 ms hop, normalized by |
| train-set global mean/std (stored inside the checkpoint). |
|
|
| ## Evaluation — official Speech Commands v2 test set (4,890 clips) |
|
|
| <!-- METRICS_TABLE: produced by evaluate.py, never hand-written --> |
| | metric | value | |
| |---|---| |
| | accuracy | 96.65% | |
| | macro-F1 | 96.64% | |
| | CPU latency (batch=1, 1 thread, Apple M2) | 1.90 ms mean / 2.08 ms p95 | |
| |
| Per-class F1 ranges from 0.921 ("unknown", the hardest class) to 0.998 |
| ("silence"); all 10 keywords score ≥0.94. Full per-class table and the |
| confusion matrix: see `metrics.json` and `confusion_matrix.png` in this repo. |
| Evaluating this checkpoint on the Colab T4 and on an Apple M2 produced |
| bit-for-bit identical metrics (reproducible across devices). |
|
|
| ## Usage |
|
|
| ```python |
| import torch |
| from huggingface_hub import hf_hub_download |
| |
| # model.py + common.py from https://github.com/priyadeepjaiswal9c/tiny-kws |
| from model import DSCNN |
| from common import LogMel, normalize |
| |
| ckpt = torch.load(hf_hub_download("priyadeepjaiswal9c/tiny-kws", "best.pt"), |
| map_location="cpu", weights_only=True) |
| model = DSCNN(**ckpt["model_config"]); model.load_state_dict(ckpt["model_state"]); model.eval() |
| |
| wav = torch.zeros(16000) # your 1 s, 16 kHz, mono float32 waveform |
| feats = normalize(LogMel()(wav), ckpt["stats"]) |
| probs = model(feats).softmax(1)[0] |
| print(dict(zip(ckpt["labels"], probs.tolist()))) |
| ``` |
|
|
| ## Intended use & limitations |
|
|
| Demo/educational model for isolated 1-second command words in quiet-to-mild |
| noise. Not a streaming/wake-word system (no sliding-window detection), not |
| robust to far-field audio or heavy noise, English only, and trained on |
| crowdsourced speech that skews toward certain accents — expect degraded |
| accuracy outside that distribution. |
|
|
| Live demo: https://huggingface.co/spaces/priyadeepjaiswal9c/tiny-kws · Code: https://github.com/priyadeepjaiswal9c/tiny-kws |
|
|
