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

docs(readme): restructure requirements and hardware section (#321)

Browse Source 
Refactor the README to improve clarity by replacing the "Usage" section with a dedicated "Requirements" section. This includes:
- Adding specific hardware requirements (Microphone, CPU, Memory, Storage, OS).
- Updating recommended hardware configurations for better readability.
- Clarifying compatibility notes regarding Raspberry Pi Zero 2W and Respeaker Lite.
This commit is contained in:
Florian Asche authored and GitHub committed 2026-05-14 19:34:47 +02:00
1 parent b1e36b0cc3
commit 19c4c2337f
1 file changed
+61 -50
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+61 -50
View File
@@ -24,69 +24,74 @@ Because it runs on a full Linux system and offers access significantly more loca
- Prebuild docker image available on [GitHub Container Registry](https://github.com/OHF-Voice/linux-voice-assistant/pkgs/container/linux-voice-assistant) - 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](https://github.com/florian-asche/PiCompose) - Prebuild [Raspberry Pi image](https://github.com/florian-asche/PiCompose)
## Usage ## Requirements
### Hardware - Microphone: Device must support 16kHz mono audio
- CPU: 1Ghz
- Memory: min. 512MB
- Storage: The OS and software is around 4GB
- OS: linux/amd64 or linux/aarch64
A more extensive 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 (multimedia framework for Linux)](https://pipewire.org/) can in theory be used for voice input with the prebuild image from there, you should however preferably use a far-field microphone-array solution if want better result. However if you're using your own USB microphone, **the microphone device must support 16kHz mono audio** for optimal voice recognition performance. A more extensive 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 (multimedia framework for Linux)](https://pipewire.org/) can in theory be used for voice input with the prebuild image from there, you should however preferably use a far-field microphone-array solution if want better result. However if you're using your own USB microphone, **the microphone device must support 16kHz mono audio** for optimal voice recognition performance.
Two solutions recommended for test setups today is to use a Raspberry Pi Zero 2 W SBC (Single Board Computer with built-in WiFi) in combination with the [Satellite1 Hat Board](https://futureproofhomes.net/products/satellite1-top-microphone-board) or the [Respeaker Lite](https://wiki.seeedstudio.com/reSpeaker_usb_v3/). Those have microphone-array designed for far-field voice capture with the added benefit of using an onboard XMOS DSP microcontroller with custom firmware which does advanced audio pre-processing for microphone cleanup that result in very good voice recognition capabilities (as it runs algorithms for Noise Suppression, Acoustic Echo Cancellation, Interference Cancellation, and Automatic Gain Control). Two solutions recommended for setups today is:
Alternatively if on a lower budget then suggest could try other untested microphone-array boards like example the [reSpeaker 2-Mics Pi HAT V2.0](https://wiki.seeedstudio.com/ReSpeaker_2_Mics_Pi_HAT/) (which uses a much more basic audio codec chip). - use a Raspberry Pi Zero 2W (Single Board Computer with built-in WiFi) in combination with the [Satellite1 Hat Board](https://futureproofhomes.net/products/satellite1-top-microphone-board)
- use at least a Raspberry Pi 3 with the [Respeaker Lite](https://wiki.seeedstudio.com/reSpeaker_usb_v3/). The Respeaker Lite currently has a problem with the Zero 2W.
As for the minimum required compute performance on these satellites the target reference hardware for testing is currently a 64-bit ARM-based SBC based on Raspberry Pi RP3A0 SiP (System-in-Package); which means the Raspberry Pi Zero 2 W, Raspberry Pi Compute Module 3E (Raspberry Pi CM3E), or other development boards that uses the Compute Module Zero" (Raspberry Pi CM0), as all of which have similar specifications to the Raspberry Pi 3 B/B+ but with a CPU running at a lower frequency. Those mic-boards have microphone-array designed for far-field voice capture with the added benefit of using an onboard XMOS DSP microcontroller with custom firmware which does advanced audio pre-processing for microphone cleanup that result in very good voice recognition capabilities (as it runs algorithms for Noise Suppression, Acoustic Echo Cancellation, Interference Cancellation, and Automatic Gain Control).
But you can also install LVA on AMD64 devices, for example on your Linux desktop computer. Alternatively if on a lower budget then suggest could use other microphone-array boards like for example the [reSpeaker 2-Mics Pi HAT V2.0](https://wiki.seeedstudio.com/ReSpeaker_2_Mics_Pi_HAT/) (which uses a much more basic audio codec chip).
### Software ## Usage
#### Installation ### Installation
For Raspberry Pi users, we provide a prebuild image that can be flashed to a SD card. See [PiCompose](https://github.com/florian-asche/PiCompose). For Raspberry Pi users, we provide a prebuild image that can be flashed to a SD card. See [PiCompose](https://github.com/florian-asche/PiCompose).
For all other users, we have different installation methods available (Docker, systemd), each with its own dedicated instructions. See [Linux-Voice-Assistant - Installation](docs/install.md). For all other users, we have different installation methods available (Docker, systemd), each with its own dedicated instructions. See [Linux-Voice-Assistant - Installation](docs/install.md).
#### Parameter overview ### Parameter overview
💡 **Note:** There is an [environment variable](docs/install_application.md#environment-variables-reference) for each parameter if you use docker or systemd based setup. 💡 **Note:** There is an [environment variable](docs/install_application.md#environment-variables-reference) for each parameter if you use docker or systemd based setup.
``` sh ```sh
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] [--mic-auto-gain] [--mic-noise-suppression] 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] [--mic-auto-gain] [--mic-noise-suppression]
[--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] [--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] [--network-interface NETWORK_INTERFACE] [--port PORT] [--enable-thinking-sound] [--debug] [--mute-sound MUTE_SOUND] [--unmute-sound UNMUTE_SOUND] [--preferences-file PREFERENCES_FILE] [--host HOST] [--network-interface NETWORK_INTERFACE] [--port PORT] [--enable-thinking-sound] [--debug]
``` ```
| Parameter | Description | Default |
|-----------|-------------|---------| | Parameter | Description | Default |
| `--name` | Name of the voice assistant device (required) | Autogenerated (`lva-MAC-ADDRESS`) | | ---------------------------- | --------------------------------------------------------------- | ----------------------------------- |
| `--audio-input-device` | Soundcard name for input device | Autodetected | | `--name` | Name of the voice assistant device (required) | Autogenerated (`lva-MAC-ADDRESS`) |
| `--audio-input-block-size` | Audio input block size in samples | 1024 | | `--audio-input-device` | Soundcard name for input device | Autodetected |
| `--audio-output-device` | mpv name for output device | Autodetected | | `--audio-input-block-size` | Audio input block size in samples | 1024 |
| `--mic-volume` | Control microphone volume | 1.0 | | `--audio-output-device` | mpv name for output device | Autodetected |
| `--mic-auto-gain` | Add WebRTC Gain to Mic | 0 | | `--mic-volume` | Control microphone volume | 1.0 |
| `--mic-noise-suppression` | Add WebRTC Noise Suppression to Mic | 0 | | `--mic-auto-gain` | Add WebRTC Gain to Mic | 0 |
| `--wake-word-dir` | Directory with wake word models (.tflite) and configs (.json) | `wakewords/` | | `--mic-noise-suppression` | Add WebRTC Noise Suppression to Mic | 0 |
| `--wake-model` | ID of active wake word model | `okay_nabu` | | `--wake-word-dir` | Directory with wake word models (.tflite) and configs (.json) | `wakewords/` |
| `--stop-model` | ID of stop model | `stop` | | `--wake-model` | ID of active wake word model | `okay_nabu` |
| `--download-dir` | Directory to download custom wake word models, etc. | `local/` | | `--stop-model` | ID of stop model | `stop` |
| `--refractory-seconds` | Seconds before wake word can be activated again | 2.0 | | `--download-dir` | Directory to download custom wake word models, etc. | `local/` |
| `--timer-max-ring-seconds` | Seconds after which the timer stops ringing | 900.0 | | `--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-max-ring-seconds` | Seconds after which the timer stops ringing | 900.0 |
| `--timer-finished-sound` | Sound file played when timer finishes | `sounds/timer_finished.flac` | | `--wakeup-sound` | Sound file played when wake word is detected | `sounds/wake_word_triggered.flac` |
| `--processing-sound` | Sound played while assistant is processing | `sounds/processing.wav` | | `--timer-finished-sound` | Sound file played when timer finishes | `sounds/timer_finished.flac` |
| `--mute-sound` | Sound played when muting the assistant | `sounds/mute_switch_on.flac` | | `--processing-sound` | Sound played while assistant is processing | `sounds/processing.wav` |
| `--unmute-sound` | Sound played when unmuting the assistant | `sounds/mute_switch_off.flac` | | `--mute-sound` | Sound played when muting the assistant | `sounds/mute_switch_on.flac` |
| `--preferences-file` | Path to preferences JSON file | `preferences.json` | | `--unmute-sound` | Sound played when unmuting the assistant | `sounds/mute_switch_off.flac` |
| `--host` | IP-Address for ESPHome server, use 0.0.0.0 for all | Autodetected | | `--preferences-file` | Path to preferences JSON file | `preferences.json` |
| `--network-interface` | Network interface for ESPHome server | Autodetected | | `--host` | IP-Address for ESPHome server, use 0.0.0.0 for all | Autodetected |
| `--port` | Port for ESPHome server | 6053 | | `--network-interface` | Network interface for ESPHome server | Autodetected |
| `--enable-thinking-sound` | Enable thinking sound on startup | False | | `--port` | Port for ESPHome server | 6053 |
| `--debug` | Print DEBUG messages to console | False | | `--enable-thinking-sound` | Enable thinking sound on startup | False |
| `--output-only` | Enable output only mode | False | | `--debug` | Print DEBUG messages to console | False |
| `--output-only` | Enable output only mode | False |
💡 **Note:** There is a detailed explanation on the gain, noise suppression, and wake word sensitivity flags in the [audio options](docs/audio_options.md) file. 💡 **Note:** There is a detailed explanation on the gain, noise suppression, and wake word sensitivity flags in the [audio options](docs/audio_options.md) file.
## Build Information ## Build Information
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. 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.
@@ -104,6 +109,7 @@ The documentation for the build process can be found in the [GitHub Actions Work
### Code Quality Checks ### Code Quality Checks
The project uses the following tools to ensure code quality: The project uses the following tools to ensure code quality:
- **Black**: Code formatting (88 characters per line, PEP 8 compliant) - **Black**: Code formatting (88 characters per line, PEP 8 compliant)
- **isort**: Import sorting compatible with Black - **isort**: Import sorting compatible with Black
- **flake8**: Style and syntax checks - **flake8**: Style and syntax checks
@@ -114,7 +120,7 @@ The project uses the following tools to ensure code quality:
To use the development tools (linting, testing, etc.), you need to install the required dependencies: To use the development tools (linting, testing, etc.), you need to install the required dependencies:
``` sh ```sh
./script/setup --dev ./script/setup --dev
source .venv/bin/activate source .venv/bin/activate
``` ```
@@ -122,29 +128,33 @@ source .venv/bin/activate
### Linting Commands ### Linting Commands
#### Run all linting checks #### Run all linting checks
``` sh
```sh
./script/lint... ./script/lint...
``` ```
#### Individual linting commands (with auto-fix support) #### Individual linting commands (with auto-fix support)
| Script | Description | Auto-fix Available? |
|--------|-------------|---------------------| | Script | Description | Auto-fix Available? |
| `./script/lint_black` | Checks Python code formatting with Black | Yes, use `--auto` flag | | ------------------------ | ------------------------------------------ | ----------------------- |
| `./script/lint_flake8` | Runs style and syntax checks with flake8 | No | | `./script/lint_black` | Checks Python code formatting with Black | Yes, use`--auto` flag |
| `./script/lint_isort` | Checks import sorting with isort | Yes, use `--auto` flag | | `./script/lint_flake8` | Runs style and syntax checks with flake8 | No |
| `./script/lint_mypy` | Runs static type analysis with mypy | No | | `./script/lint_isort` | Checks import sorting with isort | Yes, use`--auto` flag |
| `./script/lint_pylint` | Runs code quality checks with pylint | Yes, use `--auto` flag | | `./script/lint_mypy` | Runs static type analysis with mypy | No |
| `./script/lint_pylint` | Runs code quality checks with pylint | Yes, use`--auto` flag |
#### Examples #### Examples
Run a specific lint check: Run a specific lint check:
``` sh
```sh
./script/lint_black ./script/lint_black
``` ```
Auto-fix formatting issues (Black + isort): Auto-fix formatting issues (Black + isort):
``` sh
```sh
./script/lint_black --auto ./script/lint_black --auto
./script/lint_isort --auto ./script/lint_isort --auto
``` ```
@@ -152,7 +162,8 @@ Auto-fix formatting issues (Black + isort):
### Testing ### Testing
Run the test suite: Run the test suite:
``` sh
```sh
./script/test ./script/test
``` ```