From 7cf672da84ec32b15943fe2fd2c4f463001d0f5d Mon Sep 17 00:00:00 2001 From: Alex X Date: Tue, 22 Apr 2025 14:19:40 +0300 Subject: [PATCH] Add readme for exec and wyoming modules --- internal/exec/README.md | 12 +++ internal/wyoming/README.md | 197 +++++++++++++++++++++++++++++++++++++ pkg/wyoming/README.md | 14 +++ 3 files changed, 223 insertions(+) create mode 100644 internal/exec/README.md create mode 100644 internal/wyoming/README.md create mode 100644 pkg/wyoming/README.md diff --git a/internal/exec/README.md b/internal/exec/README.md new file mode 100644 index 00000000..e15a9657 --- /dev/null +++ b/internal/exec/README.md @@ -0,0 +1,12 @@ +## Backchannel + +- You can check audio card names in the **Go2rtc > WebUI > Add** +- You can specify multiple backchannel lines with different codecs + +```yaml +sources: + two_way_audio_win: + - exec:ffmpeg -hide_banner -f dshow -i "audio=Microphone (High Definition Audio Device)" -c pcm_s16le -ar 16000 -ac 1 -f wav - + - exec:ffplay -nodisp -probesize 32 -f s16le -ar 16000 -#backchannel=1#audio=s16le/16000 + - exec:ffplay -nodisp -probesize 32 -f alaw -ar 8000 -#backchannel=1#audio=alaw/8000 +``` diff --git a/internal/wyoming/README.md b/internal/wyoming/README.md new file mode 100644 index 00000000..445af2c8 --- /dev/null +++ b/internal/wyoming/README.md @@ -0,0 +1,197 @@ +# Wyoming + +This module provide [Wyoming Protocol](https://www.home-assistant.io/integrations/wyoming/) support to create local voice assistants using [Home Assistant](https://www.home-assistant.io/). + +- go2rtc can act as [Wyoming Satellite](https://github.com/rhasspy/wyoming-satellite) +- go2rtc can act as [Wyoming External Microphone](https://github.com/rhasspy/wyoming-mic-external) +- go2rtc can act as [Wyoming External Sound](https://github.com/rhasspy/wyoming-snd-external) +- any supported audio source with PCM codec can be used as audio input +- any supported two-way audio source with PCM codec can be used as audio output +- any desktop/server microphone/speaker can be used as two-way audio source + - supported any OS via FFmpeg or any similar software + - supported Linux via alsa source + +## Typical Voice Pipeline + +1. Audio stream (MIC) + - any audio source with PCM codec support (include PCMA/PCMU) +2. Voice Activity Detector (VAD) +3. Wake Word (WAKE) + - [OpenWakeWord](https://www.home-assistant.io/voice_control/create_wake_word/) +4. Speech-to-Text (STT) + - [Whisper](https://github.com/home-assistant/addons/blob/master/whisper/README.md) + - [Vosk](https://github.com/rhasspy/hassio-addons/blob/master/vosk/README.md) +5. Conversation agent (INTENT) + - [Home Assistant](https://www.home-assistant.io/integrations/conversation/) +6. Text-to-speech (TTS) + - [Google Translate](https://www.home-assistant.io/integrations/google_translate/) + - [Piper](https://github.com/home-assistant/addons/blob/master/piper/README.md) +7. Audio stream (SND) + - any source with two-way audio (backchannel) and PCM codec support (include PCMA/PCMU) + +You can use a large number of different projects for WAKE, STT, INTENT and TTS thanks to the Home Assistant. + +And you can use a large number of different technologies for MIC and SND thanks to Go2rtc. + +## Configuration + +You can optionally specify WAKE service. So go2rtc will start transmitting audio to Home Assistant only after WAKE word. If the WAKE service cannot be connected to or not specified - go2rtc will pass all audio to Home Assistant. In this case WAKE service must be configured in your Voice Assistant pipeline. + +You can optionally specify VAD threshold. So go2rtc will start transmitting audio to WAKE service only after some audio noise. + +Your stream must support audio transmission in PCM codec (include PCMA/PCMU). + +```yaml +wyoming: + stream_name_from_streams_section: + listen: :10700 + name: "My Satellite" # optional name + wake_uri: tcp://192.168.1.23:10400 # optional WAKE service + vad_threshold: 1 # optional VAD threshold (from 0.1 to 3.5) +``` + +Home Assistant -> Settings -> Integrations -> Add -> Wyoming Protocol -> Host + Port from `go2rtc.yaml` + +Select one or multiple wake words: +```yaml +wake_uri: tcp://192.168.1.23:10400?name=alexa_v0.1&name=hey_jarvis_v0.1&name=hey_mycroft_v0.1&name=hey_rhasspy_v0.1&name=ok_nabu_v0.1 +``` + +## Config examples + +Satellite on Windows server using FFmpeg and FFplay. + +```yaml +streams: + satellite_win: + - exec:ffmpeg -hide_banner -f dshow -i "audio=Microphone (High Definition Audio Device)" -c pcm_s16le -ar 16000 -ac 1 -f wav - + - exec:ffplay -hide_banner -nodisp -probesize 32 -f s16le -ar 22050 -#backchannel=1#audio=s16le/22050 + +wyoming: + satellite_win: + listen: :10700 + name: "Windows Satellite" + wake_uri: tcp://192.168.1.23:10400 + vad_threshold: 1 +``` + +Satellite on Dahua camera with two-way audio support. + +```yaml +streams: + dahua_camera: + - rtsp://admin:password@192.168.1.123/cam/realmonitor?channel=1&subtype=1&unicast=true&proto=Onvif + +wyoming: + dahua_camera: + listen: :10700 + name: "Dahua Satellite" + wake_uri: tcp://192.168.1.23:10400 + vad_threshold: 1 +``` + +Satellite on Dahua camera with two-way audio support. + +```yaml +streams: + wyoming_external: + - wyoming://192.168.1.23:10600 # wyoming-mic-external + - wyoming://192.168.1.23:10601?backchannel=1 # wyoming-snd-external + +wyoming: + wyoming_external: + listen: :10700 + name: "Wyoming Satellite" + wake_uri: tcp://192.168.1.23:10400 + vad_threshold: 1 +``` + +## Wyoming External Microphone and Sound + +Advanced users, who want to enjoy the [Wyoming Satellite](https://github.com/rhasspy/wyoming-satellite) project, can use go2rtc as a [Wyoming External Microphone](https://github.com/rhasspy/wyoming-mic-external) or [Wyoming External Sound](https://github.com/rhasspy/wyoming-snd-external). + +**go2rtc.yaml** + +```yaml +streams: + wyoming_mic_external: + - exec:ffmpeg -hide_banner -f dshow -i "audio=Microphone (High Definition Audio Device)" -c pcm_s16le -ar 16000 -ac 1 -f wav - + wyoming_snd_external: + - exec:ffplay -hide_banner -nodisp -probesize 32 -f s16le -ar 22050 -#backchannel=1#audio=s16le/22050 + +wyoming: + wyoming_mic_external: + listen: :10600 + mode: mic + wyoming_snd_external: + listen: :10601 + mode: snd +``` + +**docker-compose.yml** + +```yaml +version: "3.8" +services: + satellite: + build: wyoming-satellite # https://github.com/rhasspy/wyoming-satellite + ports: + - "10700:10700" + command: + - "--name" + - "my satellite" + - "--mic-uri" + - "tcp://192.168.1.23:10600" + - "--snd-uri" + - "tcp://192.168.1.23:10601" + - "--debug" +``` + +## Wyoming External Source + +**go2rtc.yaml** + +```yaml +streams: + wyoming_external: + - wyoming://192.168.1.23:10600 + - wyoming://192.168.1.23:10601?backchannel=1 +``` + +**docker-compose.yml** + +```yaml +version: "3.8" +services: + microphone: + build: wyoming-mic-external # https://github.com/rhasspy/wyoming-mic-external + ports: + - "10600:10600" + devices: + - /dev/snd:/dev/snd + group_add: + - audio + command: + - "--device" + - "sysdefault" + - "--debug" + playback: + build: wyoming-snd-external # https://github.com/rhasspy/wyoming-snd-external + ports: + - "10601:10601" + devices: + - /dev/snd:/dev/snd + group_add: + - audio + command: + - "--device" + - "sysdefault" + - "--debug" +``` + +## Debug + +```yaml +log: + wyoming: trace +``` diff --git a/pkg/wyoming/README.md b/pkg/wyoming/README.md new file mode 100644 index 00000000..ff17d079 --- /dev/null +++ b/pkg/wyoming/README.md @@ -0,0 +1,14 @@ +## Default wake words + +- alexa_v0.1 +- hey_jarvis_v0.1 +- hey_mycroft_v0.1 +- hey_rhasspy_v0.1 +- ok_nabu_v0.1 + +## Useful Links + +- https://github.com/rhasspy/wyoming-satellite +- https://github.com/rhasspy/wyoming-openwakeword +- https://github.com/fwartner/home-assistant-wakewords-collection +- https://github.com/esphome/micro-wake-word-models/tree/main?tab=readme-ov-file