Merge branch 'main' into patch-1
This commit is contained in:
50 files changed
+2521
-967
No files matched your search
@@ -1,57 +1,78 @@
|
||||
# Linux Voice Assistant
|
||||
# Linux-Voice-Assistant
|
||||
|
||||
Experimental Linux voice assistant for [Home Assistant][homeassistant] that uses the [ESPHome][esphome] protocol/API (via [aioesphomeapi](https://github.com/esphome/aioesphomeapi)).
|
||||
[](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.
|
||||
|
||||
## Installation
|
||||
## Features:
|
||||
|
||||
Install system dependencies (`apt-get`):
|
||||
- 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
|
||||
|
||||
* `libportaudio2` or `portaudio19-dev` (for `sounddevice`)
|
||||
* `build-essential` (for `pymicro-features`)
|
||||
* `libmpv-dev` (for `python-mpv`)
|
||||
|
||||
Clone and install project:
|
||||
## Usage:
|
||||
|
||||
### Hardware:
|
||||
|
||||
You can for example use the Raspberry Pi Zero 2W with the [Satellite1 Hat Board](https://futureproofhomes.net/products/satellite1-top-microphone-board), the [Respeaker Lite](https://wiki.seeedstudio.com/reSpeaker_usb_v3/) 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 with the prebuild image.
|
||||
|
||||
### Software:
|
||||
|
||||
#### Installation:
|
||||
|
||||
We have different installation methods available (Docker, systemd), each with its own dedicated instructions.
|
||||
|
||||
See [Linux-Voice-Assistant - Installation](docs/install.md).
|
||||
|
||||
#### Parameter overview:
|
||||
|
||||
``` sh
|
||||
git clone https://github.com/OHF-Voice/linux-voice-assistant.git
|
||||
cd linux-voice-assistant
|
||||
script/setup
|
||||
usage: __main__.py [-h] [--name NAME] [--audio-input-device AUDIO_INPUT_DEVICE] [--list-input-devices]
|
||||
[--audio-input-block-size AUDIO_INPUT_BLOCK_SIZE] [--audio-output-device AUDIO_OUTPUT_DEVICE]
|
||||
[--list-output-devices] [--wake-word-dir WAKE_WORD_DIR] [--wake-model WAKE_MODEL] [--stop-model STOP_MODEL]
|
||||
[--download-dir DOWNLOAD_DIR] [--refractory-seconds REFRACTORY_SECONDS] [--wakeup-sound WAKEUP_SOUND]
|
||||
[--timer-finished-sound TIMER_FINISHED_SOUND] [--processing-sound PROCESSING_SOUND] [--mute-sound MUTE_SOUND]
|
||||
[--unmute-sound UNMUTE_SOUND] [--preferences-file PREFERENCES_FILE] [--host HOST] [--port PORT]
|
||||
[--enable-thinking-sound] [--debug]
|
||||
```
|
||||
|
||||
## Running
|
||||
| Parameter | Description | Default |
|
||||
|-----------|-------------|---------|
|
||||
| `--name` | Name of the voice assistant device (required) | - |
|
||||
| `--audio-input-device` | Soundcard name for input device | System default microphone |
|
||||
| `--audio-input-block-size` | Audio input block size in samples | 1024 |
|
||||
| `--audio-output-device` | mpv name for output device | System default speaker |
|
||||
| `--wake-word-dir` | Directory with wake word models (.tflite) and configs (.json) | `wakewords/` |
|
||||
| `--wake-model` | ID of active wake word model | `okay_nabu` |
|
||||
| `--stop-model` | ID of stop model | `stop` |
|
||||
| `--download-dir` | Directory to download custom wake word models, etc. | `local/` |
|
||||
| `--refractory-seconds` | Seconds before wake word can be activated again | 2.0 |
|
||||
| `--wakeup-sound` | Sound file played when wake word is detected | `sounds/wake_word_triggered.flac` |
|
||||
| `--timer-finished-sound` | Sound file played when timer finishes | `sounds/timer_finished.flac` |
|
||||
| `--processing-sound` | Sound played while assistant is processing | `sounds/processing.wav` |
|
||||
| `--mute-sound` | Sound played when muting the assistant | `sounds/mute_switch_on.flac` |
|
||||
| `--unmute-sound` | Sound played when unmuting the assistant | `sounds/mute_switch_off.flac` |
|
||||
| `--preferences-file` | Path to preferences JSON file | `preferences.json` |
|
||||
| `--host` | Address for ESPHome server | `0.0.0.0` |
|
||||
| `--port` | Port for ESPHome server | 6053 |
|
||||
| `--enable-thinking-sound` | Enable thinking sound on startup | False |
|
||||
| `--debug` | Print DEBUG messages to console | False |
|
||||
|
||||
Use `script/run` or `python3 -m linux_voice_assistant`
|
||||
## Build Information:
|
||||
|
||||
You must specify `--name <NAME>` with a name that will be available in Home Assistant.
|
||||
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.
|
||||
|
||||
See `--help` for more options.
|
||||
The Docker images are built using GitHub Actions, which provides:
|
||||
|
||||
### Microphone
|
||||
- Automated builds for different architectures
|
||||
- Artifact attestation for build provenance verification
|
||||
- Regular updates and maintenance
|
||||
|
||||
Use `--audio-input-device` to change the microphone device. Use `python3 -m sounddevice` to see the available PortAudio devices.
|
||||
|
||||
The microphone device **must** support 16Khz mono audio.
|
||||
|
||||
### Speaker
|
||||
|
||||
Use `--audio-output-device` to change the speaker device. Use `mpv --audio-device=help` to see the available MPV devices.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
## 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"
|
||||
|
||||
<!-- Links -->
|
||||
[homeassistant]: https://www.home-assistant.io/
|
||||
[esphome]: https://esphome.io/
|
||||
The documentation for the build process can be found in the [GitHub Actions Workflows](.github/workflow.md) file.
|
||||
Reference in new issue
Block a user