---
title: Hey Reachy Wake Word Detection
emoji: 👋
colorFrom: red
colorTo: blue
sdk: static
pinned: false
short_description: Hey Reachy wake word detection
tags:
 - reachy_mini
 - reachy_mini_python_app
---

# Hey Reachy - Wake Word Detection

A custom wake word detection application for Reachy Mini robot that responds to the "Hey Reachy" voice command.

![Hey Reachy](/assets/hey-reachy.gif)

## Overview

This project implements a wake word detection system for the Reachy Mini robot. When the robot hears "Hey Reachy", it performs a friendly animation and responds with a greeting sound.

## Features

- On-device wake word detection using an Edge Impulse model
- Web interface for configuration
- Audio device selection
- Detection threshold adjustment
- Visual feedback when wake word is detected
- Greetings using [Gradium](https://gradium.ai/) for Reachy's voice
- Cross-platform support (macOS and Linux) - Only tested on MacOS Apple Silicon

*Notes: This project aims for a base project that you can freely modify. Don't expect this to be `Alexa` or `OK Google`-grade level. The model has only been trained on ~2.5h of data.*

## Technical Details

### Dataset generation

The wake word and sounds dataset was generated using this repo: https://github.com/edgeimpulse/example-synthetic-keywords-using-kyutai-tts-1.6b-en_fr

- [Kyutai TTS 1.6](https://huggingface.co/kyutai/tts-1.6b-en_fr) for synthetic voice generation
- [Freesound LAION 640k dataset](https://huggingface.co/datasets/benjamin-paine/freesound-laion-640k) for background noise

![Data acquisition overview](/assets/ei-data-acquisition.png)

### Model training

The model was trained on Edge Impulse using roughly 2.5h of synthetic data.

See the associated [public project](https://studio.edgeimpulse.com/public/855375/latest) for more information.

![Edge Impulse model info](/assets/ei-model-info.png)

### Implementation

The application uses:

- Reachy Mini SDK for robot control
- Edge Impulse Linux SDK for wake word detection
- Sounddevice for audio input
- FastAPI (via ReachyMiniApp) for the web interface

## Setup

### 1. Clone the repository

```bash
git clone git@hf.co:spaces/luisomoreau/hey_reachy_wake_word_detection
cd hey_reachy_wake_word_detection
```

### 2. Create and activate virtual environment

```bash
python3.12 -m venv venv
source venv/bin/activate  # Linux/MacOS
# .\venv\Scripts\activate  # Windows
```

### 3. Install dependencies

```bash
pip install -e .
```

### 4. Launch the Reach Mini Daemon

Open the [Reachy Mini Desktop App](https://github.com/pollen-robotics/reachy-mini-desktop-app).

You can also launch it from the command line:

```bash
reachy-mini-daemon
```

### 5. Run the main.py

```bash
python hey_reachy_wake_word_detection/main.py
```

If everything works, you should see logs like the followings:

```
python hey_reachy_wake_word_detection/main.py 
Running on: darwin arm64
INFO:     Started server process [98489]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8042 (Press CTRL+C to quit)
Starting HeyReachyWakeWordDetection app with sounddevice...

Available audio input devices:
  ID 1: Reachy Mini Audio (2 input channels)
  ID 2: Reachy Mini Camera (2 input channels)
  ID 3: Logitech BRIO (2 input channels)
  ID 4: BlackHole 2ch (2 input channels)
  ID 5: MacBook Pro Microphone (1 input channels)
  ID 7: Microsoft Teams Audio (1 input channels)
  ID 8: Descript Loopback Recorder (2 input channels)

Detected system: darwin arm64
Selected model: hey-reachy-wake-word-detection-mac-arm64.eim
Using audio device: Reachy Mini Audio (ID: 1)
Loaded runner for "Developer Relations / Hey Reachy - Wake word detection"
Model expects: 24000Hz, 12000 samples
Current threshold: 0.7
selected Audio device: 1
Classification: {'hey_reachy': '0.0000', 'noise': '1.0000', 'other': '0.0000'}
Classification: {'hey_reachy': '0.0000', 'noise': '1.0000', 'other': '0.0000'}
Classification: {'hey_reachy': '0.0000', 'noise': '1.0000', 'other': '0.0000'}
Classification: {'hey_reachy': '0.0000', 'noise': '1.0000', 'other': '0.0000'}
Classification: {'hey_reachy': '0.0000', 'noise': '1.0000', 'other': '0.0000'}
Classification: {'hey_reachy': '0.8501', 'noise': '0.0000', 'other': '0.1499'}
Detection score: 0.8501
🎤 KEYWORD DETECTED - Executing actions...
Playing sound: /Users/luisomoreau/workspace/reachy-mini/hey_reachy_wake_word_detection/hey_reachy_wake_word_detection/greetings-audio/speech_g4rDsF5OhcU.ogg
^CINFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [98489]

Interrupted by user
Error in stop: Lost connection with the server.
App is stopping...
```

## Create your own keyword

Want to use your own wake word instead of "Hey Reachy"? Follow these steps to create your own keyword spotting model:

### 1. Follow the Edge Impulse Keyword Spotting Tutorial

Start with the official [Edge Impulse Keyword Spotting Tutorial](https://docs.edgeimpulse.com/tutorials/end-to-end/keyword-spotting). This will guide you through:

- Collecting or generating audio data for your keyword
- Training a custom model
- Testing and deploying your model

You can also have a look at the **Hey Reachy** [public project](https://studio.edgeimpulse.com/public/855375/latest).

### 3. Export your model

1. Go to the "Deployment" section
2. Select "Linux (AARCH64)", "Linux (x86_64)", "MacOS (arm64)" or "MacOS (x86)" depending on your platform.
3. Download the `.eim` model file
4. Place it in the `models` directory of this project, using the appropriate naming convention:
   - `your-keyword-mac-arm64.eim` (for Mac ARM64)
   - `your-keyword-linux-x86_64.eim` (for Linux x86_64)
   - etc.

### 4. Update the code

Modify the `model_mapping` dictionary in `main.py` to include your model:

```python
model_mapping = {
    ('darwin', 'arm64'): "your-keyword-mac-arm64.eim",
    ('darwin', 'x86_64'): "your-keyword-mac-x86_64.eim",
    ('linux', 'aarch64'): "your-keyword-linux-aarch64.eim",
    ('linux', 'armv7l'): "your-keyword-linux-armv7.eim",
    ('linux', 'x86_64'): "your-keyword-linux-x86_64.eim"
}
```

Also update the classification label check from "hey_reachy" to your keyword:

```python
score = res['result']['classification'].get("your_keyword", 0)
```

### 5. Run the code

```bash
python hey_reachy_wake_word_detection/main.py
```

## Troubleshooting

I am still unsure why but I could not use `sample = mini.media.get_audio_sample()` to get the audio stream.
I switch to sounddevice (same library that should be behind the `get_audio_sample()`).

I also had issues when trying to use multi-threads. This is probably due to the implementation of the `classifier` functio in Edge Impulse Python SDK.