From ade6fa54b0bbcf2b9f7af1b5fddce547a096ed37 Mon Sep 17 00:00:00 2001
From: slgotting <sgotting21@gmail.com>
Date: Tue, 24 Mar 2026 10:13:12 -0400
Subject: [PATCH] Enhance README with detailed openWakeWord information

Expanded the README to include detailed information about wake word detection, its role in the voice pipeline, common uses, installation instructions, and features of openWakeWord.
---
 openwakeword/README.md | 164 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 157 insertions(+), 7 deletions(-)

diff --git a/openwakeword/README.md b/openwakeword/README.md
index ba53554a8..1ad54788d 100644
--- a/openwakeword/README.md
+++ b/openwakeword/README.md
@@ -1,12 +1,162 @@
-# Home Assistant App: openWakeWord
+# openWakeWord – Home Assistant App
 
-![Supports aarch64 Architecture][aarch64-shield] ![Supports amd64 Architecture][amd64-shield]
+**openWakeWord** adds wake-word detection to Home Assistant’s voice system. It listens to microphone audio and triggers the voice pipeline when a chosen phrase (the *wake word*) is spoken.
 
-Home Assistant app (formerly known as add-on) that uses [pyopen-wakeword](https://github.com/rhasspy/pyopen-wakeword) for wake word detection.
+It uses **pyopen-wakeword** to perform fast, local detection with very low CPU usage, making it ideal for devices like Raspberry Pi or other small voice satellites.
 
-Part of the [Year of Voice](https://www.home-assistant.io/blog/2022/12/20/year-of-voice/).
+Part of Home Assistant’s **Year of Voice** initiative.
 
-Requires Home Assistant 2023.9 or later.
+---
+
+# What a Wake Word Is
+
+A **wake word** is the phrase used to activate a voice assistant.
+
+Example:
+
+```
+User: "Hey Jarvis"
+Assistant: *starts listening*
+User: "Turn off the kitchen lights"
+Home Assistant: executes the command
+```
+
+Without a wake word, the system would need to continuously run full speech recognition, which is expensive and raises privacy concerns.
+
+Wake word detection solves this by only activating the assistant when the trigger phrase is heard.
+
+---
+
+# Where It Fits in the Voice Pipeline
+
+Wake word detection is the **first step** in Home Assistant’s voice pipeline:
+
+```
+Microphone
+   ↓
+Wake Word Detection (openWakeWord)
+   ↓
+Speech-to-Text
+   ↓
+Intent Processing
+   ↓
+Automation / Action
+   ↓
+Text-to-Speech
+```
+
+openWakeWord continuously monitors audio and signals Home Assistant when the wake phrase is detected.
+
+---
+
+# Common Uses
+
+### Voice Satellites
+
+Small devices placed around the house that listen for the wake word.
+
+Example:
+
+```
+"Okay Home, turn on the porch light"
+```
+
+The satellite detects the wake word and forwards the command to Home Assistant.
+
+---
+
+### Fully Local Voice Assistants
+
+openWakeWord enables a **completely local voice assistant** when combined with local:
+
+* Speech-to-text
+* Intent recognition
+* Text-to-speech
+
+---
+
+### Custom Wake Words
+
+Multiple wake words can be used depending on context:
+
+* “Jarvis”
+* “Computer”
+* “Okay Home”
+
+---
+
+# Installation
+
+1. Open **Home Assistant**.
+2. Go to **Settings → Add-ons → Add-on Store**.
+3. Install **openWakeWord**.
+4. Start the add-on.
+
+Requires **Home Assistant 2023.9+**
+
+Supported architectures:
+
+* **aarch64**
+* **amd64**
+
+---
+
+# How to Implement It
+
+## 1. Install the Add-on
+
+Install and start **openWakeWord** from the Add-on Store.
+
+---
+
+## 2. Configure a Voice Pipeline
+
+Navigate to:
+
+```
+Settings → Voice Assistants → Pipelines
+```
+
+Create or edit a pipeline and select:
+
+* **Wake Word Detection:** openWakeWord
+
+You will also need:
+
+* Speech-to-text provider
+* Conversation agent
+* Text-to-speech provider (optional)
+
+---
+
+## 3. Connect a Microphone
+
+Wake word detection requires a microphone source such as:
+
+* Voice satellite device
+* Browser microphone
+* ESPHome voice device
+* Assist microphone hardware
+
+---
+
+## 4. Test It
+
+Speak the configured wake phrase:
+
+```
+"Okay Home"
+```
+
+When detected, the voice assistant will begin processing the command that follows.
+
+---
+
+# Features
+
+* Local wake word detection
+* Low CPU usage
+* Multiple wake word models
+* Works with Home Assistant Assist pipeline
+* Designed for edge voice devices
 
-[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
-[amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg