nc/linux-voice-assistant
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Feature/custom paths (#165)

Browse Source 
* add possibility to add own wake words and sounds
* improve documentation

---------

Co-authored-by: Florian Asche <git@florian-asche.de>
This commit is contained in:
Florian AscheandFlorian Asche authored and GitHub committed 2026-02-20 19:05:38 +01:00
1 parent 033ff45baf
commit 70fab99c9f
7 files changed
+397 -39
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/install_application.md
+16 -7
View File
@@ -272,9 +272,10 @@ The following variables can be configured in the `.env` or in the service file:
| `NETWORK_INTERFACE` | Autodetected | network card for server |
| `HOST` | Autodetected | API server IP-Address, can be 0.0.0.0 for all interfaces, but only one network card works for MAC-ADDRESS and ESP protocol |
| `PORT` | `6053` | API server port |
| `AUDIO_INPUT_DEVICE` | `default` | Audio input device name |
| `AUDIO_OUTPUT_DEVICE` | `default` | Audio output device name |
| `AUDIO_INPUT_DEVICE` | Autodetected | Audio input device name |
| `AUDIO_OUTPUT_DEVICE` | Autodetected | Audio output device name |
| `ENABLE_THINKING_SOUND` | false | Set to "1" to enable thinking sound |
| `WAKE_WORD_DIR` | `app/wakewords` | Path to the wake word directory |
| `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 |
@@ -283,6 +284,14 @@ The following variables can be configured in the `.env` or in the service file:
| `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
### Use own soundfiles:
If you want to use your own sounds, you can add them to the `sounds/custom` aka `/var/lib/docker/volumes/lva_sounds_custom/_data` directory and reference them in the `.env` file.
### Wake Word:
#### Available Wake Word Models:
The following wake word models are available:
@@ -297,13 +306,13 @@ The following wake word models are available:
- `choo_choo_homie` - Choo Choo Homie wake word
### Wake Word:
### Custom Wake Word:
💡 **Note:** The default value for this parameter is the `wakewords` directory in the repository.
If you want to use your own wakewords, you can add them to the `wakewords/custom` aka `/var/lib/docker/volumes/lva_wakeword_custom/_data` directory and reference them in the `.env` file.
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.
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 `app/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.
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 app/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:
@@ -315,7 +324,7 @@ If you want to add [other wakewords][wakewords-collection], make sure to create
}
```
Add `--wake-word-dir <DIR>` with the directory containing `glados.tflite` and `glados.json` to your command-line.
Add `WAKE_WORD_DIR <DIR>` with the directory containing `glados.tflite` and `glados.json` to your command-line.
#### Additional Wakewords:
docs/install_audioserver.md
+349 -23
View File
@@ -1,12 +1,16 @@
# 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.
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 with pipewire-pulse. You can choose either variant A or B from this installation documentation.
**How does the communication work?**
The Linux-Voice-Assistant container connects to the PulseAudio(PipeWire-Pulse) server running on the host system. The container does not have direct access to the sound card hardware. Instead, it communicates with the PulseAudio running on the host system, which then handles the actual audio processing and output.
## A) Pipewire (recommended):
PipeWire is a multimedia server that provides low-latency audio/video handling. Install it with the following commands:
``` sh
```sh
# Update package database
sudo apt update
@@ -16,13 +20,13 @@ sudo apt install -y pipewire wireplumber pipewire-audio-client-libraries libspa-
Link the PipeWire configuration for ALSA applications:
``` sh
```sh
sudo 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
```sh
sudo mkdir -p /var/lib/systemd/linger
sudo touch /var/lib/systemd/linger/$USER
```
@@ -31,86 +35,408 @@ sudo touch /var/lib/systemd/linger/$USER
### Configure PipeWire (optional):
💡 **Note:** If you are not on a desktop system, which is already configured for PipeWire, you can configure it manually.
Create the PipeWire configuration directory:
``` sh
```sh
sudo 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
```ini
# Daemon config file for PipeWire version "1.2.7" #
#
# Copy and edit this file in /etc/pipewire for system-wide changes
# or in ~/.config/pipewire for local changes.
#
# It is also possible to place a file with an updated section in
# /etc/pipewire/pipewire.conf.d/ for system-wide changes or in
# ~/.config/pipewire/pipewire.conf.d/ for local changes.
#
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
## Configure properties in the system.
#library.name.system = support/libspa-support
#context.data-loop.library.name.system = support/libspa-support
#support.dbus = true
#link.max-buffers = 64
link.max-buffers = 16 # version < 3 clients can't handle more
mem.warn-mlock = true
#mem.allow-mlock = true
#mem.mlock-all = false
#clock.power-of-two-quantum = true
log.level = 3
#cpu.zero.denormals = false
#loop.rt-prio = -1 # -1 = use module-rt prio, 0 disable rt
#loop.class = data.rt
#thread.affinity = [ 0 1 ] # optional array of CPUs
context.num-data-loops = 1 # -1 = num-cpus, 0 = no data loops
#
#context.data-loops = [
# { loop.rt-prio = -1
# loop.class = [ data.rt audio.rt ]
# #library.name.system = support/libspa-support
# thread.name = data-loop.0
# #thread.affinity = [ 0 1 ] # optional array of CPUs
# }
#]
core.daemon = true # listening for socket connections
core.name = pipewire-0 # core name and socket name
## Properties for the DSP configuration.
default.clock.rate = 16000
#default.clock.allowed-rates = [ 48000 ]
#default.clock.quantum = 1024
#default.clock.min-quantum = 32
#default.clock.max-quantum = 2048
#default.clock.quantum-limit = 8192
#default.clock.quantum-floor = 4
#default.video.width = 640
#default.video.height = 480
#default.video.rate.num = 25
#default.video.rate.denom = 1
#
#settings.check-quantum = false
#settings.check-rate = false
# keys checked below to disable module loading
module.x11.bell = true
# enables autoloading of access module, when disabled an alternative
# access module needs to be loaded.
module.access = true
# enables autoloading of module-jackdbus-detect
module.jackdbus-detect = true
}
context.properties.rules = [
{ matches = [ { cpu.vm.name = !null } ]
actions = {
update-props = {
# These overrides are only applied when running in a vm.
default.clock.min-quantum = 1024
}
}
}
]
context.spa-libs = {
#<factory-name regex> = <library-name>
#
# Used to find spa factory names. It maps an spa factory name
# regular expression to a library name that should contain
# that factory.
#
audio.convert.* = audioconvert/libspa-audioconvert
avb.* = avb/libspa-avb
api.alsa.* = alsa/libspa-alsa
#api.v4l2.* = v4l2/libspa-v4l2
#api.libcamera.* = libcamera/libspa-libcamera
api.bluez5.* = bluez5/libspa-bluez5
api.vulkan.* = vulkan/libspa-vulkan
api.jack.* = jack/libspa-jack
support.* = support/libspa-support
#video.convert.* = videoconvert/libspa-videoconvert
#videotestsrc = videotestsrc/libspa-videotestsrc
#audiotestsrc = audiotestsrc/libspa-audiotestsrc
}
context.modules = [
#{ name = <module-name>
# ( args = { <key> = <value> ... } )
# ( flags = [ ( ifexists ) ( nofail ) ] )
# ( condition = [ { <key> = <value> ... } ... ] )
#}
#
# Loads a module with the given parameters.
# If ifexists is given, the module is ignored when it is not found.
# If nofail is given, module initialization failures are ignored.
# If condition is given, the module is loaded only when the context
# properties all match the match rules.
#
# Uses realtime scheduling to boost the audio thread priorities. This uses
# RTKit if the user doesn't have permission to use regular realtime
# scheduling. You can also clamp utilisation values to improve scheduling
# on embedded and heterogeneous systems, e.g. Arm big.LITTLE devices.
{ name = libpipewire-module-rt
args = {
nice.level = -11
rt.prio = 88
nice.level = -11
rt.prio = 88
#rt.time.soft = -1
#rt.time.hard = -1
#uclamp.min = 0
#uclamp.max = 1024
}
flags = [ ifexists nofail ]
}
{ name = libpipewire-module-protocol-native }
# The native communication protocol.
{ name = libpipewire-module-protocol-native
args = {
# List of server Unix sockets, and optionally permissions
#sockets = [ { name = "pipewire-0" }, { name = "pipewire-0-manager" } ]
}
}
# The profile module. Allows application to access profiler
# and performance data. It provides an interface that is used
# by pw-top and pw-profiler.
{ name = libpipewire-module-profiler }
# Allows applications to create metadata objects. It creates
# a factory for Metadata objects.
{ name = libpipewire-module-metadata }
# Creates a factory for making devices that run in the
# context of the PipeWire server.
{ name = libpipewire-module-spa-device-factory }
# Creates a factory for making nodes that run in the
# context of the PipeWire server.
{ name = libpipewire-module-spa-node-factory }
# Allows creating nodes that run in the context of the
# client. Is used by all clients that want to provide
# data to PipeWire.
{ name = libpipewire-module-client-node }
# Allows creating devices that run in the context of the
# client. Is used by the session manager.
{ name = libpipewire-module-client-device }
# The portal module monitors the PID of the portal process
# and tags connections with the same PID as portal
# connections.
{ name = libpipewire-module-portal
flags = [ ifexists nofail ]
}
# The access module can perform access checks and block
# new clients.
{ name = libpipewire-module-access
args = {
# Socket-specific access permissions
#access.socket = { pipewire-0 = "default", pipewire-0-manager = "unrestricted" }
# Deprecated legacy mode (not socket-based),
# for now enabled by default if access.socket is not specified
#access.legacy = true
}
condition = [ { module.access = true } ]
}
# Makes a factory for wrapping nodes in an adapter with a
# converter and resampler.
{ name = libpipewire-module-adapter }
# Makes a factory for creating links between ports.
{ name = libpipewire-module-link-factory }
# Provides factories to make session manager objects.
{ name = libpipewire-module-session-manager }
# Use libcanberra to play X11 Bell
{ name = libpipewire-module-x11-bell
args = {
#sink.name = "@DEFAULT_SINK@"
#sample.name = "bell-window-system"
#x11.display = null
#x11.xauthority = null
}
flags = [ ifexists nofail ]
condition = [ { module.x11.bell = true } ]
}
{ name = libpipewire-module-jackdbus-detect
args = {
#jack.library = libjack.so.0
#jack.server = null
#jack.client-name = PipeWire
#jack.connect = true
#tunnel.mode = duplex # source|sink|duplex
source.props = {
#audio.channels = 2
#midi.ports = 1
#audio.position = [ FL FR ]
# extra sink properties
}
sink.props = {
#audio.channels = 2
#midi.ports = 1
#audio.position = [ FL FR ]
# extra sink properties
}
}
flags = [ ifexists nofail ]
condition = [ { module.jackdbus-detect = true } ]
}
]
context.objects = [
#{ factory = <factory-name>
# ( args = { <key> = <value> ... } )
# ( flags = [ ( nofail ) ] )
# ( condition = [ { <key> = <value> ... } ... ] )
#}
#
# Creates an object from a PipeWire factory with the given parameters.
# If nofail is given, errors are ignored (and no object is created).
# If condition is given, the object is created only when the context properties
# all match the match rules.
#
#{ factory = spa-node-factory args = { factory.name = videotestsrc node.name = videotestsrc node.description = videotestsrc "Spa:Pod:Object:Param:Props:patternType" = 1 } }
#{ factory = spa-device-factory args = { factory.name = api.jack.device foo=bar } flags = [ nofail ] }
#{ factory = spa-device-factory args = { factory.name = api.alsa.enum.udev } }
#{ factory = spa-node-factory args = { factory.name = api.alsa.seq.bridge node.name = Internal-MIDI-Bridge } }
#{ factory = adapter args = { factory.name = audiotestsrc node.name = my-test node.description = audiotestsrc } }
#{ factory = spa-node-factory args = { factory.name = api.vulkan.compute.source node.name = my-compute-source } }
# A default dummy driver. This handles nodes marked with the "node.always-process"
# property when no other driver is currently active. JACK clients need this.
{ factory = spa-node-factory
args = {
factory.name = support.node.driver
node.name = Dummy-Driver
node.group = pipewire.dummy
node.sync-group = sync.dummy
priority.driver = 200000
#clock.id = monotonic # realtime | tai | monotonic-raw | boottime
#clock.name = "clock.system.monotonic"
}
}
{ factory = spa-node-factory
args = {
factory.name = support.node.driver
node.name = Freewheel-Driver
priority.driver = 190000
node.group = pipewire.freewheel
node.sync-group = sync.dummy
node.freewheel = true
#freewheel.wait = 10
}
}
# This creates a new Source node. It will have input ports
# that you can link, to provide audio for this source.
#{ factory = adapter
# args = {
# factory.name = support.null-audio-sink
# node.name = "my-mic"
# node.description = "Microphone"
# media.class = "Audio/Source/Virtual"
# audio.position = "FL,FR"
# monitor.passthrough = true
# }
#}
# This creates a single PCM source device for the given
# alsa device path hw:0. You can change source to sink
# to make a sink in the same way.
#{ factory = adapter
# args = {
# factory.name = api.alsa.pcm.source
# node.name = "alsa-source"
# node.description = "PCM Source"
# media.class = "Audio/Source"
# api.alsa.path = "hw:0"
# api.alsa.period-size = 1024
# api.alsa.headroom = 0
# api.alsa.disable-mmap = false
# api.alsa.disable-batch = false
# audio.format = "S16LE"
# audio.rate = 48000
# audio.channels = 2
# audio.position = "FL,FR"
# }
#}
# Use the metadata factory to create metadata and some default values.
#{ factory = metadata
# args = {
# metadata.name = my-metadata
# metadata.values = [
# { key = default.audio.sink value = { name = somesink } }
# { key = default.audio.source value = { name = somesource } }
# ]
# }
#}
]
context.exec = [
#{ path = <program-name>
# ( args = "<arguments>" | [ <arg1> <arg2> ... ] )
# ( condition = [ { <key> = <value> ... } ... ] )
#}
#
# Execute the given program with arguments.
# If condition is given, the program is executed only when the context
# properties all match the match rules.
#
# You can optionally start the session manager here,
# but it is better to start it as a systemd service.
# Run the session manager with -h for options.
#
#{ path = "/usr/bin/pipewire-media-session" args = ""
# condition = [ { exec.session-manager = null } { exec.session-manager = true } ] }
#
# You can optionally start the pulseaudio-server here as well
# but it is better to start it as a systemd service.
# It can be interesting to start another daemon here that listens
# on another address with the -a option (eg. -a tcp:4713).
#
#{ path = "/usr/bin/pipewire" args = [ "-c" "pipewire-pulse.conf" ]
# condition = [ { exec.pipewire-pulse = null } { exec.pipewire-pulse = true } ] }
]
```
## B) PulseAudio:
Make sure that you only run Pulseaudio and there is no Pipewire installed.
``` sh
```sh
sudo apt remove --purge pipewire pipewire-pulse wireplumber
sudo apt autoremove
```
Install Pulseaudio
``` sh
```sh
sudo apt install pulseaudio pulseaudio-utils dfu-util
```
Enable and start Pulseaudio
``` sh
```sh
systemctl --user enable pulseaudio
systemctl --user start pulseaudio
```
Check if Pulseaudio is running
``` sh
```sh
pulseaudio --check
pactl info
```
## Additional Information:
### Debug audio output:
You can debug the audio output with the following command:
```bash
export LVA_XDG_RUNTIME_DIR=/run/user/${LVA_USER_ID}
sudo aplay -L
speaker-test -D pulse -c2 -twav
```
💡 **Note:** Replace `$LVA_USER_ID` with your actual user id that you want to run the voice assistant.
💡 **Note:** You can replace `pulse` with `default` or `alsa_output.pci-0000_00_1f.3.analog-stereo` or any other audio device.
### Set audio volume:
If your driver or audiodevice is loaded and you can see the device with `aplay -L` then