taco/microWakeWord-Trainer-Nvidia-Docker
1
0
Fork 0
mirror of https://github.com/TaterTotterson/microWakeWord-Trainer-Nvidia-Docker.git synced 2026-08-12 07:55:33 -06:00
Code Issues Packages Projects Releases Wiki Activity
Files
89260f1f149f8a492c0f64ba2cb50731d8efa230
microWakeWord-Trainer-Nvidi…/README.md
MasterPhooey 1fc7d80bae Add RTX 50 Blackwell image support
2026-06-27 07:46:53 -05:00

9.1 KiB
Raw Blame History

taterassistant.com

Train custom microWakeWord models in Docker with NVIDIA/CUDA acceleration, generated Piper samples, device-captured samples, reviewed false-wake negatives, live training logs, and prebuilt Tater firmware flashing.

Real samples come from device-captured wake audio, close misses, or manual uploads. Every saved sample is normalized to 16 kHz / mono / 16-bit PCM WAV before training.

Docker Image

docker pull ghcr.io/tatertotterson/microwakeword:latest

Tagged releases also publish matching immutable image tags:

docker pull ghcr.io/tatertotterson/microwakeword:v5

RTX 50-series / Blackwell GPUs use a separate image with CUDA 12.8 and a Python 3.13 TensorFlow build for sm_120:

docker pull ghcr.io/tatertotterson/microwakeword:blackwell
docker pull ghcr.io/tatertotterson/microwakeword:v5-blackwell

Use the Blackwell image only for RTX 50-series cards. It includes the community-built TensorFlow wheel from chivitiH/tensorflow-blackwell-python313, which is unofficial and licensed CC BY-NC 4.0.

Run The Container

docker run -d \
  --gpus all \
  --network host \
  -e REC_PORT=8789 \
  -v $(pwd):/data \
  ghcr.io/tatertotterson/microwakeword:latest

Use a version tag such as ghcr.io/tatertotterson/microwakeword:v5 when you want to pin a known release instead of tracking latest. For RTX 50-series cards, use ghcr.io/tatertotterson/microwakeword:blackwell or a pinned tag such as ghcr.io/tatertotterson/microwakeword:v5-blackwell in the same docker run command.

The flags:

  • --gpus all enables GPU acceleration.
  • --network host lets the container receive mDNS/zeroconf traffic for ESPHome auto-detect.
  • -e REC_PORT=8789 sets the trainer web UI and captured-audio port. Change this value if 8789 is already in use.
  • -v $(pwd):/data persists models, downloaded voices, datasets, samples, and firmware caches.

Host networking is recommended for the Firmware tab's mDNS device discovery. Manual IP flashing and captured-audio uploads can still work without host networking if the trainer port is reachable, but auto-detect may not see devices from Docker bridge networking.

Open:

http://localhost:8789

If you change REC_PORT, open that port instead and use the same port in the ESPHome Trainer App URL.

What The UI Does

  • Trainer starts a wake-word session, shows positive/negative sample counts, and launches training.
  • Captured Audio reviews clips sent by ESPHome sats, including wake hits, close misses, and false wakes.
  • Samples plays, removes, clears, and manually imports personal or negative samples.
  • Firmware pulls verified prebuilt Tater firmware images from GitHub and flashes supported satellites over OTA.
  • Popup consoles show colorized training and firmware logs while long-running jobs are active.

Captured Audio Workflow

To collect samples from a sat, flash it with the Tater firmware from TaterTotterson/microWakeWords. The Firmware tab can pull verified prebuilt OTA images from that repo for fast firmware updates.

After flashing, the device exposes ESPHome entities for capture setup:

  • Capture Wake Audio toggles upload of wake-word triggers.
  • Capture Close Misses toggles upload of near misses.
  • Trainer App URL sets the trainer address, for example http://<trainer-ip>:8789.

ESPHome devices can send raw captured audio to:

/api/upload_captured_audio_raw

Keep the training app running and reachable at the Trainer App URL while capture is enabled. The sats upload clips live; if the app is stopped or the URL is wrong, captured audio will not be saved.

In the Captured Audio tab:

  • play each clip from the inbox
  • mark good wake-word clips as This is good
  • mark bad triggers as False wake
  • discard clips that should not be used

Approved clips move into:

/data/personal_samples/

False wakes move into:

/data/negative_samples/

Captured audio is boosted for easier playback in the UI, then kept in the correct training format.

Samples

The Samples tab is the sample library.

  • Personal samples are positive examples of the wake word.
  • Negative samples are reviewed false wakes or hard negatives.
  • Both can be played back and removed one at a time.
  • Manual upload is available here as an optional seed path.

Accepted manual upload formats include:

  • WAV
  • MP3
  • M4A
  • FLAC
  • OGG
  • AAC
  • OPUS
  • WEBM

Uploads are validated or converted with ffmpeg into:

16 kHz / mono / 16-bit PCM WAV

Starting a new session does not clear samples. Use the clear buttons in Samples if you want to remove saved personal or negative clips.

Training Flow

  1. Enter the wake phrase in Trainer.
  2. Choose the language.
  3. Optionally test pronunciation with Test TTS.
  4. Review the positive and negative sample counts.
  5. Click Start training.
  6. Watch the popup training console.

Personal samples are optional. Training can run with zero personal samples after confirmation, using generated TTS samples and the stock negative datasets.

Reviewed negative samples are converted into /data/work/reviewed_negative_features/ and inserted into the training YAML as a hard-negative feature set when present.

On RTX 50-series / Blackwell GPUs, the Blackwell Docker image keeps sample generation and augmentation in the normal Python 3.12 trainer environment, then runs only the TensorFlow training/export stage in /data/.venv-blackwell with Python 3.13 and the Blackwell-native TensorFlow wheel.

Language Support

The language picker is dynamic.

  • en is always available.
  • English keeps the existing dedicated generator model path.
  • Non-English languages are discovered from the Piper voices catalog and any local Piper voice metadata.
  • When a non-English language is selected, the trainer downloads all voices for that selected language only.
  • Already-downloaded voices are reused.
  • It does not download every language up front.

If the upstream Piper catalog is unavailable, already-installed local voices are used when available.

Dataset Behavior

The first training run downloads and prepares missing training assets into /data, including:

  • Piper voices for the selected language
  • negative datasets and background data
  • the Python training environment
  • generated samples and augmented feature caches

After those assets are prepared, later runs reuse the local copies unless the mounted /data contents are deleted.

Firmware Flashing

The Firmware tab flashes prebuilt Tater firmware for supported ESPHome satellites.

  • Downloads the latest prebuilt firmware manifest plus OTA and USB factory images from TaterTotterson/microWakeWords.
  • Verifies downloaded images by size and SHA before upload.
  • Auto-detects ESPHome devices with mDNS when the container is running with host networking.
  • Allows manual IP or hostname entry if discovery does not find the device.
  • Saves the selected OTA target for each firmware family.
  • Flashes the prebuilt factory image over Browser USB for first installs or recovery when opened in Chrome or Edge.
  • Lists locally trained wake words from /data/trained_wake_words/ for live model switching.
  • Streams download, verification, and OTA upload progress in a colorized firmware console.

You usually only flash for firmware updates. New satellites, or devices older than Tater firmware 3.0.3, need one USB flash first before OTA updates and live wake-word switching are available.

Output Files

Successful runs produce timestamped training output folders such as:

/data/output/<timestamp>-<wake_word>-<samples>-<steps>/<wake_word>.tflite
/data/output/<timestamp>-<wake_word>-<samples>-<steps>/<wake_word>.json

The trainer also syncs firmware-ready artifacts into:

/data/trained_wake_words/<wake_word>.tflite
/data/trained_wake_words/<wake_word>.json

The firmware tab uses /data/trained_wake_words/ to populate the wake-word dropdown.

Resetting Everything

If you want a clean slate, stop the container and remove the contents of the mounted /data directory.

That removes:

  • personal samples
  • negative samples
  • captured inbox clips
  • downloaded Piper voices
  • cached datasets
  • training environments
  • trained models
  • downloaded firmware images

Important Notes

  • Personal samples are optional.
  • Negative samples are optional but useful for reducing false wakes.
  • The UI server is trainer_server.py.
  • The launcher is run.sh.
  • Firmware capture settings live on the ESPHome device and can be toggled from the device entities after flashing.

Credits

Built on top of:

Reference in New Issue View Git Blame Copy Permalink