### Install Uv

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Install the uv tool, a fast Python package installer and copier.

```bash
# Install uv (if you don't have it)
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Setup without Configuration File

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/data-generation.md

Installs default Piper VITS artifacts to the specified data directory without requiring a configuration file. This is useful for initial setup or when a custom YAML is not yet available. VoxCPM is not downloaded in this mode.

```bash
livekit-wakeword setup --data-dir ./data
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Clone the repository and install the project dependencies, including extras for synchronization.

```bash
git clone https://github.com/livekit/livekit-wakeword
cd livekit-wakeword
uv sync --all-extras
```

--------------------------------

### Install LiveKit Wake Word with Uv

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Install the livekit-wakeword package with training, evaluation, and export capabilities using uv.

```bash
uv tool install livekit-wakeword[train,eval,export]
```

--------------------------------

### Adding a New TTS Backend: Optional Setup

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/data-generation.md

Guidance on extending the setup function to download backend-specific assets when a configuration file is provided.

```python
# Extend setup() in cli.py
# Branch on config.tts_backend to download necessary assets
# Use paths from the config
```

--------------------------------

### Install CLI Dependencies (Ubuntu/Debian)

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Install system dependencies for training custom wake words on Ubuntu/Debian systems.

```bash
# Ubuntu/Debian
sudo apt install espeak-ng libsndfile1 ffmpeg sox portaudio19-dev
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/livekit/livekit-wakeword/blob/main/AGENTS.md

Use 'uv sync' to install all dependencies, including optional groups. For development-only dependencies, use 'uv sync --group dev'.

```bash
uv sync                              # All deps including optional groups
uv sync --group dev                  # Dev only
```

--------------------------------

### Install LiveKit Wake Word with Pip

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Install the livekit-wakeword package with training, evaluation, and export capabilities using pip.

```bash
pip install livekit-wakeword[train,eval,export]
```

--------------------------------

### Install livekit-wakeword Python Package

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Installs the livekit-wakeword Python package using pip. Includes instructions for installing with the 'listener' extra for microphone support.

```bash
pip install livekit-wakeword
# or
uv add livekit-wakeword
```

```bash
pip install livekit-wakeword[listener]
```

--------------------------------

### Example Window Calculation

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/feature-extraction.md

Demonstrates the calculation of the number of windows for a specific input of 198 mel frames.

```text
n_windows = (198 - 76) / 8 + 1 = 16.25 → 16 windows
```

--------------------------------

### Install LiveKit Wake Word with VoxCPM

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Install the livekit-wakeword package with the 'voxcpm' optional dependency to enable TTS synthesis.

```bash
pip install livekit-wakeword[train,eval,export,voxcpm]
```

--------------------------------

### Install CLI Dependencies (macOS)

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Install system dependencies for training custom wake words on macOS using Homebrew.

```bash
# macOS
brew install espeak-ng ffmpeg portaudio
```

--------------------------------

### Install PortAudio for Microphone Listener

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Installs the PortAudio library, a system dependency required for microphone listening functionality on macOS and Ubuntu/Debian.

```bash
# macOS
brew install portaudio
```

```bash
# Ubuntu/Debian
sudo apt install portaudio19-dev
```

--------------------------------

### Install XcodeGen

Source: https://github.com/livekit/livekit-wakeword/blob/main/examples/ios_wakeword/README.md

Installs XcodeGen using Homebrew, a tool for regenerating the Xcode project from project.yml.

```shell
brew install xcodegen
```

--------------------------------

### Install TFLite Extra

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/export-and-inference.md

Install the 'tflite' extra for LiveKit Wakeword to enable TFLite export functionality. This can be done using uv sync or pip.

```bash
uv sync --extra tflite
```

```bash
pip install 'livekit-wakeword[tflite]'
```

--------------------------------

### Run Data Generation CLI

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/data-generation.md

Initiates the data generation process using a specified configuration file. Ensure 'espeak-ng' is installed for phonemization.

```bash
livekit-wakeword generate <config>
```

--------------------------------

### Adding a New TTS Backend: Config File Setup

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/data-generation.md

Steps for configuring a new TTS backend, including adding a new member to TtsBackend enum and defining engine-specific fields in the configuration.

```python
# Add a new member to TtsBackend in config.py
# e.g., qwen_tts = "qwen_tts"

# Add engine-specific fields to WakeWordConfig
# e.g., nested models or top-level keys

# Put backend defaults in a new module under defaults/ (e.g., defaults/qwen_tts.py)
```

--------------------------------

### CLI Commands for LiveKit Wake Word

Source: https://github.com/livekit/livekit-wakeword/blob/main/AGENTS.md

Execute various CLI commands for setup, data generation, augmentation, training, export, and running the full pipeline.

```bash
uv run livekit-wakeword setup [--config YAML]   # Data deps; Piper if piper_vits / VoxCPM snapshot if voxcpm; else always Piper when no --config
uv run livekit-wakeword generate <config> # VITS TTS + SLERP speaker blending + adversarial negatives
uv run livekit-wakeword augment <config>  # Augment + extract features → .npy
uv run livekit-wakeword train <config>    # 3-phase adaptive training
uv run livekit-wakeword export <config>   # Export classifier to ONNX
uv run livekit-wakeword run <config>      # Full pipeline (generate→augment→extract→train→export)
```

--------------------------------

### Initialize WakeWordModel and Predict

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/export-and-inference.md

Instantiate WakeWordModel with paths to ONNX classifiers and use the predict method with an audio chunk to get confidence scores. The model expects approximately 2 seconds of 16kHz audio.

```python
from livekit.wakeword import WakeWordModel

model = WakeWordModel(models=["hey_livekit.onnx"])

# Pass ~2 seconds of 16kHz audio
scores = model.predict(audio_chunk)
# Returns: {"hey_livekit": 0.95}
```

--------------------------------

### WakeWordListener Example

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/export-and-inference.md

Demonstrates how to use WakeWordListener to detect wake words from the microphone. Ensure you have 'hey_livekit.onnx' model available. The listener resets its state when entering a new async with block.

```python
import asyncio
from livekit.wakeword import WakeWordModel, WakeWordListener

model = WakeWordModel(models=["hey_livekit.onnx"])

async def main():
    async with WakeWordListener(model, threshold=0.5, debounce=2.0) as listener:
        while True:
            detection = await listener.wait_for_detection()
            print(f"Detected {detection.name}! ({detection.confidence:.2f})")

asyncio.run(main())
```

--------------------------------

### Install Shared Data and TTS Artifacts

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/data-generation.md

Installs shared data (features, RIRs, backgrounds) and backend-specific TTS weights based on the provided configuration file. Piper VITS or VoxCPM2 weights are downloaded only if selected in the config.

```bash
livekit-wakeword setup --config configs/prod.yaml
```

--------------------------------

### Export to TFLite Format

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Install the TFLite extra and export the model in a TFLite format compatible with openWakeWord. This requires the 'tflite' extra.

```bash
pip install livekit-wakeword[tflite]
```

```bash
livekit-wakeword export configs/prod.yaml --format tflite
```

--------------------------------

### Example Evaluation Metrics JSON

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/evaluation.md

A sample JSON output detailing the evaluation metrics, including AUT, FPPH, recall, accuracy, and threshold.

```json
{
  "aut": 0.0012,
  "fpph": 0.08,
  "recall": 0.861,
  "accuracy": 0.93,
  "threshold": 0.68,
  "n_positive": 15000,
  "n_negative": 45084,
  "validation_hours": 25.05
}
```

--------------------------------

### Python Basic Inference

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Feed audio frames to the model and get wake word scores. Use this for direct audio processing.

```python
scores = model.predict(audio_frame)
if scores["hey_livekit"] > 0.5:
    print("Wake word detected!")
```

--------------------------------

### Export Model to TFLite

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/export-and-inference.md

Export a trained model to TFLite format using the CLI. This requires the 'tflite' extra to be installed. The `--format tflite` flag specifies the output format.

```bash
livekit-wakeword export configs/hey_jarvis.yaml --format tflite
```

--------------------------------

### Launch Training Job with SkyPilot

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Launch a training job on cloud GPUs using SkyPilot by specifying a training configuration file.

```bash
sky launch skypilot/train.yaml
```

--------------------------------

### 3-Phase Training Overview

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/training.md

This diagram illustrates the sequential phases of the training pipeline: Full Training, Refinement, and Fine-Tuning, followed by checkpoint averaging and threshold optimization.

```text
.npy features (N, 16, 96)
    │
    ▼
Phase 1: Full Training
    LR warmup → hold → cosine decay
    Focal loss + negative weighting + embedding mixup
    │
    ▼
Phase 2: Refinement
    0.1× LR, steps/10 steps
    Adaptive negative weight doubling
    │
    ▼
Phase 3: Fine-Tuning
    0.01× LR, steps/10 steps
    │
    ▼
Checkpoint Averaging
    Select top checkpoints by FPPH + recall + accuracy
    Average their weights
    │
    ▼
Threshold Optimization
    Scan 0.01–0.99 to maximize recall at target FPPH
    │
    ▼
Final model (.pt)
```

--------------------------------

### Basic Wakeword Inference in Python

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Demonstrates how to initialize a WakeWordModel with a specified model file for basic inference.

```python
from livekit.wakeword import WakeWordModel

model = WakeWordModel(models=["hey_livekit.onnx"])
```

--------------------------------

### Focal Loss Formula

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/training.md

The formula for Focal Loss, which down-weights well-classified examples using a modulating factor (1 - p_t)^γ.

```latex
FL(p_t) = -(1 - p_t)^γ · log(p_t)
```

--------------------------------

### Initialize AudioAugmentor

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/augmentation.md

Initializes the AudioAugmentor with paths to background noise and RIR files. The sample rate defaults to 16000 Hz.

```python
AudioAugmentor(
    background_paths: list[Path],  # Directories with background noise .wav files
    rir_paths: list[Path],         # Directories with room impulse response .wav files
    sample_rate: int = 16000
)
```

--------------------------------

### Train a Wake Word

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Run the full wake word training pipeline using the specified configuration file.

```bash
livekit-wakeword run configs/prod.yaml
```

--------------------------------

### Run CLI Evaluation

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/evaluation.md

Execute the evaluation pipeline using the command-line interface with a specified configuration file.

```bash
uv run livekit-wakeword eval configs/hey_livekit.yaml
```

--------------------------------

### Swift Async Listener with Microphone

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Set up an asynchronous listener for microphone input to detect wake words. Requires microphone usage descriptions in Info.plist.

```swift
import LiveKitWakeWord

let classifier = Bundle.main.url(forResource: "hey_livekit", withExtension: "onnx")!
let model = try WakeWordModel(models: [classifier], sampleRate: 16_000)
let listener = WakeWordListener(model: model, threshold: 0.5, debounce: 2.0)

try await listener.start()
for await detection in listener.detections() {
    print("Detected \(detection.name)! (confidence=\(String(format: "%.2f", detection.confidence)))")
}
```

--------------------------------

### Compare Models with CLI

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/evaluation.md

Use the CLI to evaluate different ONNX models, useful for comparing performance across various training configurations or frameworks.

```bash
uv run livekit-wakeword eval configs/hey_livekit.yaml -m models/conv_attention_medium.onnx
```

--------------------------------

### WakeWordListener Initialization

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/export-and-inference.md

Shows the parameters for initializing WakeWordListener. The `model` parameter requires a WakeWordModel instance. `threshold` controls detection sensitivity, and `debounce` sets the minimum time between detections.

```python
WakeWordListener(
    model: WakeWordModel,    # WakeWordModel instance with loaded classifiers
    threshold: float = 0.5,  # Detection threshold (0-1)
    debounce: float = 2.0    # Minimum seconds between detections
)
```

--------------------------------

### Export Model to ONNX with Quantization

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/export-and-inference.md

Use the CLI to export a trained model to ONNX format and apply dynamic INT8 quantization. The `--quantize` flag enables quantization.

```bash
livekit-wakeword export configs/hey_jarvis.yaml --quantize
```

--------------------------------

### Run Individual Training Stages

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Execute specific stages of the wake word training pipeline individually, such as TTS synthesis, augmentation, training, export, or evaluation.

```bash
livekit-wakeword generate configs/prod.yaml  # TTS synthesis + adversarial negatives
```

```bash
livekit-wakeword augment configs/prod.yaml   # Augment + extract features
```

```bash
livekit-wakeword train configs/prod.yaml     # 3-phase adaptive training
```

```bash
livekit-wakeword export configs/prod.yaml    # Export to ONNX (default)
```

```bash
livekit-wakeword eval configs/prod.yaml      # Evaluate model (DET curve, AUT, FPPH)
```

--------------------------------

### Swift Package for LiveKit Wake Word

Source: https://github.com/livekit/livekit-wakeword/blob/main/AGENTS.md

Details on the Swift package for iOS and macOS, utilizing ONNX Runtime with CoreML Execution Provider for efficient inference.

```swift
// LiveKitWakeWord Swift package: ONNX Runtime-based pipeline for iOS 16+ / macOS 14+.
// WakeWordModel (stateless predict) + WakeWordListener (actor around AVAudioEngine).
// The mel + embedding .onnx files from src/livekit/wakeword/resources/ are bundled as package resources;
// classifier .onnx files are loaded from disk. ORT's CoreML Execution Provider (ANE/GPU/CPU) is used by default via ExecutionProvider.coreML.
// Depends on the [official ORT SPM package](https://github.com/microsoft/onnxruntime-swift-package-manager).

// Example usage (conceptual):
// import LiveKitWakeWord
//
// // Initialize listener
// let listener = try WakeWordListener(modelPath: "path/to/classifier.onnx")
// listener.start()
//
// // Handle wake word detection
// Task { @MainActor in
//   for await event in listener.events {
//     switch event {
//     case .wakeWordDetected(let score):
//       print("Wake word detected with score: \(score)")
//     case .error(let error):
//       print("Error: \(error)")
//     }
//   }
// }

```

--------------------------------

### Wake Word Processing Pipeline (Inference)

Source: https://github.com/livekit/livekit-wakeword/blob/main/AGENTS.md

Diagram illustrating the inference pipeline from raw audio to a wake word score, detailing the ONNX and PyTorch components.

```text
Raw audio (16kHz) → MelSpectrogramFrontend (ONNX) → SpeechEmbedding (ONNX) → Classifier (PyTorch) → [0,1]
                    n_fft=512, hop=160, n_mels=32     76×32×1 → 96-dim         16×96 → 1 score
```

--------------------------------

### Lint and Format Code with Ruff and Mypy

Source: https://github.com/livekit/livekit-wakeword/blob/main/AGENTS.md

Utilize Ruff for linting and formatting, and Mypy for type checking. Ensure code quality and adherence to standards.

```bash
uv run ruff check src/ tests/       # Lint (rules: E, F, I, UP)
uv run ruff format src/ tests/      # Auto-format
uv run mypy src/livekit/wakeword/       # Type check (strict mode)
```

--------------------------------

### Python API for Wake Word Training Pipeline

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Import and use the LiveKit Wake Word Python API to drive the full training pipeline from your own code.

```python
from livekit.wakeword import (
    WakeWordConfig,
    load_config,
    run_generate,
    run_augment,
    run_extraction,
    run_train,
    run_export,
    run_eval,
)

# Load from YAML or construct directly
config = load_config("configs/prod.yaml")

# Or build a config programmatically
config = WakeWordConfig(
    model_name="hey_robot",
    target_phrases=["hey robot"],
    n_samples=5000,
    steps=30000,
)

# Run individual stages
run_generate(config)     # TTS synthesis + adversarial negatives
run_augment(config)      # Add noise, reverb, pitch shifts
run_extraction(config)   # Extract mel spectrograms + speech embeddings → .npy
run_train(config)        # 3-phase adaptive training
onnx_path = run_export(config)       # Export to ONNX

# Evaluate the exported model
results = run_eval(config, onnx_path)
print(f"AUT={results['aut']:.4f}  FPPH={results['fpph']:.2f}  Recall={results['recall']:.1%}")
```

--------------------------------

### Python API for Wake Word Training Pipeline

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

This snippet demonstrates how to use the LiveKit Wake Word Python API to load configurations, run individual training stages, and evaluate the exported model.

```APIDOC
## Python API

The full training pipeline is available as a Python API, so you can import and drive it from your own code instead of using the CLI:

```python
from livekit.wakeword import (
    WakeWordConfig,
    load_config,
    run_generate,
    run_augment,
    run_extraction,
    run_train,
    run_export,
    run_eval,
)

# Load from YAML or construct directly
config = load_config("configs/prod.yaml")

# Or build a config programmatically
config = WakeWordConfig(
    model_name="hey_robot",
    target_phrases=["hey robot"],
    n_samples=5000,
    steps=30000,
)

# Run individual stages
run_generate(config)     # TTS synthesis + adversarial negatives
run_augment(config)      # Add noise, reverb, pitch shifts
run_extraction(config)   # Extract mel spectrograms + speech embeddings → .npy
run_train(config)        # 3-phase adaptive training
onnx_path = run_export(config)       # Export to ONNX

# Evaluate the exported model
results = run_eval(config, onnx_path)
print(f"AUT={results['aut']:.4f}  FPPH={results['fpph']:.2f}  Recall={results['recall']:.1%}")
```

This is useful for integrating wake word training into larger pipelines, automating model iteration, or building custom tooling on top of the data generation and training stages.
```

--------------------------------

### Output Directory Structure for Generated Data

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/data-generation.md

Illustrates the expected directory layout for training and validation clips after data generation. This structure helps organize positive, negative, and background noise samples.

```text
output/<model_name>/
├── positive_train/      # Positive training clips (.wav)
├── positive_test/       # Positive validation clips (.wav)
├── negative_train/      # Adversarial negative training clips (.wav)
├── negative_test/       # Adversarial negative validation clips (.wav)
├── background_train/    # Background noise training clips (.wav)
└── background_test/     # Background noise validation clips (.wav)
```

--------------------------------

### Adding a New TTS Backend: Implementation Class

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/data-generation.md

Details on creating a new module and class for a TTS backend that satisfies the SpeechSynthesizer interface. This includes implementing validation and synthesis methods.

```python
# Add a module under data/ (e.g., data/qwen_tts/)

# Class must satisfy SpeechSynthesizer in tts/backends.py

# Implement validate_artifacts(): ensure required assets exist
# Implement synthesize_clips(): write .wav files at 16 kHz
```

--------------------------------

### Run Model Evaluation

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/evaluation.md

Execute the livekit-wakeword evaluation command with a specified configuration and model. This command is used to test the performance of an openWakeWord model against a predefined validation dataset.

```bash
uv run livekit-wakeword eval configs/hey_livekit.yaml -m models/hey_livekit_oww.onnx
```

--------------------------------

### Configure TTS Backend

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

To use multilingual models, specify the TTS backend in your configuration YAML file.

```yaml
tts_backend: voxcpm
```

--------------------------------

### MelSpectrogramFrontend Fallback to Torchaudio

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/feature-extraction.md

If the ONNX model file is not found, MelSpectrogramFrontend falls back to using torchaudio.transforms.MelSpectrogram. Note that slight numerical differences may exist as the ONNX model was built with torchlibrosa.

```python
from torchaudio.transforms import MelSpectrogram

mel_spectrogram = MelSpectrogram(
    sample_rate=16000,
    n_fft=512,
    hop_length=160,
    win_length=400,
    n_mels=32,
    f_min=60,
    f_max=3800,
    power=2.0,
    center=False,
    pad_mode="reflect",
    norm="slaney",
    mel_scale="slaney",
)

# Example usage:
audio_tensor = torch.randn(1, 16000) # 1 second of audio
mels = mel_spectrogram(audio_tensor)
print(mels.shape) # (batch, n_mels, time_frames)
```

--------------------------------

### OpenWakeWord Classifier Architecture

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Illustrates the architecture of the openWakeWord classifier, which flattens audio features before feeding them into a dense neural network.

```text
Flatten(16×96=1536) → Dense → Dense → Sigmoid
```

--------------------------------

### Cosine Warmup Learning Rate Schedule

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/training.md

Defines a learning rate schedule with linear warmup, a hold period, and cosine decay. Phases 2 and 3 omit warmup and hold steps.

```python
_cosine_warmup_schedule(step, total_steps, warmup_steps, hold_steps, base_lr)
```

--------------------------------

### iOS Wake Word SwiftUI Demo App

Source: https://github.com/livekit/livekit-wakeword/blob/main/AGENTS.md

Description of the SwiftUI demo app for iOS and macOS, demonstrating the Swift package's wake word detection capabilities.

```swift
// SwiftUI demo app (iOS + macOS) that consumes the swift/ package via a local SPM dependency (path: ../../swift).
// WakewordEngine wraps AVAudioEngine + a 2 s Int16 ring buffer + background WakeWordModel.predict();
// ContentView renders score/volume graphs and an execution-provider picker.
// Generated from project.yml via xcodegen.

// Example structure (conceptual):
// import SwiftUI
// import LiveKitWakeWord
//
// class WakewordEngine: ObservableObject {
//   private var listener: WakeWordListener?
//   @Published var wakeWordScore: Double = 0.0
//   @Published var isListening: Bool = false
//
//   func startListening(modelPath: String) {
//     // Initialize and start WakeWordListener
//     // ...
//     isListening = true
//   }
//
//   func stopListening() {
//     // Stop and deinitialize WakeWordListener
//     // ...
//     isListening = false
//   }
// }
//
// struct ContentView: View {
//   @StateObject private var engine = WakewordEngine()
//
//   var body: some View {
//     VStack {
//       Text("Wake Word Score: \(engine.wakeWordScore)")
//       Button(engine.isListening ? "Stop Listening" : "Start Listening") {
//         if engine.isListening {
//           engine.stopListening()
//         } else {
//           engine.startListening(modelPath: "path/to/classifier.onnx")
//         }
//       }
//       // ... other UI elements like execution provider picker
//     }
//   }
// }

```

--------------------------------

### Swift Basic Inference

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Load a wake word model and predict scores from audio chunks. Ensure the ONNX classifier is included in your app bundle.

```swift
import LiveKitWakeWord

let classifier = Bundle.main.url(forResource: "hey_livekit", withExtension: "onnx")!
let model = try WakeWordModel(models: [classifier], sampleRate: 16_000)

// Feed ~2 s PCM chunks (Int16, at the configured sample rate):
let scores = try model.predict(audioChunk)
if (scores["hey_livekit"] ?? 0) > 0.5 {
    print("Wake word detected!")
}
```

--------------------------------

### Adding a New TTS Backend: Registry Update

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/data-generation.md

Instructions for mapping the new TtsBackend enum value to its corresponding implementation class in the get_tts_backend function.

```python
# In get_tts_backend() in tts/backends.py
# Map your TtsBackend value to your class
# e.g., return YourBackend.from_config(config)
```

--------------------------------

### Configure Background Noise Samples

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/training.md

Set the number of background noise samples for training and validation. Add custom background noise sources by specifying paths in `augmentation.background_paths`.

```yaml
n_background_samples: 200
n_background_samples_val: 40

augmentation:
  background_paths:
    - ./data/backgrounds        # default MUSAN noise
    - ./data/my-office-noise    # your custom recordings
```

--------------------------------

### Minimum Wake Word Configuration

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Defines the essential parameters for a wake word configuration, including model name, target phrases, training samples, model type and size, training steps, and target false positives per hour.

```yaml
model_name: hey_livekit
target_phrases:
  - "hey livekit"

n_samples: 10000 # training samples per class
model:
  model_type: conv_attention # conv_attention, dnn, or rnn
  model_size: small # tiny, small, medium, large
steps: 50000
target_fp_per_hour: 0.2
```

--------------------------------

### LiveKit Wakeword Module Map

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/overview.md

A map of the livekit-wakeword project structure, detailing the purpose of each module and file.

```python
src/livekit/wakeword/
├── config.py                    Pydantic config models + YAML loading
├── cli.py                       Typer CLI (setup, generate, augment, train, export, eval, run)
├── models/
│   ├── feature_extractor.py     MelSpectrogramFrontend + SpeechEmbedding (ONNX)
│   ├── classifier.py            DNNClassifier, RNNClassifier, ConvAttentionClassifier
│   └── pipeline.py              WakeWordClassifier (training wrapper for classifier head)
├── data/
│   ├── generate.py              TTS orchestration (default Piper VITS) + adversarial negatives
│   ├── piper/                   Piper VITS + SLERP synthesis stack
│   ├── tts/                     Pluggable SpeechSynthesizer backends
│   ├── augment.py               AudioAugmentor + clip alignment
│   ├── dataset.py               WakeWordDataset (memory-mapped .npy batch generator)
│   └── features.py              ONNX feature extraction → .npy files
├── training/
│   ├── trainer.py               WakeWordTrainer (3-phase training + checkpoint averaging)
│   └── metrics.py               FPPH, recall, balanced accuracy
├── eval/
│   └── evaluate.py              DET curve, AUT, FPPH evaluation + plotting
├── export/
│   └── onnx.py                  ONNX export + INT8 quantization
└── inference/
    ├── model.py                 WakeWordModel class (simple prediction API)
    └── listener.py              WakeWordListener class (async microphone detection)
```

--------------------------------

### Rust Basic Inference

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Load a wake word model and predict scores from audio chunks. Audio is automatically resampled to 16 kHz.

```rust
use livekit_wakeword::WakeWordModel;

let mut model = WakeWordModel::new(&["hey_livekit.onnx"], 16000)?;

// Feed ~2s PCM audio chunks (i16, at configured sample rate)
let scores = model.predict(&audio_chunk)?;
if scores["hey_livekit"] > 0.5 {
    println!("Wake word detected!");
}
```

--------------------------------

### Regenerate Xcode Project

Source: https://github.com/livekit/livekit-wakeword/blob/main/examples/ios_wakeword/README.md

Generates the Xcode project from the project.yml specification file.

```shell
xcodegen generate
```

--------------------------------

### Multilingual Model Configuration

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

To improve multilingual performance, increase the number of voice design prompts and samples in your configuration.

```yaml
n_samples: 50000 # ↑ from 25000
n_samples_val: 10000 # ↑ from 5000

voxcpm_tts:
  voice_design_prompts:
    # Add 50-100 diverse prompts covering age, gender, pitch, pace, accent, energy, etc.
    - "A young adult woman, clear mid-pitch voice, moderate pace, calm and professional"
    - "A young adult man, warm baritone, steady pace, friendly and articulate"
    - "A middle-aged woman, slightly low pitch, measured pace, confident tone"
    # ... add more prompts for wider speaker diversity
```

--------------------------------

### Run Pytest for Testing

Source: https://github.com/livekit/livekit-wakeword/blob/main/AGENTS.md

Execute tests using Pytest. Supports running all tests, single files, specific tests by name, or with code coverage.

```bash
uv run pytest tests/                 # All tests
uv run pytest tests/test_config.py   # Single file
uv run pytest -k "test_name"         # Single test
uv run pytest --cov=src/livekit/wakeword tests/  # With coverage
```

--------------------------------

### Align Positive Clips to End

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/augmentation.md

Places positive clips at the end of a target window with random jitter. This simulates the wake word appearing at the trailing edge of an audio buffer.

```python
align_clip_to_end(audio, target_length, jitter_samples=3200)
```

--------------------------------

### Align Negative Clips (Center-Padded/Cropped)

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/augmentation.md

Centers negative clips within a target window. Clips longer than the target are center-cropped, while shorter clips are center-padded with zeros.

```python
Negative clips are centered within the target window. If longer than the target, they are center-cropped; if shorter, they are center-padded with zeros.
```

--------------------------------

### Evaluate External ONNX Model

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Evaluate any compatible ONNX model, including those trained with openWakeWord, using the project's evaluation tools.

```bash
livekit-wakeword eval configs/prod.yaml -m /path/to/other_model.onnx
```

--------------------------------

### Swift Package Dependency

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Add the LiveKitWakeWord Swift package to your iOS or macOS project.

```swift
.package(url: "https://github.com/livekit/livekit-wakeword", branch: "main")
```

--------------------------------

### Run CLI Evaluation with Specific Model

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/evaluation.md

Evaluate a specific ONNX model by providing its path, overriding the default model location.

```bash
uv run livekit-wakeword eval configs/hey_livekit.yaml -m /path/to/model.onnx
```

--------------------------------

### Checkpoint Weight Averaging

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/training.md

Qualifying checkpoints are averaged by stacking their parameter tensors to produce a smoother, more generalizable model.

```python
averaged[key] = mean(stack([ckpt[key] for ckpt in selected]))
```

--------------------------------

### Run Python API Evaluation

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/evaluation.md

Perform model evaluation programmatically using the Python API. Load a configuration and model path, then call the run_eval function.

```python
from pathlib import Path
from livekit.wakeword import load_config
from livekit.wakeword.eval.evaluate import run_eval

config = load_config("configs/hey_livekit.yaml")
model_path = Path("output/hey_livekit/hey_livekit.onnx")

results = run_eval(config, model_path)
# results = {
#     "aut": 0.0012,
#     "fpph": 0.08,
#     "recall": 0.861,
#     "accuracy": 0.93,
#     "threshold": 0.68,
#     "n_positive": 15000,
#     "n_negative": 45084,
#     "validation_hours": 25.05,
# }
```

--------------------------------

### Negative Weight Schedule Calculation

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/training.md

Calculates a linearly increasing negative weight from 1.0 to a specified maximum over the total training steps.

```python
_negative_weight_schedule(step, total_steps, max_weight)

weight = 1.0 + (max_weight - 1.0) * step / total_steps
```

--------------------------------

### Rust Wake Word Dependency

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Add the livekit-wakeword crate to your Rust project's dependencies.

```toml
[dependencies]
livekit-wakeword = "0.1"
```

--------------------------------

### Calculate Number of Windows

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/feature-extraction.md

Formula to calculate the number of sliding windows based on total time frames, window size, and stride. Used when processing audio longer than the model's context window.

```text
n_windows = floor((time_frames - window_size) / stride) + 1
          = floor((time_frames - 76) / 8) + 1
```

--------------------------------

### Mel Spectrogram Parameters

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/overview.md

Key parameters for generating mel spectrograms, including sample rate, FFT size, hop length, window length, and mel bands.

```markdown
| Parameter | Value |
|-----------|-------|
| Sample rate | 16000 Hz |
| FFT size | 512 |
| Hop length | 160 (10ms) |
| Window length | 400 (25ms) |
| Mel bands | 32 |
| Frequency range | 60–3800 Hz |
| Centering | Disabled |
| Normalization | `power_to_db / 10 + 2` |
```

--------------------------------

### Data Flow: Feature Dimensions

Source: https://github.com/livekit/livekit-wakeword/blob/main/docs/overview.md

This table outlines the data dimensions at each stage of the livekit-wakeword processing pipeline, from raw audio to the final classifier output.

```markdown
| Stage | Output Shape | Description |
|-------------|-------------|-------------|
| Raw audio | `(samples,)` | 16kHz float32 mono |
| MelSpectrogramFrontend | `(batch, time_frames, 32)` | 32 mel bands, ~5 frames per 80ms |
| SpeechEmbedding | `(batch, n_windows, 96)` | 76-frame sliding window, stride 8 |
| Timestep selection | `(batch, 16, 96)` | Last 16 windows (or left-padded) |
| Classifier | `(batch, 1)` | Sigmoid confidence score |
```

--------------------------------

### LiveKit WakeWord Conv-Attention Classifier Architecture

Source: https://github.com/livekit/livekit-wakeword/blob/main/README.md

Details the architecture of the LiveKit WakeWord Conv-Attention classifier, highlighting the use of 1D convolutions and multi-head self-attention for improved temporal pattern recognition.

```text
Conv1D blocks → MultiheadAttention → Mean pool → Linear(1) → Sigmoid
```