improved documentation
This commit is contained in:
Florian Asche committed
1 parent
ebd18dd234
commit
7655d9e398
6 files changed
+737
-105
No files matched your search
@@ -1,122 +1,42 @@
|
||||
# Linux Voice Assistant
|
||||
# Linux-Voice-Assistant
|
||||
|
||||
Experimental Linux voice assistant for [Home Assistant][homeassistant] that uses the [ESPHome][esphome] protocol.
|
||||
[](https://github.com/OHF-Voice/linux-voice-assistant/actions/workflows/docker-build-release.yml) [](https://github.com/OHF-Voice/linux-voice-assistant/pkgs/container/linux-voice-assistant) [](https://github.com/OHF-Voice/linux-voice-assistant/blob/main/LICENSE.md) [](https://github.com/OHF-Voice/linux-voice-assistant/commits) [](https://github.com/OHF-Voice/linux-voice-assistant/pkgs/container/linux-voice-assistant)
|
||||
|
||||
Runs on Linux `aarch64` and `x86_64` platforms. Tested with Python 3.13 and Python 3.11.
|
||||
Supports announcments, start/continue conversation, and timers.
|
||||
Experimental Linux-Voice-Assistant for [Home Assistant][https://www.home-assistant.io/] that uses the [ESPHome][https://esphome.io/] protocol.
|
||||
|
||||
## Installation
|
||||
|
||||
Install system dependencies (`apt-get`):
|
||||
## Features:
|
||||
|
||||
* `libportaudio2` or `portaudio19-dev` (for `sounddevice`)
|
||||
* `build-essential` (for `pymicro-features`)
|
||||
* `libmpv-dev` (for `python-mpv`)
|
||||
- Works with [Home Assistant](https://www.home-assistant.io/integrations/esphome/)
|
||||
- Local wake word detection using integrated [OpenWakeWord](https://github.com/dscripka/openWakeWord) or [MicroWakeWord](https://github.com/kahrendt/microWakeWord)
|
||||
- Supports multiple architectures (linux/amd64 and linux/aarch64)
|
||||
- Automated builds with artifact attestation for security
|
||||
- Supports multiple wake words and languages
|
||||
- Supports announcments, start/continue conversation, and timers
|
||||
- Tested with Python 3.13 and Python 3.11.
|
||||
- Prebuild docker image available on [GitHub Container Registry](https://github.com/OHF-Voice/linux-voice-assistant/pkgs/container/linux-voice-assistant)
|
||||
- Prebuild Raspberry Pi image
|
||||
|
||||
Clone and install project:
|
||||
|
||||
``` sh
|
||||
git clone https://github.com/OHF-Voice/linux-voice-assistant.git
|
||||
cd linux-voice-assistant
|
||||
script/setup
|
||||
```
|
||||
## Usage:
|
||||
|
||||
## Running
|
||||
### Hardware:
|
||||
|
||||
Use `script/run` or `python3 -m linux_voice_assistant`
|
||||
You can for example use the Raspberry Pi Zero 2W with the [Satellite1 Hat Board](https://futureproofhomes.net/products/satellite1-top-microphone-board) or the [Respeaker 2Mic_Hat](https://wiki.seeedstudio.com/ReSpeaker_2_Mics_Pi_HAT/). A list for possible compatible hardware can be found in the [PiCompose documentation](https://github.com/florian-asche/PiCompose) but basically any microphone that works with [Pipewire](https://pipewire.org/) can be used.
|
||||
|
||||
You must specify `--name <NAME>` with a name that will be available in Home Assistant.
|
||||
### Software:
|
||||
|
||||
See `--help` for more options.
|
||||
See [Linux-Voice-Assistant - Installation](docs/install.md)
|
||||
|
||||
### Microphone
|
||||
|
||||
Use `--audio-input-device` to change the microphone device. Use `--list-input-devices` to see the available microphones.
|
||||
## Build Information:
|
||||
|
||||
The microphone device **must** support 16Khz mono audio.
|
||||
Image builds can be tracked in this repository's `Actions` tab, and utilize [artifact attestation](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds) to certify provenance.
|
||||
|
||||
### Speaker
|
||||
The Docker images are built using GitHub Actions, which provides:
|
||||
|
||||
Use `--audio-output-device` to change the speaker device. Use `--list-output-devices` to see the available speakers.
|
||||
- Automated builds for different architectures
|
||||
- Artifact attestation for build provenance verification
|
||||
- Regular updates and maintenance
|
||||
|
||||
### Sounds
|
||||
|
||||
Customize wake word and timer sounds (defaults are used if not specified):
|
||||
``` sh
|
||||
python3 -m linux_voice_assistant ... \
|
||||
--wakeup-sound sounds/wake_word_triggered_old.wav \
|
||||
--timer-finished-sound sounds/timer_finished.flac
|
||||
```
|
||||
|
||||
Available sounds:
|
||||
* **Wake sounds**: `wake_word_triggered.flac` (default), `wake_word_triggered_old.wav`
|
||||
* **Timer sounds**: `timer_finished.flac` (default), `timer_finished_old.wav`
|
||||
|
||||
The optional "thinking" sound plays while the assistant is processing. Enable it on startup with:
|
||||
``` sh
|
||||
python3 -m linux_voice_assistant ... \
|
||||
--enable-thinking-sound
|
||||
```
|
||||
|
||||
This enables the thinking sound by default and sets the Home Assistant switch to ON. The switch can be toggled at any time from the device page.
|
||||
|
||||
## Wake Word
|
||||
|
||||
Change the default wake word with `--wake-model <id>` where `<id>` is the name of a model in the `wakewords` directory. For example, `--wake-model hey_jarvis` will load `wakewords/hey_jarvis.tflite` by default.
|
||||
|
||||
You can include more wakeword directories by adding `--wake-word-dir <DIR>` where `<DIR>` contains either [microWakeWord][] or [openWakeWord][] config files and `.tflite` models. For example, `--wake-word-dir wakewords/openWakeWord` will include the default wake words for openWakeWord.
|
||||
|
||||
If you want to add [other wakewords][wakewords-collection], make sure to create a small JSON config file to identify it as an openWakeWord model. For example, download the [GLaDOS][glados] model to `glados.tflite` and create `glados.json` with:
|
||||
|
||||
``` json
|
||||
{
|
||||
"type": "openWakeWord",
|
||||
"wake_word": "GLaDOS",
|
||||
"model": "glados.tflite"
|
||||
}
|
||||
```
|
||||
|
||||
Add `--wake-word-dir <DIR>` with the directory containing `glados.tflite` and `glados.json` to your command-line.
|
||||
|
||||
## Connecting to Home Assistant
|
||||
|
||||
1. In Home Assistant, go to "Settings" -> "Device & services"
|
||||
2. Click the "Add integration" button
|
||||
3. Choose "ESPHome" and then "Set up another instance of ESPHome"
|
||||
4. Enter the IP address of your voice satellite with port 6053
|
||||
5. Click "Submit"
|
||||
|
||||
## Acoustic Echo Cancellation
|
||||
|
||||
Enable the echo cancel PulseAudio module:
|
||||
|
||||
``` sh
|
||||
pactl load-module module-echo-cancel \
|
||||
aec_method=webrtc \
|
||||
aec_args="analog_gain_control=0 digital_gain_control=1 noise_suppression=1"
|
||||
```
|
||||
|
||||
Verify that the `echo-cancel-source` and `echo-cancel-sink` devices are present:
|
||||
|
||||
``` sh
|
||||
pactl list short sources
|
||||
pactl list short sinks
|
||||
```
|
||||
|
||||
Use the new devices:
|
||||
|
||||
``` sh
|
||||
# The device names may be different on your system.
|
||||
# Double check with --list-input-devices and --list-output-devices
|
||||
python3 -m linux_voice_assistant ... \
|
||||
--audio-input-device 'Echo-Cancel Source' \
|
||||
--audio-output-device 'pipewire/echo-cancel-sink'
|
||||
```
|
||||
|
||||
<!-- Links -->
|
||||
[homeassistant]: https://www.home-assistant.io/
|
||||
[esphome]: https://esphome.io/
|
||||
[microWakeWord]: https://github.com/kahrendt/microWakeWord
|
||||
[openWakeWord]: https://github.com/dscripka/openWakeWord
|
||||
[wakewords-collection]: https://github.com/fwartner/home-assistant-wakewords-collection
|
||||
[glados]: https://github.com/fwartner/home-assistant-wakewords-collection/blob/main/en/glados/glados.tflite
|
||||
The documentation for the build process can be found in the [GitHub Actions Workflows](.github/workflow.md) file.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Additional Audio Settings
|
||||
|
||||
This document is still in an early stage and will be updated soon.
|
||||
|
||||
## Pipewire:
|
||||
|
||||
tbd
|
||||
|
||||
## Pulseaudio:
|
||||
|
||||
### Acoustic Echo Cancellation:
|
||||
|
||||
Enable the echo cancel PulseAudio module:
|
||||
|
||||
``` sh
|
||||
pactl load-module module-echo-cancel \
|
||||
aec_method=webrtc \
|
||||
aec_args="analog_gain_control=0 digital_gain_control=1 noise_suppression=1"
|
||||
```
|
||||
|
||||
Verify that the `echo-cancel-source` and `echo-cancel-sink` devices are present:
|
||||
|
||||
``` sh
|
||||
pactl list short sources
|
||||
pactl list short sinks
|
||||
```
|
||||
|
||||
Use the new devices:
|
||||
|
||||
``` sh
|
||||
# The device names may be different on your system.
|
||||
# Double check with --list-input-devices and --list-output-devices
|
||||
python3 -m linux_voice_assistant ... \
|
||||
--audio-input-device 'Echo-Cancel Source' \
|
||||
--audio-output-device 'pipewire/echo-cancel-sink'
|
||||
```
|
||||
@@ -0,0 +1,165 @@
|
||||
|
||||
# Debugging
|
||||
|
||||
## Explanation of the audio system:
|
||||
|
||||
The Linux audio stack consists of multiple layers working together:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ HOST SYSTEM │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ User Applications │ │
|
||||
│ │ (Browser, Media Player, Voice Assistant, etc.) │ │
|
||||
│ └────────────────┬────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────▼────────────────────────────────────┐ │
|
||||
│ │ PipeWire / PulseAudio │ │
|
||||
│ │ (Sound Server) │ │
|
||||
│ │ - Audio mixing & routing │ │
|
||||
│ │ - Device abstraction │ │
|
||||
│ │ - Network audio support │ │
|
||||
│ │ - Per-application volume control │ │
|
||||
│ └────────────────┬────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────▼────────────────────────────────────┐ │
|
||||
│ │ ALSA │ │
|
||||
│ │ (Advanced Linux Sound Architecture) │ │
|
||||
│ │ - Kernel-level audio driver framework │ │
|
||||
│ │ - Direct hardware access │ │
|
||||
│ │ - Controls: /dev/snd/ │ │
|
||||
│ └────────────────┬────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────▼────────────────────────────────────┐ │
|
||||
│ │ Hardware (Sound Card) │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌───────────────────┐ │ │
|
||||
│ │ │Microphon│ │ Speaker │ │ DSP/Codec │ │ │
|
||||
│ │ └─────────┘ └─────────┘ └───────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ XDG_RUNTIME_DIR=/run/user/1000 │
|
||||
│ └── Socket: /run/user/1000/pipewire-0 │
|
||||
│ Socket: /run/user/1000/pulse/native │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Device Passthrough
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ DOCKER CONTAINER │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ Container Process │ │
|
||||
│ │ (Linux Voice Assistant) │ │
|
||||
│ │ │ │
|
||||
│ │ Accesses audio via: │ │
|
||||
│ │ - PipeWire/PulseAudio client library │ │
|
||||
│ │ - Uses same XDG_RUNTIME_DIR socket path │ │
|
||||
│ │ │ │
|
||||
│ │ Environment Variables: │ │
|
||||
│ │ - XDG_RUNTIME_DIR=/run/user/1000 (host path) │ │
|
||||
│ │ - AUDIO_INPUT_DEVICE="default" │ │
|
||||
│ │ - AUDIO_OUTPUT_DEVICE="default" │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Device Access: │
|
||||
│ - Socket: /run/user/1000/pipewire-0 (volume mount) │
|
||||
│ - Socket: /run/user/1000/pulse/native (volume mount) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### How it works:
|
||||
|
||||
1. **Host Layer**:
|
||||
- ALSA provides kernel drivers for audio hardware
|
||||
- PipeWire/PulseAudio sits on top of ALSA as a sound server
|
||||
- Applications connect to PipeWire/PulseAudio, not directly to ALSA, otherwhise the container would need access to the ALSA devices. If you use ALSA only only one application can connect to the device at a time.
|
||||
|
||||
2. **Docker Integration**:
|
||||
- The XDG_RUNTIME_DIR socket must be mounted from host to container
|
||||
- The container user must have matching UID/GID with host user or the audio group is added.
|
||||
|
||||
3. **Communication Flow**:
|
||||
```
|
||||
Container App → PipeWire Client Library → Host PipeWire/PulseAudio
|
||||
↓ ↓
|
||||
(via mounted socket) (via ALSA drivers)
|
||||
↓ ↓
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Audio Data flows to Hardware │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
4. **Key Configuration Points**:
|
||||
- `XDG_RUNTIME_DIR` must point to host's runtime directory
|
||||
- Container user UID/GID should match host user
|
||||
|
||||
### Docker Compose Example:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
voice-assistant:
|
||||
image: ghcr.io/ohf-voice/linux-voice-assistant:latest
|
||||
environment:
|
||||
- XDG_RUNTIME_DIR=/run/user/1000
|
||||
- AUDIO_INPUT_DEVICE=default
|
||||
- AUDIO_OUTPUT_DEVICE=default
|
||||
volumes:
|
||||
- /run/user/1000:/run/user/1000:rw
|
||||
devices:
|
||||
- /dev/snd:/dev/snd
|
||||
group_add:
|
||||
- audio
|
||||
```
|
||||
|
||||
|
||||
## List available audio devices:
|
||||
|
||||
To list available audio devices, run:
|
||||
|
||||
```bash
|
||||
# List audio devices
|
||||
docker run --rm -it -e LIST_DEVICES="1" ghcr.io/florian-asche/linux-voice-assistant:develop-final-docker-version
|
||||
```
|
||||
|
||||
Update the `.env` file with your device names:
|
||||
|
||||
``` ini
|
||||
AUDIO_INPUT_DEVICE="default"
|
||||
AUDIO_OUTPUT_DEVICE="default"
|
||||
```
|
||||
|
||||
|
||||
## Pipewire runtime directory (Optional):
|
||||
|
||||
If you work with the root user, you need to:
|
||||
``` sh
|
||||
export XDG_RUNTIME_DIR=/run/user/${USER_ID}
|
||||
```
|
||||
|
||||
💡 **Note:** Replace `$USER_ID` with your actual user id that you want to run the voice assistant.
|
||||
|
||||
|
||||
## Troubleshooting:
|
||||
|
||||
### Audio Device Not Found:
|
||||
|
||||
If the container cannot access audio devices, ensure:
|
||||
|
||||
1. The USER_ID in `.env` matches your actual users ID (run `id -u $USER` to check)
|
||||
2. The XDG_RUNTIME_DIR path exists on the host
|
||||
|
||||
### Permission Denied Errors:
|
||||
|
||||
tbd
|
||||
|
||||
### Low Audio Quality:
|
||||
|
||||
If you experience audio quality issues:
|
||||
|
||||
1. Check the audio device settings with `alsamixer`
|
||||
2. Try setting `AUDIO_INPUT_DEVICE` and `AUDIO_OUTPUT_DEVICE` explicitly
|
||||
3. Adjust the microphone gain in your system settings
|
||||
|
||||
|
||||
## More debugging documentation:
|
||||
|
||||
See [PiCompose](https://github.com/florian-asche/PiCompose/blob/main/docs/pipewire_debugging.md) for more debugging information.
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
# Linux-Voice-Assistant - Installation
|
||||
|
||||
This guide describes how to install PipeWire, Docker, and then set up the Linux-Voice-Assistant using docker-compose manually. The Linux-Voice-Assistant is a voice assistant that runs locally and supports wake word detection, voice activity detection, and audio playback.
|
||||
|
||||
## Prerequisites:
|
||||
|
||||
- A Linux system (tested on Debian/Raspberry Pi OS/Ubuntu)
|
||||
- Docker and Docker Compose installed (Optional but preffered)
|
||||
- A microphone and speaker for audio input/output
|
||||
|
||||
## Overview:
|
||||
|
||||
The installation process can be divided into the following steps:
|
||||
|
||||
```
|
||||
+-----------------------------------------------------------------------+
|
||||
| LINUX-VOICE-ASSISTANT INSTALLATION |
|
||||
+-----------------------------------------------------------------------+
|
||||
|
|
||||
v
|
||||
+-------------------------------+
|
||||
| 0) Use Prebuilt Pi Image? |
|
||||
| +---------+---------+ |
|
||||
| | YES | NO | |
|
||||
| +---------+---------+ |
|
||||
+-------------------------------+
|
||||
/ \
|
||||
/ \
|
||||
v v
|
||||
+-------+ +-----------------------+
|
||||
| READY | | 1) INSTALL AUDIO SYS |
|
||||
| | +-----------------------+
|
||||
+-------+ |
|
||||
v
|
||||
+-------------------------------------------+
|
||||
| Audio Service Options |
|
||||
| +-------------+ +-------------+ |
|
||||
| | Existing | | Install | |
|
||||
| | Pipe/Pulse | | Audio Sys | |
|
||||
| +-------------+ +-------------+ |
|
||||
| | | |
|
||||
| v v |
|
||||
| +-------+ +-----+----------+ |
|
||||
| |READY | | a) PipeWire | |
|
||||
| +-------+ | b) PulseAudio | |
|
||||
| +-----+----------+ |
|
||||
| | |
|
||||
+--------------------------+----------------+
|
||||
/ \
|
||||
v v
|
||||
+---------------------+ +---------------------+
|
||||
| Audio Ready | | 2) INSTALL APP |
|
||||
+---------------------+ +---------------------+
|
||||
|
|
||||
v
|
||||
+---------------------------+
|
||||
| Application Options |
|
||||
| +-----------------------+ |
|
||||
| | a) Docker Compose | |
|
||||
| | b) Bare Metal | |
|
||||
| +-----------------------+ |
|
||||
| | |
|
||||
+-----------+-------#-------+
|
||||
|
|
||||
v
|
||||
+---------------------------+
|
||||
| Application Ready |
|
||||
+---------------------------+
|
||||
|
||||
```
|
||||
|
||||
## Installation Steps:
|
||||
|
||||
### Option A) Use Prebuilt Pi Image:
|
||||
|
||||
The easyiest way to get started is to use the prebuilt image. This image comes with all necessary configurations and drivers preinstalled.
|
||||
|
||||
- Download ready-to-use image from [PiCompose](https://github.com/florian-asche/PiCompose)
|
||||
- Change configuration in /compose/ directory if you need to.
|
||||
- You may need to reboot the board like 3 times for everything to be installed. Especially for the 2MicHat drivers. And give docker-compose some time to download the images. You can watch the logs in /var/logs/picompose.log
|
||||
- More information within the PiCompose project.
|
||||
|
||||
### Option B) Install on your own:
|
||||
|
||||
If you want to setup the software on your own hardware, for example if you want to use LVA on your linux desktop, you can use the docker image.
|
||||
|
||||
#### Step 1: Install Audioservice:
|
||||
|
||||
It is on your own to choose the audio service you want to use.
|
||||
|
||||
- **a) Existing PipeWire/PulseAudio** Use if already installed
|
||||
- **b) Install PipeWire** (recommended): Install PipeWire and configure. See [Install Audioservice - Pipewire](install_audioservice.md)
|
||||
- **c) Install PulseAudio** Install PulseAudio as alternative. See [Install Audioservice - PulseAudio](install_audioservice.md)
|
||||
|
||||
#### Step 2: Install Application:
|
||||
|
||||
You can run the application in two ways:
|
||||
|
||||
- **a) Docker Compose** (recommended): Install Docker, download compose files, configure and start. See [Install Application - Docker Compose](install_application.md)
|
||||
- **b) Bare Metal** Install dependencies, clone repo, setup and create systemd service. See [Install Application - Bare Metal](install_application.md)
|
||||
@@ -0,0 +1,276 @@
|
||||
# Install Application
|
||||
|
||||
You can install the application in different ways. We recommend to use Docker Compose if not the prebuilt image. But if you dont want to use Docker you can also install it directly on your system.
|
||||
|
||||
## A) Docker Compose (recommended):
|
||||
|
||||
Install packages:
|
||||
``` sh
|
||||
sudo apt-get install -y ca-certificates curl wget gnupg lsb-release git jq vim
|
||||
```
|
||||
|
||||
Download and add Docker's official GPG key:
|
||||
``` sh
|
||||
mkdir -p /etc/apt/keyrings
|
||||
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
|
||||
sudo chmod a+r /etc/apt/keyrings/docker.gpg
|
||||
```
|
||||
|
||||
Set up the Docker repository:
|
||||
``` sh
|
||||
echo \
|
||||
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
|
||||
https://download.docker.com/linux/debian \
|
||||
$(lsb_release -cs) stable" | \
|
||||
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
```
|
||||
|
||||
Install Docker and Docker Compose:
|
||||
``` sh
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
|
||||
```
|
||||
|
||||
Download the docker-compose.yml and .env.example file from the repository to a folder on your system:
|
||||
``` sh
|
||||
mkdir linux-voice-assistant
|
||||
cd linux-voice-assistant
|
||||
wget https://raw.githubusercontent.com/OHF-Voice/linux-voice-assistant/refs/tags/v1.0.0/docker-compose.yml
|
||||
wget https://raw.githubusercontent.com/OHF-Voice/linux-voice-assistant/refs/tags/v1.0.0/.env.example
|
||||
mv .env.example .env
|
||||
```
|
||||
|
||||
💡 **Note:** Use the latest stable version of the files from the repository. We update this documentation only regulary.
|
||||
|
||||
| Tag | Description | Example |
|
||||
|-----|-------------|---------|
|
||||
| `latest` | Latest stable release | `ghcr.io/ohf-voice/linux-voice-assistant:latest` |
|
||||
| `nightly` | Latest development build | `ghcr.io/ohf-voice/linux-voice-assistant:nightly` |
|
||||
| `x.y.z` | Specific version release | `ghcr.io/ohf-voice/linux-voice-assistant:1.0.0` |
|
||||
| `x.y` | Major.Minor with auto updates | `ghcr.io/ohf-voice/linux-voice-assistant:1.0` |
|
||||
| `<branch>` | Branch-specific build | `ghcr.io/ohf-voice/linux-voice-assistant:my-branch` |
|
||||
|
||||
Edit the .env file and change the values to your needs:
|
||||
``` sh
|
||||
vim .env
|
||||
```
|
||||
|
||||
💡 **Note:** You can exit vim with :wq or :q! if you dont want to save the changes.
|
||||
|
||||
Start the application:
|
||||
``` sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
💡 **Note:** If you want to use the application with a different user, you need to change the user in the .env file. Dont forget to change the UID from the user. The docker container will run until you stop it. It will restart autiomatically after a reboot.
|
||||
|
||||
Check if the application is running:
|
||||
``` sh
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
Check the logs:
|
||||
``` sh
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
Stop the service:
|
||||
``` sh
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
Download the latest image:
|
||||
``` sh
|
||||
docker-compose pull
|
||||
```
|
||||
|
||||
|
||||
## B) Bare Metal:
|
||||
|
||||
Install the required packages for the application:
|
||||
|
||||
``` sh
|
||||
sudo apt update
|
||||
sudo apt-get install \
|
||||
avahi-utils \
|
||||
pulseaudio-utils \
|
||||
alsa-utils \
|
||||
pipewire-bin \
|
||||
pipewire-alsa \
|
||||
pipewire-pulse \
|
||||
build-essential \
|
||||
libmpv-dev \
|
||||
libasound2-plugins \
|
||||
ca-certificates \
|
||||
iproute2 \
|
||||
procps \
|
||||
git \
|
||||
jq \
|
||||
curl \
|
||||
wget \
|
||||
vim \
|
||||
python3-venv \
|
||||
python3-dev
|
||||
```
|
||||
|
||||
Clone the repository:
|
||||
|
||||
``` sh
|
||||
git clone https://github.com/OHF-Voice/linux-voice-assistant.git
|
||||
cd linux-voice-assistant
|
||||
chmod +x docker-entrypoint.sh
|
||||
```
|
||||
|
||||
Install the application:
|
||||
|
||||
``` sh
|
||||
script/setup
|
||||
```
|
||||
|
||||
Create a systemd service for the application:
|
||||
|
||||
``` sh
|
||||
sudo systemctl edit --force --full linux-voice-assistant.service
|
||||
```
|
||||
|
||||
Paste the following content into the file:
|
||||
|
||||
``` ini
|
||||
[Unit]
|
||||
Description=Wyoming Voice Assistant (wyomingpi2)
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=pi
|
||||
WorkingDirectory=/home/pi/linux-voice-assistant
|
||||
|
||||
Environment=PATH=/home/pi/linux-voice-assistant/.venv/bin:/usr/bin:/bin
|
||||
# Environment=ENABLE_DEBUG="1"
|
||||
# Environment=LIST_DEVICES="1"
|
||||
Environment=USER_ID="1000"
|
||||
Environment=CLIENT_NAME="My Voice Assistant Speaker"
|
||||
Environment=PULSE_SERVER="unix:/run/user/${USER_ID}/pulse/native"
|
||||
Environment=XDG_RUNTIME_DIR="/run/user/${USER_ID}"
|
||||
Environment=PREFERENCES_FILE="/home/pi/linux-voice-assistant/preferences.json"
|
||||
Environment=PORT="6053"
|
||||
# Environment=AUDIO_INPUT_DEVICE="default"
|
||||
# Environment=AUDIO_OUTPUT_DEVICE="default"
|
||||
# Environment=ENABLE_THINKING_SOUND="1"
|
||||
# Environment=WAKE-MODEL="okay_nabu"
|
||||
# Environment=REFACTORY_SECONDS="2"
|
||||
# Environment=WAKEUP_SOUND="sounds/wake_word_triggered.flac"
|
||||
# Environment=TIMER_FINISHED_SOUND="sounds/timer_finished.flac"
|
||||
# Environment=PROCESSING_SOUND="sounds/processing.wav"
|
||||
# Environment=MUTE_SOUND="sounds/mute_switch_on.flac"
|
||||
# Environment=UNMUTE_SOUND="sounds/mute_switch_off.flac"
|
||||
# ExecStart=/home/pi/linux-voice-assistant/docker-entrypoint.sh --additional-parameter-if-you-want
|
||||
ExecStart=/home/pi/linux-voice-assistant/docker-entrypoint.sh
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
💡 **Note:** We are using the `docker-entrypoint.sh` script to start the application. This script is located in the root of the repository. But there is no docker used. Only the start script is used.
|
||||
|
||||
💡 **Note:** Replace `$USER_ID` with your actual user id that you want to run the voice assistant.
|
||||
|
||||
Reload the systemd daemon and start the service:
|
||||
|
||||
``` sh
|
||||
sudo systemctl daemon-reexec
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable linux-voice-assistant
|
||||
sudo systemctl start linux-voice-assistant
|
||||
```
|
||||
|
||||
💡 **Note:** If you want to change settings you can do this with editing the Environment in the service file.
|
||||
|
||||
If you want to check if the service is running you can use the following command:
|
||||
|
||||
``` sh
|
||||
sudo systemctl status linux-voice-assistant
|
||||
```
|
||||
|
||||
|
||||
## Connecting to Home Assistant:
|
||||
|
||||
1. In Home Assistant, go to "Settings" -> "Device & services"
|
||||
2. Click the "Add integration" button
|
||||
3. Choose "ESPHome" and then "Set up another instance of ESPHome"
|
||||
4. Enter the IP address of your voice satellite with port 6053
|
||||
5. Click "Submit"
|
||||
|
||||
|
||||
## Additional Information:
|
||||
|
||||
### Settings:
|
||||
All optional settings except the audio sounds are disabled by default. You can change them in the UI and they will be saved in the PREFERENCES_FILE. If you set the configuration in the service file, the corresponding settings will be overwritten and you are no longer able to change them in the UI.
|
||||
|
||||
If you want to change the audio sounds you need to change the paths in the service file.
|
||||
|
||||
#### Environment Variables Reference:
|
||||
|
||||
The following variables can be configured in the `.env` or in the service file:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `USER_ID` | `1000` | User ID for the container (usually 1000 for the first user) |
|
||||
| `CLIENT_NAME` | (optional) | Custom name for this voice assistant instance |
|
||||
| `PULSE_SERVER` | `unix:/run/user/${USER_ID}/pulse/native` | Path to the PulseAudio/PipeWire socket |
|
||||
| `XDG_RUNTIME_DIR` | `/run/user/${USER_ID}` | XDG runtime directory |
|
||||
| `ENABLE_DEBUG` | (optional) | Set to "1" to enable debug mode |
|
||||
| `LIST_DEVICES` | (optional) | Set to "1" to list audio devices instead of starting |
|
||||
| `PREFERENCES_FILE` | (optional) | Path to a custom preferences JSON file |
|
||||
| `PORT` | `6053` | API server port |
|
||||
| `AUDIO_INPUT_DEVICE` | `default` | Audio input device name |
|
||||
| `AUDIO_OUTPUT_DEVICE` | `default` | Audio output device name |
|
||||
| `ENABLE_THINKING_SOUND` | (optional) | Set to "1" to enable thinking sound |
|
||||
| `WAKE_MODEL` | `okay_nabu` | Wake word model to use |
|
||||
| `REFACTORY_SECONDS` | `2` | Refractory period in seconds after wake word |
|
||||
| `WAKEUP_SOUND` | `sounds/wake_word_triggered.flac` | Sound file for wake word triggered |
|
||||
| `TIMER_FINISHED_SOUND` | `sounds/timer_finished.flac` | Sound file for timer finished |
|
||||
| `PROCESSING_SOUND` | `sounds/processing.wav` | Sound file for processing state |
|
||||
| `MUTE_SOUND` | `sounds/mute_switch_on.flac` | Sound file for mute on |
|
||||
| `UNMUTE_SOUND` | `sounds/mute_switch_off.flac` | Sound file for Configure Audio Devices
|
||||
|
||||
#### Available Wake Word Models:
|
||||
|
||||
The following wake word models are available:
|
||||
- `okay_nabu` - Default wake word
|
||||
- `alexa` - Alexa wake word
|
||||
- `hey_jarvis` - Jarvis wake word
|
||||
- `hey_mycroft` - Mycroft wake word
|
||||
- `hey_luna` - Luna wake word
|
||||
- `hey_home_assistant` - Home Assistant wake word
|
||||
- `stop` - Stop wake word
|
||||
- `okay_computer` - Okay Computer wake word
|
||||
- `choo_choo_homie` - Choo Choo Homie wake word
|
||||
|
||||
|
||||
### Wake Word:
|
||||
|
||||
💡 **Note:** The default value for this parameter is the `wakewords` directory in the repository.
|
||||
|
||||
Change the default wake word with `--wake-model <id>` where `<id>` is the name of a model in the `wakewords` directory. For example, `--wake-model hey_jarvis` will load `wakewords/hey_jarvis.tflite` by default.
|
||||
|
||||
You can include more wakeword directories by adding `--wake-word-dir <DIR>` where `<DIR>` contains either [microWakeWord][] or [openWakeWord][] config files and `.tflite` models. For example, `--wake-word-dir wakewords/openWakeWord` will include the default wake words for openWakeWord.
|
||||
|
||||
If you want to add [other wakewords][wakewords-collection], make sure to create a small JSON config file to identify it as an openWakeWord model. For example, download the [GLaDOS][glados] model to `glados.tflite` and create `glados.json` with:
|
||||
|
||||
``` json
|
||||
{
|
||||
"type": "openWakeWord",
|
||||
"wake_word": "GLaDOS",
|
||||
"model": "glados.tflite"
|
||||
}
|
||||
```
|
||||
|
||||
Add `--wake-word-dir <DIR>` with the directory containing `glados.tflite` and `glados.json` to your command-line.
|
||||
|
||||
#### Additional Wakewords:
|
||||
|
||||
More wakewords can be found in the [wakewords-collection](https://github.com/fwartner/home-assistant-wakewords-collection) repository.
|
||||
@@ -0,0 +1,135 @@
|
||||
# Install Audioservice
|
||||
|
||||
For Linux-Voice-Assistant a Pulseaudio connection to the soundcard is required. Since PulseAudio is not installed by default on Ubuntu 22.04 we also support Pipewire. You can choose either one (A or B) of them.
|
||||
|
||||
## A) Pipewire (recommended):
|
||||
|
||||
PipeWire is a multimedia server that provides low-latency audio/video handling. Install it with the following commands:
|
||||
|
||||
``` sh
|
||||
# Update package database
|
||||
sudo apt update
|
||||
|
||||
# Install PipeWire and related packages
|
||||
sudo apt install -y pipewire wireplumber pipewire-audio-client-libraries libspa-0.2-bluetooth pipewire-audio pipewire-pulse dfu-util
|
||||
```
|
||||
|
||||
Link the PipeWire configuration for ALSA applicationssudo ln -sf:
|
||||
|
||||
``` sh
|
||||
ln -s /usr/share/alsa/alsa.conf.d/50-pipewire.conf /etc/alsa/conf.d/
|
||||
```
|
||||
|
||||
Allow services to run without an active user session (optional, for headless setups):
|
||||
|
||||
``` sh
|
||||
sudo mkdir -p /var/lib/systemd/linger
|
||||
sudo touch /var/lib/systemd/linger/$USER
|
||||
```
|
||||
|
||||
💡 **Note:** Replace `$USER` with your actual username that you want to run the voice assistant.
|
||||
|
||||
### Configure PipeWire (optional):
|
||||
|
||||
Create the PipeWire configuration directory:
|
||||
|
||||
``` sh
|
||||
mkdir -p "/etc/pipewire"
|
||||
```
|
||||
|
||||
Create the file `/etc/pipewire/pipewire.conf` with the following content (minimal configuration for voice assistant use):
|
||||
|
||||
``` ini
|
||||
# Daemon config file for PipeWire
|
||||
context.properties = {
|
||||
link.max-buffers = 16
|
||||
mem.warn-mlock = true
|
||||
log.level = 3
|
||||
context.num-data-loops = 1
|
||||
core.daemon = true
|
||||
core.name = pipewire-0
|
||||
default.clock.rate = 16000
|
||||
}
|
||||
|
||||
context.modules = [
|
||||
{ name = libpipewire-module-rt
|
||||
args = {
|
||||
nice.level = -11
|
||||
rt.prio = 88
|
||||
}
|
||||
flags = [ ifexists nofail ]
|
||||
}
|
||||
{ name = libpipewire-module-protocol-native }
|
||||
{ name = libpipewire-module-profiler }
|
||||
{ name = libpipewire-module-metadata }
|
||||
{ name = libpipewire-module-spa-device-factory }
|
||||
{ name = libpipewire-module-spa-node-factory }
|
||||
{ name = libpipewire-module-client-node }
|
||||
{ name = libpipewire-module-client-device }
|
||||
{ name = libpipewire-module-portal
|
||||
flags = [ ifexists nofail ]
|
||||
}
|
||||
{ name = libpipewire-module-access
|
||||
condition = [ { module.access = true } ]
|
||||
}
|
||||
{ name = libpipewire-module-adapter }
|
||||
{ name = libpipewire-module-link-factory }
|
||||
{ name = libpipewire-module-session-manager }
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
## B) PulseAudio:
|
||||
|
||||
Make sure that you only run Pulseaudio and there is no Pipewire installed.
|
||||
|
||||
sudo apt remove --purge pipewire pipewire-pulse wireplumber
|
||||
sudo apt autoremove
|
||||
|
||||
Install Pulseaudio
|
||||
|
||||
``` sh
|
||||
sudo apt install pulseaudio pulseaudio-utils dfu-util
|
||||
```
|
||||
|
||||
Enable and start Pulseaudio
|
||||
|
||||
``` sh
|
||||
systemctl --user enable pulseaudio
|
||||
systemctl --user start pulseaudio
|
||||
```
|
||||
|
||||
Check if Pulseaudio is running
|
||||
|
||||
``` sh
|
||||
pulseaudio --check
|
||||
pactl info
|
||||
```
|
||||
|
||||
|
||||
## Additional Information:
|
||||
|
||||
### Set audio volume:
|
||||
|
||||
If your driver or audiodevice is loaded and you can see the device with `aplay -L` then
|
||||
set the audio volume from 0 to 100:
|
||||
|
||||
```bash
|
||||
export XDG_RUNTIME_DIR=/run/user/${USER_ID}
|
||||
sudo amixer -c seeed2micvoicec set Headphone 100%
|
||||
sudo amixer -c seeed2micvoicec set Speaker 100%
|
||||
sudo amixer -c Lite set Headphone 100%
|
||||
sudo amixer -c Lite set Speaker 100%
|
||||
sudo alsactl store
|
||||
```
|
||||
|
||||
💡 **Note:** Replace `$USER_ID` with your actual user id that you want to run the voice assistant.
|
||||
|
||||
Alternatively you can use the following command to set the volume:
|
||||
|
||||
```bash
|
||||
export XDG_RUNTIME_DIR=/run/user/${USER_ID}
|
||||
sudo alsamixer
|
||||
```
|
||||
|
||||
💡 **Note:** Replace `$USER_ID` with your actual user id that you want to run the voice assistant.
|
||||
Reference in new issue
Block a user