Home Assistant Satellite

Python-based satellite for Assist that streams audio to Home Assistant from a microphone.

You must have the openWakeWord add-on installed.

Requirements

• Python 3.9 or higher
• ffmpeg
• libportaudio2 (for sounddevice)

Installation

Install Python and the required system dependencies:

apt-get install python3 python3-pip python3-venv \
                ffmpeg libportaudio2

Clone the repository and run the setup script:

git clone https://github.com/synesthesiam/homeassistant-satellite.git
cd homeassistant-satellite
script/setup

This will create a virtual environment and install the package.

Long-Lived Access Token

You must create a long-lived access token in Home Assistant for the satellite to access the websocket API.

1. Go to your profile page in Home Assistant
2. Scroll down to "Long-lived access tokens"
3. Click "Create token"
4. Enter a name and click "OK"
5. Copy the entire token using the copy button provided
6. Save the token somewhere you can paste from later

Running

script/run --host <IP> --token <TOKEN>

where <IP> is the IP address of your Home Assistant server and <TOKEN> is the long-lived access token.

This will stream audio from the default microphone to your preferred pipeline in Home Assistant.

See --help for more options

Feedback Sounds

Use --awake-sound <WAV> and --done-sound <WAV> to play sounds when the wake word is detected and when a voice command is finished.

For example:

script/run ... --awake-sound sounds/awake.wav --done.wav sounds/done.wav

Change Microphone/Speaker

Use --mic-device <NUMBER> and --snd-device <NUMBER> to change the microphone and speaker. Get a list of devices with:

python3 -m sounddevice

Voice Activity Detection

Use --vad webrtcvad to only stream audio when speech is detected.

Make use of silero VAD with:

.venv/bin/pip3 install -r requirements_extra.txt

and

script/run ... --vad silero

Audio Enhancements

Use --noise-suppression <NS> suppress background noise, such as fans (0-4 with 4 being max suppression, default: 0).

Use--auto-gain <AG> to automatically increase the microphone volume (0-31 with 31 being the loudest, default: 0).

Use--volume-multiplier <VM> to multiply volume by <VM> so 2.0 would be twice as loud (default: 1.0).

Troubleshooting

Add --debug to get more information about the messages being exchanged with Home Assistant.

Add --debug-recording-dir <DIR> to save recorded audio to a directory <DIR>.