Custom Wake Words

Ava supports two ways to add custom wake words: in-app import (recommended, no tools needed) and APK injection (advanced, for power users).

Both methods support microWakeWord (.tflite + .json) and OpenWakeWord (.onnx + .json) model formats. OpenWakeWord keyword classifiers must be float32; the native loader rejects quantized tensors.

Before importing your own models: Ava ships with a built-in Wake Word Library that already includes a curated catalog and a community catalog with 100+ pretrained models you can browse and download directly. See Wake Word Engines → Wake Word Library & Catalog for the full catalog. Importing your own files is for models that are not in either catalog.

Compatible with Android 5-16.

Method 1: In-App Import (Recommended)

Since 0.5.5, Ava includes a built-in Wake Word Library that lets you import custom wake word models directly in the app — no APK editing, no desktop tools required.

Supported File Types

Engine	Config File	Model File
microWakeWord	`.json`	`.tflite`
OpenWakeWord	`.json` (manifest, `openwakeword-v1` format)	`.onnx` (float32 ONNX keyword classifier)

The app automatically detects which engine a .json file belongs to based on its content (format field contains openwakeword or type equals openwakeword).

Import Methods

Option A: Import a ZIP archive (batch)

If you have multiple wake words bundled in a .zip file, you can import them all at once:

Go to Settings → Voice Config → Wake Word Library
Tap Import wake word files
Select a .zip file containing your wake word files
The app extracts and installs all valid models automatically
Imported wake words appear in the library list

The ZIP file should contain .json + .tflite pairs (microWakeWord) or .json + .onnx pairs (OpenWakeWord). Files are grouped by their ID (filename without extension). OpenWakeWord .onnx files must be float32; non-float32 graphs fail closed at import.

Option B: Import a single JSON config

Go to Settings → Voice Config → Wake Word Library
Tap Import wake word files
Select a .json file
If the JSON is a complete package (includes model data), import finishes immediately
If the model file is missing, the app prompts to select the matching model file (.tflite for microWakeWord, .onnx for OpenWakeWord)
After both files are imported, the wake word appears as "Ready" in the library

Option C: Add a model file to an existing entry

If a library entry shows "Missing model file", you can add the model file separately:

Tap the entry in the Wake Word Library
Tap Add model file
Select the matching .tflite or .onnx file

Managing Imported Wake Words

Action	How
Use an imported wake word	Tap it in the library → tap Set as wake word
Delete an imported wake word	Tap it → tap Remove → confirm
Engine auto-switch	Selecting an OpenWakeWord model automatically switches the engine to OpenWakeWord

Note: Stop-classifier models (stop_classifier: true) cannot be imported through the Wake Word Library. Ava does not use stop models at all — "stop" is detected by a built-in model-free native DSP detector.

Method 2: APK Injection (Advanced)

Ava also loads microWakeWord models from assets/wakeWords/ and OpenWakeWord models from assets/openwakeword/ inside the APK. You can inject custom models without building from source — just edit the APK directly.

Tools needed:

Android file manager with APK editing: MT Manager (Chinese), APK Editor Pro, or Nexus APK Editor
Or on desktop: apktool + zipalign + apksigner

Steps (MT Manager method)

Download the Ava Pro lite APK from GitHub releases
Open MT Manager, long-press the APK, select "View" (or "Extract")
Navigate to assets/wakeWords/ (for microWakeWord) or assets/openwakeword/ (for OpenWakeWord)
Copy your custom model files into the directory:
- microWakeWord: my_word.tflite + my_word.json
- OpenWakeWord: my_word.onnx + my_word.json (float32 only)
Save and repack the APK (MT Manager handles re-signing automatically)
Uninstall the old Ava, install the modified APK
Open Settings -> Voice Config -> Wake Word, your custom model appears in the list

Steps (desktop apktool method)

# Decompile
apktool d Ava-0.7.3.apk -o ava_decoded

# Add your model
cp my_word.tflite my_word.json ava_decoded/assets/wakeWords/

# For OpenWakeWord
cp my_word.onnx my_word.json ava_decoded/assets/openwakeword/

# Repack
apktool b ava_decoded -o Ava-custom.apk

# Sign
zipalign -v 4 Ava-custom.apk Ava-custom-aligned.apk
apksigner sign --ks ava-key.jks --ks-pass pass:1234 --out Ava-custom-signed.apk Ava-custom-aligned.apk

microWakeWord: Download Pretrained or Train Your Own

Ava uses microWakeWords V3 format. The JSON config is identical to the V3 models from the community.

Option 1: Download Pretrained Models (Easiest)

The microWakeWords repo by TaterTotterson maintains a large library of pretrained V3 models. The format is directly compatible with Ava.

Browse the microWakeWordsV3 directory
Find a wake word you like (e.g., aleesa, angel, annika, arale, artamis, etc.)
Download both files: name.json and name.tflite
Import via Wake Word Library (Method 1 above) or place in assets/wakeWords/ (Method 2)

The V3 JSON format is identical to Ava's built-in models:

{
  "type": "micro",
  "wake_word": "ah_lehks_sah",
  "author": "Tater Totterson",
  "website": "https://github.com/TaterTotterson/microWakeWord-Trainer-AppleSilicon",
  "model": "ah_lehks_sah.tflite",
  "trained_languages": ["en"],
  "version": 2,
  "micro": {
    "probability_cutoff": 0.1,
    "sliding_window_size": 3,
    "feature_step_size": 10,
    "tensor_arena_size": 30000,
    "minimum_esphome_version": "2024.7.0"
  }
}

Option 2: Train Your Own with macOS Trainer (Apple Silicon)

If you have a Mac with Apple Silicon (M1/M2/M3/M4), you can train a custom wake word with a local web UI:

Install the trainer:
- Download the signed macOS app from WakeWord Trainer releases
- Or clone and run from source:
```
git clone https://github.com/TaterTotterson/microWakeWord-Trainer-AppleSilicon.git
cd microWakeWord-Trainer-AppleSilicon
./run.sh
```
- Open http://127.0.0.1:8789 in your browser
Train the wake word:
- Enter your wake phrase in the Trainer tab
- Choose language (en, or other Piper-supported languages)
- Optionally test pronunciation with Test TTS
- Click Start training
- The trainer uses Piper TTS to generate samples automatically
- Personal samples are optional but improve accuracy
Optionally capture real samples from devices:
- Flash a device with Tater firmware (from the Firmware tab)
- Enable Capture Wake Audio on the device
- Set Trainer App URL to http://<trainer-ip>:8789
- Review captured clips in the Captured Audio tab
- Mark good clips as "This is good", bad ones as "False wake"
Get the output files:
- Successful training produces:
  - trained_wake_words/<wake_word>.tflite
  - trained_wake_words/<wake_word>.json
Install into Ava:
- Import via Wake Word Library (Method 1 above)
- Or copy both files to assets/wakeWords/ and rebuild the APK (Method 2)

Option 3: Train with Direct Script

git clone https://github.com/TaterTotterson/microWakeWord-Trainer-AppleSilicon.git
cd microWakeWord-Trainer-AppleSilicon
./train_microwakeword_macos.sh "hey_my_custom_word"

If personal_samples/*.wav or negative_samples/*.wav exist in the folder, they are included automatically.

JSON Config Parameters

Parameter	Description	Typical Value
`probability_cutoff`	Detection threshold (lower = easier to trigger, more false positives)	0.1 - 0.97
`sliding_window_size`	Frames to average before triggering	3 - 9
`feature_step_size`	Feature extraction step in ms	10
`tensor_arena_size`	TFLite arena size in bytes (must match model)	21000 - 30000
`minimum_esphome_version`	Minimum ESPHome version	2024.7.0

Note: microWakeWord requires a trained model for each wake word. There is no hot-swap — you need a .tflite file. But Ava's Wake Word Library includes a community catalog with 100+ pretrained models from the TaterTotterson/microWakeWords V3 library — browse and download directly in the app.

OpenWakeWord: ONNX Keyword Classifier Import

OpenWakeWord uses a shared 96-dimensional acoustic embedding model. Custom wake words are lightweight ONNX keyword classifiers that read from the shared embedding — you only need the small classifier .onnx, not a full model.

OpenWakeWord Manifest Format

Each OpenWakeWord model is a pair: id.json (manifest) + id.onnx (float32 ONNX keyword classifier).

{
  "type": "openwakeword",
  "format": "openwakeword-v1",
  "id": "my_custom_word",
  "wake_word": "My Custom Word",
  "model": "my_custom_word.onnx",
  "trained_languages": ["en"],
  "author": "Your Name",
  "website": "https://...",
  "license": "MIT",
  "source_url": "https://...",
  "sha256": "...",
  "input": { "name": "serving_default_input:0", "shape": [1, 16, 96], "dtype": "float32" },
  "output": { "name": "PartitionedCall:0", "shape": [1, 1], "dtype": "float32" },
  "openwakeword": {
    "threshold": 0.5,
    "required_hits": 2,
    "cooldown_ms": 2000,
    "sliding_window_size": 1
  },
  "built_in_verifier": false,
  "stop_classifier": false
}

Manifest Fields

Field	Description
`format`	Manifest format version (`openwakeword-v1`)
`id`	Keyword identifier (filename without extension)
`wake_word`	Human-readable wake word
`model`	ONNX model filename
`input` / `output`	Tensor shapes and dtypes (must be float32)
`openwakeword.threshold`	Trigger cutoff
`openwakeword.required_hits`	Consecutive windows above threshold to trigger
`openwakeword.cooldown_ms`	Cooldown before same keyword can trigger again
`built_in_verifier`	True if model carries its own second-stage verifier
`stop_classifier`	Ava rejects stop-classifier models

Where to Find OpenWakeWord Models

Easiest — browse in-app: Ava's Wake Word Library includes a community catalog that auto-syncs from the Ava repository. Open Settings → Voice Config → Wake Word Library to browse and download directly — no manual file handling.

Manual download from upstream:

openWakeWord — the original project by David Scripka
fwartner/home-assistant-wakewords-collection — Home Assistant community models by Florian Wartner
Train your own using the openWakeWord training pipeline

Import Steps

Obtain a .json manifest + .onnx model pair (float32 only)
Go to Settings → Voice Config → Wake Word Library
Tap Import wake word files
Select the .json file
If prompted, select the matching .onnx file
The wake word appears as "Ready" in the library
Tap it → Set as wake word (engine auto-switches to OpenWakeWord)

Advantage: OpenWakeWord's shared embedding architecture means each keyword model is small and independent. Adding a keyword does not add a new full inference path — it adds a tiny classifier head that reads the shared 96-dim embedding.

Compatibility: Ava uses the microWakeWord V2/V3 .tflite + .json format. Models from TaterTotterson/microWakeWords V3 directory work directly. OpenWakeWord imports are float32 .onnx + .json (openwakeword-v1 format) only.

Back to Voice Control

Uh oh!

Custom Wake Words

Custom Wake Words

Method 1: In-App Import (Recommended)

Supported File Types

Import Methods

Option A: Import a ZIP archive (batch)

Option B: Import a single JSON config

Option C: Add a model file to an existing entry

Managing Imported Wake Words

Method 2: APK Injection (Advanced)

Steps (MT Manager method)

Steps (desktop apktool method)

microWakeWord: Download Pretrained or Train Your Own

Option 1: Download Pretrained Models (Easiest)

Option 2: Train Your Own with macOS Trainer (Apple Silicon)

Option 3: Train with Direct Script

JSON Config Parameters

OpenWakeWord: ONNX Keyword Classifier Import

OpenWakeWord Manifest Format

Manifest Fields

Where to Find OpenWakeWord Models

Import Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Core

Optional Modules

Advanced

Clone this wiki locally