Easily train MicroWakeWord detection models with this Docker image. This setup uses Python 3.11 and is based on the tensorflow/tensorflow:2.19.0-gpu-jupyter image.
- Docker installed on your system.
- An NVIDIA GPU with CUDA support (optional but highly recommended for faster training).
- The
prepare_local_data.pyscript should be present at the root of your workspace (e.g., alongside theMicroWakeWord-Trainer-Dockerdirectory) before building the Docker image.
microWakeWordlibrary: Cloned fromhttps://github.com/kiwina/microWakeWord.gitand installed in editable mode (pip install -e .) during the Docker image build.piper-sample-generator: Cloned fromhttps://github.com/kiwina/piper-sample-generator.gitinto the/datavolume by theprepare_local_data.pyscript when the notebooks are first run. The notebooks then use scripts from/data/piper-sample-generator.prepare_local_data.py: This script is copied into the Docker image and then into the/datavolume bystartup.sh. The training notebooks execute this script to download all necessary datasets and thepiper-sample-generator.
Follow these steps to get started with the microWakeWord Trainer:
Navigate to the MicroWakeWord-Trainer-Docker directory (this directory) in your terminal and run:
docker build -t kiwina/microwakeword-trainer .(You can replace kiwina/microwakeword-trainer with your preferred image name and tag.)
Start the container with a mapped volume for saving your data and expose the Jupyter Notebook port. Create a microwakeword-trainer-data directory if it doesn't exist, typically inside your MicroWakeWord-Trainer-Docker project directory or at your workspace root.
Example (if microwakeword-trainer-data is inside MicroWakeWord-Trainer-Docker directory):
# From within MicroWakeWord-Trainer-Docker directory:
mkdir -p microwakeword-trainer-data
docker run --rm -it \
--gpus all \
-p 8888:8888 \
-v "$(pwd)/microwakeword-trainer-data:/data" \
kiwina/microwakeword-trainerExample (if microwakeword-trainer-data is at the workspace root, sibling to MicroWakeWord-Trainer-
84BB
Docker):
# From within MicroWakeWord-Trainer-Docker directory:
# mkdir -p ../microwakeword-trainer-data # Create it if it doesn't exist
# docker run --rm -it \
# --gpus all \
# -p 8888:8888 \
# -v "$(pwd)/../microwakeword-trainer-data:/data" \
# kiwina/microwakeword-trainerChoose the volume mapping (-v) that matches your microwakeword-trainer-data directory location.
--gpus all: Enables GPU acceleration (optional, remove if not using a GPU).-p 8888:8888: Exposes the Jupyter Notebook on port 8888.-v ...:/data: Maps your localmicrowakeword-trainer-datadirectory to the container's/datadirectory. This is where all generated samples, datasets, trained models, and notebooks will be stored, ensuring persistence.
Open your web browser and navigate to:
http://localhost:8888(The current Dockerfile CMD disables the token, so one might not be required.)
The notebook interface should appear, showing the contents of the /data directory.
The startup.sh script within the container will automatically copy:
basic_training_notebook.ipynbadvanced_training_notebook.ipynbprepare_local_data.pyfrom the image's/root/directory to/data/if they are not already present.
You should generate the .ipynb files from their corresponding .py versions (which were modified in this project) and ensure they, along with prepare_local_data.py (from your workspace root), are correctly placed for the Docker COPY commands during the build.
When you first run a notebook (.py or .ipynb version), its initial cells will execute /data/prepare_local_data.py. This script downloads and prepares all necessary datasets (Piper TTS model, augmentation audio, negative features) and clones piper-sample-generator into subdirectories within /data. This process is idempotent.
Open either basic_training_notebook.py or advanced_training_notebook.py (or their .ipynb versions) from the Jupyter interface (or run the .py scripts via a terminal in the container). Locate the line defining target_word and change it:
target_word = 'your_wake_word_here' # Phonetic spellings may produce better samplesExecute the cells or run the Python script. The process will:
- Utilize the data prepared by
prepare_local_data.py. - Generate wake word samples into
/data/generated_samples/{target_word}/.... - Train a detection model.
- Output a quantized
.tflitemodel and a corresponding JSON manifest file into the/datadirectory.
The trained .tflite model and .json manifest will be available in your mapped local microwakeword-trainer-data directory.
If you need to start fresh with datasets or generated content:
- Delete specific subfolders within your local
microwakeword-trainer-datadirectory (e.g.,generated_samples,mit_rirs,piper-sample-generator,trained_models_adv). Theprepare_local_data.pyscript will then re-download/re-process only the missing parts when a notebook is run. - To reset the notebooks or
prepare_local_data.pyscript themselves, delete them from your localmicrowakeword-trainer-datadirectory. When you restart the Docker container,startup.shwill copy fresh versions from the image.
This project builds upon the excellent work of kahrendt/microWakeWord.
This version is maintained in the kiwina forks (e.g., kiwina/MicroWakeWord-Trainer-Docker, kiwina/microWakeWord).