diff --git a/README.md b/README.md index 962f852..5d3a91c 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,28 @@ # Linux Voice Assistant -Experimental Linux voice assistant for [Home Assistant][homeassistant] that uses the [ESPHome][esphome] protocol. +Experimental Linux voice assistant (LVA) for [Home Assistant][homeassistant] that uses the [ESPHome][esphome] protocol. Runs on Linux `aarch64` and `x86_64` platforms. Tested with Python 3.13 and Python 3.11. Supports announcments, start/continue conversation, and timers. +See [the tutorial](docs/linux-voice-assistant-2mic-install.md) to build a satellite using a [Raspberry Pi Zero 2 W](https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/) and a [ReSpeaker 2Mic HAT](https://wiki.keyestudio.com/Ks0314_keyestudio_ReSpeaker_2-Mic_Pi_HAT_V1.0). + +### What's working: +- This fork introduces the ability to use Wyoming OpenWakeWord (OWW) instead of MicroWakeWord (MWW). +- Now supports **ALSA, PulseAudio and PipeWire** playback backends using the updated `linux_voice_assistant/mpv_player.py`. +- You can choose between ALSA, PulseAudio, or PipeWire with either MWW or OWW simply by enabling the matching systemd service file. +- You can change the OWW wake word within HA after the VLA is registered. (defaults to the wake word defind in the systemd config file) +- Home Assistant successfully detects the LVA when Avahi is setup according to the tutorial. + ## Installation Install system dependencies (`apt-get`): -* `libportaudio2` or `portaudio19-dev` (for `sounddevice`) +* `libportaudio2` (for `sounddevice`) * `build-essential` (for `pymicro-features`) * `libmpv-dev` (for `python-mpv`) +* `mpv` (for testing) +* `libmpv-dev` (for building spidev) Clone and install project: @@ -25,25 +36,8 @@ script/setup Use `script/run` or `python3 -m linux_voice_assistant` -You must specify `--name ` with a name that will be available in Home Assistant. - See `--help` for more options. -### Microphone - -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 ` where `` 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" @@ -52,6 +46,22 @@ Change the default wake word with `--wake-model ` where `` is the name o 4. Enter the IP address of your voice satellite with port 6053 5. Click "Submit" + +## ToDo: + +* Implement echo-cancellation filter in PipeWire. (Improves wake word detection when audio is being played) +* Merge jianyu-li's PR from source project to add mute switch function in this branch +* ~~Configure LVA to advertise on Zeroconf/mDNS via Avahi for HA to auto detect (in progress)~~ +* Implement a single LVA systemd unit file that can be addapted using profiles and drop-ins (in progress) +* Implement OWW model validation checks and error handling so that a bad model doesn't crash OWW +* Make the selection of the right ALSA ar PA device more scripted +* ~~Make a Docker of the project~~ Already done in parent repo. +* Add sensor entity that displays which wake word engine is being used for HA +* Could this be an DEB package? +* Implement Stop for OWW +* Stretch goal: create a smart installer full of validation and sanity checks [homeassistant]: https://www.home-assistant.io/ [esphome]: https://esphome.io/ +[wyoming]: https://github.com/rhasspy/wyoming-openwakeword/ +[future proof home]: https://github.com/FutureProofHomes/wyoming-enhancements/ diff --git a/requirements.txt b/requirements.txt index be3245c..e2b529f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,5 @@ aioesphomeapi sounddevice +gpiozero +spidev +adafruit-circuitpython-dotstar