# klumw/wakeword architecture

> Architecture diagram of the GitHub repository klumw/wakeword, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/klumw/wakeword
- Repository: https://github.com/klumw/wakeword

## Overview

This is an ESP32-S3 wakeword-detection starter: microphone audio is captured and gain-adjusted, then passed through Edge Impulse audio processing and an embedded model; a positive “computer” detection drives the onboard LED. The README documents I2S input, software AGC, ESP-NN optimization, model replacement, and visual feedback. The sampled sources establish the classifier entry point, model artifact, DSP and inference-runtime layers; detailed capture and detection calls are not shown, so those documented links are marked unverified.

Main entry points: [`components/edge_impulse/edge-impulse-sdk/classifier`](https://github.com/klumw/wakeword/tree/main/components/edge_impulse/edge-impulse-sdk/classifier) (Classifier API), [`main/keyword.cpp`](https://github.com/klumw/wakeword/blob/main/main/keyword.cpp) (Keyword app), [`components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro`](https://github.com/klumw/wakeword/tree/main/components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro) (TFLite Micro), [`main`](https://github.com/klumw/wakeword/tree/main/main) (Audio AGC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Device I/O"]
  node_mic["I2S microphone"]
  node_app["Keyword app<br/>[keyword.cpp]"]
  node_agc["Audio AGC"]
  node_led["Status LED"]
end

subgraph group_inference["Audio inference"]
  node_classifier["Classifier API"]
  node_audio_features["Audio features<br/>[feature.hpp]"]
  node_dsp_math["DSP math<br/>[numpy.hpp]"]
  node_metadata["Model metadata<br/>[model_metadata.h]"]
  node_model["Compiled model"]
  node_result["Detection result"]
end

subgraph group_runtime["Inference runtime"]
  node_tflm["TFLite Micro"]
  node_micro_context["Micro context<br/>[micro_context.h]"]
  node_tflite_api["Tensor API<br/>[common.h]"]
end

subgraph group_accel["Embedded acceleration"]
  node_cmsis_nn["CMSIS-NN<br/>[arm_nnfunctions.h]"]
  node_esp_nn["ESP-NN"]
end

node_user(("Device user"))

node_user -.->|"starts detection"| node_app
node_mic -.->|"provides audio"| node_app
node_app -.->|"adjusts gain"| node_agc
node_app -->|"runs classifier"| node_classifier
node_agc -.->|"supplies audio"| node_classifier
node_classifier -.->|"extracts features"| node_audio_features
node_audio_features -.->|"uses DSP math"| node_dsp_math
node_classifier -.->|"runs model"| node_model
node_classifier -.->|"uses configuration"| node_metadata
node_classifier -.->|"invokes runtime"| node_tflm
node_tflm -.->|"uses context"| node_micro_context
node_micro_context -->|"uses tensor API"| node_tflite_api
node_tflm -.->|"uses kernels"| node_cmsis_nn
node_tflm -.->|"uses acceleration"| node_esp_nn
node_classifier -.->|"formats results"| node_result
node_app -.->|"signals detection"| node_led
node_led -.->|"shows detection"| node_user

click node_app "https://github.com/klumw/wakeword/blob/main/main/keyword.cpp"
click node_agc "https://github.com/klumw/wakeword/tree/main/main"
click node_led "https://github.com/klumw/wakeword/tree/main/main"
click node_classifier "https://github.com/klumw/wakeword/tree/main/components/edge_impulse/edge-impulse-sdk/classifier"
click node_audio_features "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/dsp/speechpy/feature.hpp"
click node_dsp_math "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/dsp/numpy.hpp"
click node_metadata "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/model-parameters/model_metadata.h"
click node_model "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/tflite-model/tflite_learn_1904_compiled.cpp"
click node_result "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/classifier/ei_fill_result_struct.h"
click node_tflm "https://github.com/klumw/wakeword/tree/main/components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro"
click node_micro_context "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro/micro_context.h"
click node_tflite_api "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/tensorflow/lite/core/c/common.h"
click node_cmsis_nn "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/CMSIS/NN/Include/arm_nnfunctions.h"
click node_esp_nn "https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/porting/espressif/ESP-NN/src/convolution/esp_nn_depthwise_conv_s8_esp32s3.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mic,node_app,node_agc,node_led,node_user toneBlue
class node_classifier,node_audio_features,node_dsp_math,node_metadata,node_model,node_result toneAmber
class node_tflm,node_micro_context,node_tflite_api toneMint
class node_cmsis_nn,node_esp_nn toneRose
```

## Components

### Device I/O

- **I2S microphone**
- [Keyword app](https://github.com/klumw/wakeword/blob/main/main/keyword.cpp): `main/keyword.cpp`
- [Audio AGC](https://github.com/klumw/wakeword/tree/main/main): `main`
- [Status LED](https://github.com/klumw/wakeword/tree/main/main): `main`

### Audio inference

- [Classifier API](https://github.com/klumw/wakeword/tree/main/components/edge_impulse/edge-impulse-sdk/classifier): `components/edge_impulse/edge-impulse-sdk/classifier`
- [Audio features](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/dsp/speechpy/feature.hpp): `components/edge_impulse/edge-impulse-sdk/dsp/speechpy/feature.hpp`
- [DSP math](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/dsp/numpy.hpp): `components/edge_impulse/edge-impulse-sdk/dsp/numpy.hpp`
- [Model metadata](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/model-parameters/model_metadata.h): `components/edge_impulse/model-parameters/model_metadata.h`
- [Compiled model](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/tflite-model/tflite_learn_1904_compiled.cpp): `components/edge_impulse/tflite-model/tflite_learn_1904_compiled.cpp`
- [Detection result](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/classifier/ei_fill_result_struct.h): `components/edge_impulse/edge-impulse-sdk/classifier/ei_fill_result_struct.h`

### Inference runtime

- [TFLite Micro](https://github.com/klumw/wakeword/tree/main/components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro): `components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro`
- [Micro context](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro/micro_context.h): `components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro/micro_context.h`
- [Tensor API](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/tensorflow/lite/core/c/common.h): `components/edge_impulse/edge-impulse-sdk/tensorflow/lite/core/c/common.h`

### Embedded acceleration

- [CMSIS-NN](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/CMSIS/NN/Include/arm_nnfunctions.h): `components/edge_impulse/edge-impulse-sdk/CMSIS/NN/Include/arm_nnfunctions.h`
- [ESP-NN](https://github.com/klumw/wakeword/blob/main/components/edge_impulse/edge-impulse-sdk/porting/espressif/ESP-NN/src/convolution/esp_nn_depthwise_conv_s8_esp32s3.c): `components/edge_impulse/edge-impulse-sdk/porting/espressif/ESP-NN/src/convolution/esp_nn_depthwise_conv_s8_esp32s3.c`

### Other components

- **Device user**

## Connections

- Device user → Keyword app: starts detection
- I2S microphone → Keyword app: provides audio
- Keyword app → Audio AGC: adjusts gain
- Keyword app → Classifier API: runs classifier (evidence: `main/keyword.cpp`)
- Audio AGC → Classifier API: supplies audio (evidence: `main/keyword.cpp`)
- Classifier API → Audio features: extracts features
- Audio features → DSP math: uses DSP math
- Classifier API → Compiled model: runs model
- Classifier API → Model metadata: uses configuration (evidence: `components/edge_impulse/edge-impulse-sdk/classifier/ei_fill_result_struct.h`)
- Classifier API → TFLite Micro: invokes runtime (evidence: `components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro/kernels/conv.cc`)
- TFLite Micro → Micro context: uses context (evidence: `components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro/micro_context.h`)
- Micro context → Tensor API: uses tensor API (evidence: `components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro/micro_context.h`)
- TFLite Micro → CMSIS-NN: uses kernels (evidence: `components/edge_impulse/edge-impulse-sdk/tensorflow/lite/micro/kernels/conv.cc`)
- TFLite Micro → ESP-NN: uses acceleration
- Classifier API → Detection result: formats results (evidence: `components/edge_impulse/edge-impulse-sdk/classifier/ei_fill_result_struct.h`)
- Keyword app → Status LED: signals detection
- Status LED → Device user: shows detection
