sirmrak/linux-voice-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated for the Release v1.0.0 codebase

Browse Source
This commit is contained in:
imonlinux
2025-10-11 18:07:59 -07:00
committed by GitHub
parent 1a5cc3005f
commit 5fcb8b2623
1 changed files with 83 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/linux-voice-assistant-2mic-install.md
+83 -138
View File
@@ -9,7 +9,7 @@
``` ```
> Modeled after the Wyoming Satellite two‑mic tutorial, adapted from actual shell history. > Modeled after the Wyoming Satellite two‑mic tutorial, adapted from actual shell history.
This guide reproduces a working setup of the **linux-voice-assistant** project with **Wyoming OpenWakeWord** or **MicroWakeWord** on a Raspberry PI Zero 2W and a Respeaker 2‑mic HAT (e.g., seeed-2mic-voicecard). It assumes a fresh system with sudo access and the default "pi" user. Included is the option to use PipeWire or PulseAudio instead of ALSA. This guide reproduces a working setup of the **linux-voice-assistant** project with **Wyoming OpenWakeWord** and **MicroWakeWord** on a Raspberry PI Zero 2W and a Respeaker 2‑mic HAT (e.g., seeed-2mic-voicecard). It assumes a fresh system with sudo access and the default "pi" user. Included is the option to use PipeWire or PulseAudio instead of ALSA.
## Prerequisites ## Prerequisites
- Raspberry Pi OS Lite (64-bit) - Raspberry Pi OS Lite (64-bit)
@@ -26,7 +26,7 @@ This guide reproduces a working setup of the **linux-voice-assistant** project w
sudo apt update sudo apt update
sudo apt upgrade sudo apt upgrade
sudo apt install libportaudio2 build-essential git \ sudo apt install libportaudio2 build-essential git \
libmpv-dev mpv python3.11-dev avahi-daemon avahi-utils libmpv-dev mpv python3.11-dev
sudo reboot sudo reboot
``` ```
@@ -47,21 +47,7 @@ sudo reboot
``` ```
## 4. Wyoming OpenWakeWord (OWW), skip to step 5. if using MicroWakeWord (MWW) ## 4. Linux Voice Assistant (LVA)
```bash
git clone https://github.com/rhasspy/wyoming-openwakeword.git
```
```bash
cp ~/linux-voice-assistant/wyoming-openwakeword/requirements.txt ~/wyoming-openwakeword/requirements.txt
cd wyoming-openwakeword/
script/setup
```
## 5. Linux Voice Assistant (LVA)
```bash ```bash
cd ~/linux-voice-assistant/ cd ~/linux-voice-assistant/
@@ -69,14 +55,14 @@ script/setup
``` ```
## 6. Choose your install option "Choose your Adventure!" ## 5. Choose your install option "Choose your Adventure!"
Pick **one** of the following install paths. Expand a section to see the exact steps. Pick **one** of the following install paths. Expand a section to see the exact steps.
> Tip: PipeWire options run services in *user* mode (requires `loginctl enable-linger`); PulseAudio/ALSA options run services in *system* mode. > Tip: All services run in *user* mode (requires `loginctl enable-linger`);
<details> <details>
<summary><strong>PipeWire + OpenWakeWord (user-mode services)</strong></summary> <summary><strong>PipeWire (user-mode services)</strong></summary>
**Prep (PipeWire):** Follow the PipeWire tutorial first: [the tutorial](install_pipewire.md). **Prep (PipeWire):** Follow the PipeWire tutorial first: [the tutorial](install_pipewire.md).
@@ -85,44 +71,13 @@ Pick **one** of the following install paths. Expand a section to see the exact s
sudo loginctl enable-linger pi sudo loginctl enable-linger pi
``` ```
**Install user-mode services:** **Install LVA user-mode services:**
```bash ```bash
mkdir -p ~/.config/systemd/user mkdir -p ~/.config/systemd/user
# LVA
cp ~/linux-voice-assistant/service/user-pw-oww-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
# OWW
cp ~/linux-voice-assistant/service/user-wyoming-openwakeword.service.service ~/.config/systemd/user/wyoming-openwakeword.service
``` ```
**Enable & start:**
```bash ```bash
systemctl --user daemon-reload cp ~/linux-voice-assistant/service/user-pw-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
systemctl --user enable --now wyoming-openwakeword.service
systemctl --user enable --now linux-voice-assistant.service
```
**Verify:**
```bash
systemctl --user status linux-voice-assistant wyoming-openwakeword --no-pager -l
```
</details>
<details>
<summary><strong>PipeWire + MicroWakeWord (user-mode services)</strong></summary>
**Prep (PipeWire):** Follow the PipeWire tutorial first: [the tutorial](install_pipewire.md).
**Enable linger:**
```bash
sudo loginctl enable-linger pi
```
**Install user-mode service:**
```bash
mkdir -p ~/.config/systemd/user
cp ~/linux-voice-assistant/service/user-pw-mww-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
``` ```
**Enable & start:** **Enable & start:**
@@ -138,54 +93,38 @@ systemctl --user status linux-voice-assistant --no-pager -l
</details> </details>
<details> <details>
<summary><strong>PulseAudio + OpenWakeWord (system services)</strong></summary> <summary><strong>PulseAudio (user-mode services)</strong></summary>
**Prep (PulseAudio):** Follow the PulseAudio tutorial first: [the tutorial](install_pulseaudio.md). **Prep (PulseAudio):** Follow the PulseAudio tutorial first: [the tutorial](install_pulseaudio.md).
**Install LVA (system) + tuning drop-in:** **Enable linger (required for user services to start after reboot):**
```bash ```bash
sudo cp ~/linux-voice-assistant/service/pa-oww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service sudo loginctl enable-linger pi
sudo mkdir -p /etc/systemd/system/linux-voice-assistant.service.d
sudo cp ~/linux-voice-assistant/service/10-tuning.conf /etc/systemd/system/linux-voice-assistant.service.d/10-tuning.conf
``` ```
**Install OWW (system):** **Install LVA user-mode services:**
```bash ```bash
sudo cp ~/linux-voice-assistant/service/wyoming-openwakeword.service /etc/systemd/system/wyoming-openwakeword.service mkdir -p ~/.config/systemd/user
```
```bash
cp ~/linux-voice-assistant/service/user-pa-linux-voice-assistant.service.service ~/.config/systemd/user/linux-voice-assistant.service
``` ```
**Enable & start:** **Enable & start:**
```bash ```bash
sudo systemctl daemon-reload systemctl --user daemon-reload
sudo systemctl enable --now wyoming-openwakeword linux-voice-assistant systemctl --user enable --now linux-voice-assistant.service
sudo systemctl status linux-voice-assistant wyoming-openwakeword --no-pager -l ```
**Verify:**
```bash
systemctl --user status linux-voice-assistant --no-pager -l
``` ```
</details> </details>
<details> <details>
<summary><strong>PulseAudio + MicroWakeWord (system services)</strong></summary> <summary><strong>ALSA (user-mode services)</strong></summary>
**Prep (PulseAudio):** Follow the PulseAudio tutorial first: [the tutorial](install_pulseaudio.md).
**Install LVA (system) + tuning drop-in:**
```bash
sudo cp ~/linux-voice-assistant/service/pa-mww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
sudo mkdir -p /etc/systemd/system/linux-voice-assistant.service.d
sudo cp ~/linux-voice-assistant/service/10-tuning.conf /etc/systemd/system/linux-voice-assistant.service.d/10-tuning.conf
```
**Enable & start:**
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now linux-voice-assistant
sudo systemctl status linux-voice-assistant --no-pager -l
```
</details>
<details>
<summary><strong>ALSA + OpenWakeWord (system services)</strong></summary>
**No extra audio stack needed.** If you’re using a different sound card/driver, confirm device names: **No extra audio stack needed.** If you’re using a different sound card/driver, confirm device names:
```bash ```bash
@@ -193,59 +132,34 @@ arecord -l
aplay -l aplay -l
``` ```
**Install LVA (system):** **Enable linger (required for user services to start after reboot):**
```bash ```bash
sudo cp ~/linux-voice-assistant/service/alsa-oww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service sudo loginctl enable-linger pi
``` ```
**Install OWW (system):** **Install LVA user-mode services:**
```bash ```bash
sudo cp ~/linux-voice-assistant/service/wyoming-openwakeword.service /etc/systemd/system/wyoming-openwakeword.service mkdir -p ~/.config/systemd/user
```
```bash
sudo cp ~/linux-voice-assistant/service/user-linux-voice-assistant.service ~/.config/systemd/user/linux-voice-assistant.service
``` ```
**Enable & start:** **Enable & start:**
```bash ```bash
sudo systemctl daemon-reload systemctl --user daemon-reload
sudo systemctl enable --now wyoming-openwakeword linux-voice-assistant systemctl --user enable --now linux-voice-assistant.service
sudo systemctl status linux-voice-assistant wyoming-openwakeword --no-pager -l ```
**Verify:**
```bash
systemctl --user status linux-voice-assistant --no-pager -l
``` ```
</details> </details>
<details> ## 6. Connect to Home Assistant
<summary><strong>ALSA + MicroWakeWord (system services)</strong></summary>
**No extra audio stack needed.** If you’re using a different sound card/driver, confirm device names:
```bash
arecord -l
aplay -l
```
**Install LVA (system):**
```bash
sudo cp ~/linux-voice-assistant/service/alsa-mww-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
```
**Enable & start:**
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now linux-voice-assistant
sudo systemctl status linux-voice-assistant --no-pager -l
```
</details>
<details>
<summary><strong>Optional: Advertise LVA to Home Assistant via Avahi</strong></summary>
**Generate & install ESPHome-style mDNS service:**
```bash
chmod +x ~/linux-voice-assistant/script/gen-esphome-avahi.sh
sudo ~/linux-voice-assistant/script/gen-esphome-avahi.sh
sudo systemctl restart avahi-daemon.service
```
</details>
## 7. Connect to Home Assistant
### If HA does not discover the new LVA: ### If HA does not discover the new LVA:
@@ -254,12 +168,12 @@ sudo systemctl restart avahi-daemon.service
3. Choose "ESPHome" and then "Set up another instance of ESPHome" 3. Choose "ESPHome" and then "Set up another instance of ESPHome"
4. Enter the IP address of your voice satellite with port 6053 4. Enter the IP address of your voice satellite with port 6053
5. Click "Submit" 5. Click "Submit"
6. During the registration process, use the wake word that you configured in your linux-voice-assistant.service file. Default is "alexa". 6. During the registration process, use the wake word that is displayed on the registration page. Default is "OK Nabu".
## 8. Verification ## 7. Verification
- Use "journalctl -u linux-voice-assistant.service -f" to check for errors for ALSA and PluseAudio. Debugging is enabled.
- Use "journalctl --user -u linux-voice-assistant.service -f" to check for errors when using PipeWire. Debugging is enabled. - Use "journalctl --user -u linux-voice-assistant.service -f" to check for errors. Debugging is enabled.
- Expect logs like `Connected to Home Assistant` - Expect logs like `Connected to Home Assistant`
- Look for `[OWW] Detection: name=...` followed by re-arming/cycling - Look for `[OWW] Detection: name=...` followed by re-arming/cycling
- Ask: *“What time is it?”* and confirm TTS reply - Ask: *“What time is it?”* and confirm TTS reply
@@ -268,7 +182,7 @@ sudo systemctl restart avahi-daemon.service
### Settings -> Voice assistants -> Assist (the assistant you configured) -> Text-to-speech -> Voice ### Settings -> Voice assistants -> Assist (the assistant you configured) -> Text-to-speech -> Voice
## 9. Change OWW detection model ## 8. Change OWW detection model
After the LVA is registered with HA, you can change the Wake Word model used in the ESPHome Voice Assistant entity. After the LVA is registered with HA, you can change the Wake Word model used in the ESPHome Voice Assistant entity.
@@ -285,18 +199,49 @@ ok_nabu_v0.1.tflite -> OK Nabo **(I had to say OK Nobu)**
Additional community provided OWW models available from this repository: Additional community provided OWW models available from this repository:
https://github.com/fwartner/home-assistant-wakewords-collection https://github.com/fwartner/home-assistant-wakewords-collection
You just copy the ones you want into the ~/wyoming-openwakeword/wyoming-openwakeword/models directory. If a model is currupted, the wyoming-openwakeword.service will fail to start. You just copy the ones you want into the ~/linux-voice-assistant/wakewords/openWakeWord directory. If a model is currupted, the LVA will fail to start.
Each model added will need a corresponding json file. (note the json file names matches the tflite name)
***Example***
Add Model:
```
/linux-voice-assistant/wakewords/openWakeWord/hal_v2.tflite
```
Create Json:
```
/linux-voice-assistant/wakewords/openWakeWord/hal_v2.json
```
Contents:
```
{
"type": "openWakeWord",
"wake_word": "HAL",
"model": "hal_v2.tflite"
}
```
**Word of warning. I have had problems with some of the community provided wake words. YMMV** **Word of warning. I have had problems with some of the community provided wake words. YMMV**
## 10. Switching between OWW and MWW. Or ALSA, PW, PA see section 6. ## 9. Switching between ALSA, PW, or PA see section 5.
If you intend to switch from PA to ALSA, you must first stop the pusleaudio.service. If you intend to switch from PA or PW to ALSA, you must first stop and disable the corresponding user-mode services.
###PulseAudio
```bash ```bash
sudo systemctl stop pulseaudio.service sudo systemctl --user stop pulseaudio.service
``` ```
```bash ```bash
sudo systemctl disable pulseaudio.service sudo systemctl --user disable pulseaudio.service
```
###PipeWire
```bash
sudo systemctl --user stop pipewire.service
```
```bash
sudo systemctl --user disable pipewire.service
``` ```