Update README.md

README.md

@@ -6,31 +6,111 @@ tags:
   - embedded
   - cpp
   - audio
-  - wake word
+  - wake-word
   - kws
-  - edge impulse
-  - hey edge
+  - keyword-spotting
+  - microphone
+  - synthetic-data
+  - hey-edge
 pipeline_tag: audio-classification
 ---
 
 # Hey-Edge
 
-Trained via Edge Impulse using synthetic and augmented audio.
+Hey-Edge is an audio keyword-spotting wake-word model trained with Edge Impulse to detect the phrase "hey edge" from 16 kHz microphone audio.
+
+The model was trained using synthetic and augmented audio and exported as an Edge Impulse C++ library for embedded and TinyML deployment.
+
+Live Edge Impulse project: https://studio.edgeimpulse.com/public/1052106/live
 
 ## Model details
 
 | Field | Value |
 |---|---|
+| Model name | Hey-Edge |
+| Task | Wake-word keyword spotting |
+| Pipeline tag | audio-classification |
 | Export type | Edge Impulse C++ library |
-| Modality | audio |
-| Sensor | microphone |
+| Modality | Audio |
+| Sensor | Microphone |
 | Sample frequency | 16000 Hz |
 | Input feature count | 3960 |
+| Classes | background_noise, hey_edge, unknown |
+| License | Apache 2.0 |
+
+## Intended use
+
+This model is intended for embedded wake-word detection and TinyML audio classification use cases, including:
+
+- Detecting the phrase "hey edge" on-device.
+- Running keyword spotting on microcontrollers, Linux SBCs, or embedded Linux devices.
+- Demonstrating Edge Impulse C++ library deployment.
+- Prototyping custom wake-word interfaces for edge AI systems.
+
+This model is not intended for speaker identification, speech recognition, transcription, biometric identification, or security-critical voice authentication.
+
+## Training data
+
+| Field | Value |
+|---|---|
+| Training data duration | 41 min 50 sec |
+| Number of classes | 3 |
+| Classes | background_noise, hey_edge, unknown |
+| Training windows | 3765 |
+| Data type | Synthetic and augmented audio |
+| Audio sample rate | 16 kHz |
+
+## Validation performance
+
+| Metric | Value |
+|---|---:|
+| Accuracy | 86.7% |
+| Loss | 0.28 |
+| Area under ROC Curve | 0.97 |
+| Weighted average precision | 0.88 |
+| Weighted average recall | 0.87 |
+| Weighted average F1 score | 0.87 |
+
+## Per-class F1 score
+
+| Class | F1 score |
+|---|---:|
+| background_noise | 0.99 |
+| hey_edge | 0.75 |
+| unknown | 0.90 |
+
+## Confusion matrix
+
+| Actual / Predicted | background_noise | hey_edge | unknown |
+|---|---:|---:|---:|
+| background_noise | 100.0% | 0.0% | 0.0% |
+| hey_edge | 0.7% | 85.5% | 13.8% |
+| unknown | 0.0% | 14.5% | 85.5% |
+
+The main observed failure mode is confusion between hey_edge and unknown.
+
+## On-device performance
+
+### Full impulse inference
+
+| Metric | Value |
+|---|---:|
+| Inferencing time | 655 ms |
+| Peak RAM usage | 166.2 KB |
+| Flash usage | 535.2 KB |
 
+### Feature generation
+
+| Metric | Value |
+|---|---:|
+| Processing time | 250 ms |
+| Peak RAM usage | 20 KB |
+
+Actual performance will vary depending on target hardware, compiler options, DSP settings, and inference engine.
 
 ## Files in this repository
 
-```
+```text
 CMakeLists.txt
 README.txt
 edge-impulse-sdk/
@@ -41,46 +121,169 @@ tflite-model/tflite_learn_1052106_5_compiled.h
 tflite-model/trained_model_ops_define.h
 ```
 
-## How to run
-
-### Build the C++ library
+## Download the full repository
 
 ```bash
 pip install huggingface_hub
-hf download edgeimpulse/Hey-Edge --local-dir ./impulse
-cd impulse
-# Standalone example (from the Edge Impulse C++ SDK):
-make -j
-./build/edge-impulse-standalone <features.txt>
+hf download edgeimpulse/Hey-Edge --local-dir ./Hey-Edge
 ```
 
-The archive contains `edge-impulse-sdk/`, `model-parameters/` and
-`tflite-model/`. Integrate it into your firmware/app per the Edge Impulse C++
-inferencing docs: <https://docs.edgeimpulse.com/deploy-your-model/running-your-impulse-locally/deploy-your-impulse-as-a-c-library>
-
-### Download from the Hub
+## Download a single file
 
 ```bash
 pip install huggingface_hub
-# whole repo:
-hf download edgeimpulse/Hey-Edge --local-dir ./Hey-Edge
-# or a single file:
 hf download edgeimpulse/Hey-Edge CMakeLists.txt --local-dir .
 ```
 
+## Download from Python
+
 ```python
 from huggingface_hub import hf_hub_download, snapshot_download
-path = hf_hub_download("edgeimpulse/Hey-Edge", "CMakeLists.txt")   # one file
-folder = snapshot_download("edgeimpulse/Hey-Edge")             # whole repo
+
+path = hf_hub_download(
+    repo_id="edgeimpulse/Hey-Edge",
+    filename="CMakeLists.txt",
+)
+
+folder = snapshot_download(
+    repo_id="edgeimpulse/Hey-Edge",
+)
+```
+
+## Build the C++ library
+
+```bash
+pip install huggingface_hub
+hf download edgeimpulse/Hey-Edge --local-dir ./impulse
+cd impulse
+make -j
+```
+
+To run the standalone example with a feature file:
+
+```bash
+./build/edge-impulse-standalone features.txt
+```
+
+The repository contains the generated Edge Impulse deployment archive, including:
+
+```text
+edge-impulse-sdk/
+model-parameters/
+tflite-model/
+```
+
+These files can be integrated into firmware, a native application, an embedded Linux application, or another C++ project using the Edge Impulse C++ inferencing workflow.
+
+Edge Impulse C++ deployment documentation:
+
+https://docs.edgeimpulse.com/deploy-your-model/running-your-impulse-locally/deploy-your-impulse-as-a-c-library
+
+## Example embedded integration
+
+A typical embedded or native C++ application will include the generated Edge Impulse headers and call the classifier using the Edge Impulse SDK.
+
+```cpp
+#include "edge-impulse-sdk/classifier/ei_run_classifier.h"
+
+static int get_signal_data(size_t offset, size_t length, float *out_ptr) {
+    return EIDSP_OK;
+}
+
+int main() {
+    signal_t signal;
+    signal.total_length = EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE;
+    signal.get_data = &get_signal_data;
+
+    ei_impulse_result_t result = { 0 };
+
+    EI_IMPULSE_ERROR res = run_classifier(&signal, &result, false);
+
+    if (res != EI_IMPULSE_OK) {
+        return 1;
+    }
+
+    for (size_t ix = 0; ix < EI_CLASSIFIER_LABEL_COUNT; ix++) {
+        ei_printf(
+            "%s: %.5f\n",
+            result.classification[ix].label,
+            result.classification[ix].value
+        );
+    }
+
+    return 0;
+}
 ```
 
+For continuous microphone inference, use a rolling audio buffer, generate features at the expected sampling rate, and call the classifier on each inference window.
+
+## Labels
+
+| Label | Meaning |
+|---|---|
+| background_noise | Non-speech or background audio |
+| hey_edge | Target wake phrase |
+| unknown | Speech or audio that is not the target wake phrase |
+
+A downstream application should apply a confidence threshold to hey_edge before triggering an action. The best threshold depends on the deployment environment and the acceptable false accept / false reject trade-off.
+
+## Limitations
+
+- Validation accuracy is based on the available validation set and may not reflect real-world performance in all acoustic environments.
+- Synthetic and augmented data can improve coverage but may not capture all microphones, accents, rooms, background noises, or playback conditions.
+- The hey_edge class shows some confusion with the unknown class.
+- Real-device testing is recommended before using this model in a production wake-word pipeline.
+- Performance depends on microphone quality, gain settings, sampling consistency, and deployment hardware.
+
+## Recommended evaluation before deployment
+
+Before deploying this model, test it with:
+
+- The target microphone.
+- Real users saying "hey edge".
+- Background noise from the deployment environment.
+- Similar but incorrect phrases.
+- Different distances from the microphone.
+- Continuous audio streams rather than isolated clips.
+- The exact embedded hardware and compiler configuration intended for deployment.
+
+Recommended application-level checks:
+
+- Tune the hey_edge confidence threshold.
+- Add debounce logic to avoid repeated triggers.
+- Require multiple consecutive positive windows for higher precision.
+- Log false accepts and false rejects during field testing.
+- Retrain with real deployment audio where possible.
+
+## About Edge Impulse
+
+This model was exported from Edge Impulse and published to the Hugging Face Hub.
+
+Edge Impulse handles:
+
+- Data collection
+- Audio preprocessing
+- DSP feature extraction
+- Model training
+- Validation
+- Deployment packaging
+
+This repository packages the resulting C++ deployment artifact with instructions for downloading, building, and integrating the model.
+
+Useful Edge Impulse documentation:
 
-## About
+- https://docs.edgeimpulse.com/deploy-your-model
+- https://docs.edgeimpulse.com/deploy-your-model/running-your-impulse-locally
+- https://docs.edgeimpulse.com/deploy-your-model/running-your-impulse-locally/deploy-your-impulse-as-a-c-library
 
-This model was exported from [Edge Impulse](https://edgeimpulse.com) and
-published to the Hub. Edge Impulse handles data collection,
-DSP feature extraction and model training; this repo packages the resulting
-deployment artifact plus ready-to-run instructions.
+## Citation
 
-- Edge Impulse deployment docs: <https://docs.edgeimpulse.com/deploy-your-model>
-- Running impulses locally: <https://docs.edgeimpulse.com/deploy-your-model/running-your-impulse-locally>
+```bibtex
+@misc{heyedge_edgeimpulse,
+  title = {Hey-Edge Wake Word Model},
+  author = {Eoin Jordan - Edge Impulse},
+  year = {2026},
+  howpublished = {https://huggingface.co/edgeimpulse/Hey-Edge},
+  note = {Edge Impulse C++ library export for audio keyword spotting}
+}
+```