Skip to content

lva-desktop.md

Latest commit

 

History

History
212 lines (151 loc) · 5.58 KB

lva-desktop.md

File metadata and controls

212 lines (151 loc) · 5.58 KB

Want to run LVA on a Linux Graphical Desktop?

This guide covers installing the Linux Voice Assistant (LVA) on a desktop Linux distribution (Debian, Fedora, Arch) and setting up the System Tray Client.

1. Install System Dependencies

You will need Python headers, mpv (for audio playback), and git.

Debian / Ubuntu / Raspberry Pi OS:

sudo apt update
sudo apt install \
  libmpv-dev git python3-dev mpv python3-venv

Fedora:

sudo dnf install \
  mpv-devel python3-devel git mpv

Arch Linux:

sudo pacman -Syu \
  python python-pip mpv

Note: The tray client uses PyQt5 (installed via script/setup --tray). If PyQt5 fails to import or the tray icon does not appear on minimal desktops, you may need additional Qt/X11 system packages for your distro.

2. Configure Firewall

LVA uses port 6053 (TCP/UDP) for the ESPHome API. If you have a firewall enabled, you must allow this port so Home Assistant can connect.

UFW (Ubuntu/Debian):

sudo ufw allow 6053/udp
sudo ufw allow 6053/tcp
sudo ufw reload

FirewallD (Fedora/CentOS):

sudo firewall-cmd --permanent --zone=public --add-port=6053/tcp
sudo firewall-cmd --permanent --zone=public --add-port=6053/udp
sudo firewall-cmd --reload

3. Get the Code

git clone https://github.com/imonlinux/linux-voice-assistant.git
cd linux-voice-assistant

4. Install LVA

We will set up a virtual environment and install the package with the optional [tray] dependencies (which installs PyQt5).

# Run the setup script (creates .venv and installs core deps + tray extras)
script/setup --tray

5. Configure LVA

Create your configuration file:

nano linux_voice_assistant/config.json

Important: For the Tray Client to show status colors (listening, thinking, etc.) and control the mute state, MQTT is required.

  • The tray client requires mqtt.host to be set.
  • If MQTT is disabled or missing, the tray client will not be able to show online/offline status, state colors, or mute control.

Update the example below with your specific MQTT broker details:

{
  "app": {
    "name": "My Desktop Assistant"
  },
  "mqtt": {
    "host": "192.168.1.X",
    "port": 1883,
    "username": "your_mqtt_user",
    "password": "your_mqtt_password"
  },
  "tray": {
    "systemd_service_name": "linux-voice-assistant.service"
  }
}

tray.systemd_service_name is the service that the tray menu will start/stop/restart. You can omit this section if you are using the name linux-voice-assistant.service already as it is the default.

6. Set up Systemd Services

We will run LVA as a user-level service so it has access to your user audio session (PulseAudio/PipeWire).

A. Main LVA Service

mkdir -p ~/.config/systemd/user
cp service/linux-voice-assistant.service ~/.config/systemd/user/

Edit the service to match your installation path:

systemctl --user edit --force --full linux-voice-assistant.service

Replace /path/to/linux-voice-assistant with your actual directory (e.g., /home/yourname/linux-voice-assistant):

[Unit]
Description=Linux Voice Assistant
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
# UPDATE THIS PATH:
WorkingDirectory=/path/to/linux-voice-assistant
Environment=PYTHONUNBUFFERED=1

# UPDATE THIS PATH:
ExecStart=/path/to/linux-voice-assistant/script/run

Restart=always
RestartSec=2

[Install]
WantedBy=default.target

B. Tray Client Service

cp service/linux-voice-assistant-tray.service ~/.config/systemd/user/

Edit the tray service to match your installation path:

systemctl --user edit --force --full linux-voice-assistant-tray.service

Again, update the paths:

[Unit]
Description=Linux Voice Assistant Tray Client
# Make sure we have a graphical session
After=graphical-session.target
Wants=graphical-session.target

[Service]
Type=simple
# UPDATE THIS PATH:
WorkingDirectory=/path/to/linux-voice-assistant

# UPDATE THIS PATH:
ExecStart=/path/to/linux-voice-assistant/script/tray

Restart=on-failure
RestartSec=2

[Install]
WantedBy=default.target

The repository ships a tray unit file in service/linux-voice-assistant-tray.service. Prefer copying and editing that file as shown above, rather than hand-authoring targets that may differ between desktop environments.

7. Start the Application

You only need to enable and start the Tray Client. The Tray Client has a menu option to start/stop the main LVA background service for you.

systemctl --user daemon-reload
systemctl --user enable --now linux-voice-assistant-tray.service

8. Using the Tray Client

  1. Icon: You should see a small circle icon in your system tray.
  • Grey: Offline / LVA Service not running.
  • Idle: Idle (Connected). Default is purple unless you change the Idle color via Home Assistant.
  • Blue: Listening.
  • Yellow: Thinking (Processing).
  • Green: Responding (TTS).
  • Orange: Error.
  • Red Tint: Microphone Muted.
  1. Menu: Left-click or Right-click the icon to:
  • Start LVA: Launches the main background service.
  • Mute Microphone: Toggles the software mute state.
  • Restart/Stop LVA: Controls the background service.
  1. Home Assistant Integration:
  • Once LVA connects to MQTT, it will discover several entities in Home Assistant.
  • You can change the LED/icon colors for each state (Idle, Listening, etc.) directly from Home Assistant using the Light entities created by LVA (e.g., light.my_desktop_assistant_idle_color). The tray icon will update instantly to match these settings.