Merge pull request #10 from imonlinux/imonlinux-patch-1

Add tutorial for PA and alternate service file
2025-09-12 13:33:25 -07:00
parent 30683cf718 734c0b7cf4
commit bf74160528
4 changed files with 210 additions and 32 deletions
@@ -0,0 +1,119 @@
+## Install PulseAudio On Your Wyoming Voice Satellite
+
+> Courtesy of https://github.com/FutureProofHomes/wyoming-enhancements/blob/master/snapcast/docs/2_install_pulseaudio.md with minor modifications
+
+## 1. Connect to your Pi over SSH using the username/password you configured during flashing:
+
+```sh
+ssh <your_username>@<pi_IP_address>
+```
+
+
+## 2. If already installed Disable/Stop the entire the Linux Voice Assistant service temporarily. If not installed, proceed to setp 3.:
+
+```sh
+sudo systemctl disable --now linux-voice-assistant.service
+```
+
+
+## 3. Install PulseAudio drivers and necessary utilities:
+
+```sh
+sudo apt-get update
+sudo apt-get install \
+    pulseaudio \
+    pulseaudio-utils \
+    pamixer
+```
+
+
+## 4. Reboot your Pi:
+
+```sh
+sudo reboot -h now
+```
+
+
+## 5. SSH back in to your Pi.  (See step 1.)
+
+
+## 6. Ensure PulseAudio is runnining in "system-wide mode".  Per the [official instructions](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SystemWide/) we first need to stop some existing services to be safe:
+
+```sh
+sudo systemctl --global disable pulseaudio.service pulseaudio.socket
+```
+
+
+## 7. It is also advisable to set `autospawn = no` in `/etc/pulse/client.conf`:
+
+```sh
+sudo nano /etc/pulse/client.conf
+```
+
+
+## 8. Create the `PulseAudio.service`:
+
+```sh
+sudo cp ./service/pulseaudio.service /etc/systemd/system/pulseaudio.service
+```
+
+
+## 9. Start the `PulseAudio.service`.  This will require you to type in your password a couple times.
+
+```sh
+systemctl --system enable pulseaudio.service
+```
+
+```sh
+systemctl --system start pulseaudio.service
+```
+
+
+## 10. Ensure pi user is in the `pulse-access` group:
+
+```sh
+sudo sed -i '/^pulse-access:/ s/$/root,pi/' /etc/group
+```
+
+
+## 11. Reboot your Pi: (see step 4)
+
+
+## 12. (OPTIONAL) If plugging speakers into the headphone jack, set the correct PulseAudio Sync Port:
+
+Run `pactl list sinks` and scroll to the bottom and notice your Active Port is probably "analog-output-speaker".  Run the command below to output audio through the 3.5mm headphone jack.
+
+```sh
+pactl set-sink-port 1 "analog-output-headphones"
+```
+
+**Please note that if you are setting this up on a Raspberry Pi 3B or 4B, you need an additional step at this point to make it route the audio through the 2mic hat (and likely the 4mic one as well). Run the following command to do this.**
+
+```sh
+pactl set-default-sink alsa_output.platform-soc_sound.stereo-fallback
+```
+
+
+## 13. Test and make sure you can hear the wav file:
+
+```sh
+paplay /usr/share/sounds/alsa/Front_Center.wav
+```
+
+**Note that if you have a Raspbery Pi 3B or 4B, this may or may not seem to work, but it will output on the hat as intended.**
+
+
+## 14. Modify PulseAudio to duck the music volume when you or the voice assistant are speaking:
+
+```sh
+sudo sed -i.bak \
+    -e '$a### Enable Volume Ducking' \
+    -e '$aload-module module-role-ducking trigger_roles=announce,phone,notification,event ducking_roles=any_role volume=25%' \
+    /etc/pulse/system.pa
+```
+
+
+## 15. Reboot your Pi: (see step 4)
+
+
+## 16. Done! Return to the tutorial to continue the Linux Voice Assistant install.
@@ -17,6 +17,7 @@ This guide reproduces a working setup of the **linux-voice-assistant** project w
 - A 2‑mic sound card
 - Network access to your Home Assistant instance

+
 ## 1. Install system packages

 ```bash
@@ -54,9 +55,16 @@ script/setup
 ```


-## 5. Configure audio devices
+## 5. Configure audio devices, choose either Pulse Audio or ALSA (default)
+
+### (Optional) Pulse Audio
+
+See [the tutorial](docs/install_pulseaudio.md) to install and configure Pulse Audio.
+
+### For Standard ALSA

 You shouldn't have to change anything if you are using the driver provided in this repo. If you are using something else, find your sound device names and update the linux-voice-assistant/service/linux-voice-assistant.service file to match sound card details:
+
 ```bash
 arecord -l
 aplay -l
@@ -65,12 +73,27 @@ aplay -l

 ## 6. Systemd services

-Copy the 2 service files into /etc/systemd/system/:
+### (Optional) for Pulse Audio copy this service file into /etc/systemd/system/:
+
+```bash
+sudo cp ./service/pa-linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
+```
+
+
+### For ALSA copy this service file into /etc/systemd/system/:
+
 ```bash
 sudo cp ./service/linux-voice-assistant.service /etc/systemd/system/linux-voice-assistant.service
+```
+
+### For either ALSA or Pusle Audio systems, copy the Wyoming OpenWakeWord service file into /etc/systemd/system/:
+
+```bash
 sudo cp ./service/wyoming-openwakeword.service /etc/systemd/system/wyoming-openwakeword.service
 ```
+
 Start new services and confirm services are running:
+
 ```bash
 sudo systemctl daemon-reload
 sudo systemctl enable --now linux-voice-assistant
@@ -94,7 +117,8 @@ sudo systemctl status linux-voice-assistant wyoming-openwakeword --no-pager -l
 - Look for `[OWW] Detection: name=...` followed by re-arming/cycling
 - Ask: *“What time is it?”* and confirm TTS reply
 - If you do not get a voice response, check the Voice Assistant that you choose during registration has a voice assigned to it.
-      Setting -> 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 (Depricated-Wake word can be selected in HA now)
@@ -113,40 +137,14 @@ ok_nabu_v0.1.tflite
 Additional community provided OWW models available from this repository:
 https://github.com/fwartner/home-assistant-wakewords-collection

-**Word of warning. I have had problems with some of the communitee provided wake words. YMMV**
+**Word of warning. I have had problems with some of the community provided wake words. YMMV**

 Edit linux-voice-assistant.service file:
 ```bash
 sudo systemctl edit --force --full linux-voice-assistant.service 
 ```

-Service file as provided using OWW 'alexa':
-```text
-[Unit]
-Description=Linux Voice Assistant
-Requires=wyoming-openwakeword.service
-After=sound.target network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-WorkingDirectory=/home/pi/linux-voice-assistant
-ExecStart=/home/pi/linux-voice-assistant/script/run \
-  --name 'Linux Satellite' \
-  --audio-input-device seeed-2mic-voicecard \
-  --audio-output-device alsa/hw:1,0 \
-  --wake-uri 'tcp://127.0.0.1:10400' \
-  --wake-word-name 'alexa'
-Restart=always
-RestartSec=2
-Environment=PYTHONUNBUFFERED=1
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Service file using OWW 'ok_nabu':
-
+Service file as provided using OWW 'ok_nabu':
 ```text
 [Unit]
 Description=Linux Voice Assistant
@@ -171,6 +169,32 @@ Environment=PYTHONUNBUFFERED=1
 WantedBy=multi-user.target
 ```

+Service file using OWW 'alexa':
+
+```text
+[Unit]
+Description=Linux Voice Assistant
+Requires=wyoming-openwakeword.service
+After=sound.target network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/home/pi/linux-voice-assistant
+ExecStart=/home/pi/linux-voice-assistant/script/run \
+  --name 'Linux Satellite' \
+  --audio-input-device seeed-2mic-voicecard \
+  --audio-output-device alsa/hw:1,0 \
+  --wake-uri 'tcp://127.0.0.1:10400' \
+  --wake-word-name 'alexa'
+Restart=always
+RestartSec=2
+Environment=PYTHONUNBUFFERED=1
+
+[Install]
+WantedBy=multi-user.target
+```
+
 Reload systemd with updated linux-voice-assistant.service file, restart linux-voice-assistant.service, and confirm successful run:
 ```bash
 sudo systemctl daemon-reload
@@ -191,6 +215,7 @@ Service file with OWW:
 [Unit]
 Description=Linux Voice Assistant
 Requires=wyoming-openwakeword.service
+After=wyoming-openwakeword.service
 After=sound.target network-online.target
 Wants=network-online.target

@@ -202,7 +227,7 @@ ExecStart=/home/pi/linux-voice-assistant/script/run \
  --audio-input-device seeed-2mic-voicecard \
  --audio-output-device alsa/hw:1,0 \
  --wake-uri 'tcp://127.0.0.1:10400' \
-  --wake-word-name 'alexa'
+  --wake-word-name 'ok_nabu'
 Restart=always
 RestartSec=2
 Environment=PYTHONUNBUFFERED=1
@@ -216,6 +241,7 @@ Service file without OWW:
 [Unit]
 Description=Linux Voice Assistant
 Requires=wyoming-openwakeword.service
+After=wyoming-openwakeword.service
 After=sound.target network-online.target
 Wants=network-online.target

@@ -0,0 +1,24 @@
+[Unit]
+Description=Linux Voice Assistant
+Requires=wyoming-openwakeword.service
+After=wyoming-openwakeword.service
+After=sound.target network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/home/pi/linux-voice-assistant
+ExecStart=/home/pi/linux-voice-assistant/script/run \
+  --name 'Linux Satellite' \
+  --audio-input-device pulse \
+  --audio-output-device pulse \
+  --wake-uri 'tcp://127.0.0.1:10400' \
+  --wake-word-name 'marvin' \
+  --wake-models-dir '/home/pi/wyoming-openwakeword/wyoming_openwakeword/models' \
+  --debug
+Restart=always
+RestartSec=2
+Environment=PYTHONUNBUFFERED=1
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,9 @@
+[Unit]
+Description=PulseAudio system server
+
+[Service]
+Type=notify
+ExecStart=pulseaudio --daemonize=no --system --realtime --log-target=journal
+
+[Install]
+WantedBy=multi-user.target