diff --git a/docs/README.md b/docs/README.md index eeaee06..4952773 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ | Document | Description | |----------|-------------| +| [**Settings Cheat Sheet**](settings-cheatsheet.md) | All CLI flags and options | | [**Architecture**](architecture/overview.md) | How Wyoming Satellite works | | [**VAD/Wake Integration**](integration/vad-wakeword.md) | Technical integration guide | | [**MQTT LED Control**](integration/mqtt-led.md) | LED control with Home Assistant | diff --git a/docs/settings-cheatsheet.md b/docs/settings-cheatsheet.md new file mode 100644 index 0000000..f1139b0 --- /dev/null +++ b/docs/settings-cheatsheet.md @@ -0,0 +1,242 @@ +# Wyoming Satellite — Settings Cheat Sheet + +Quick reference for all CLI flags and settings. + +--- + +## 🎤 Microphone (`--mic-*`) + +| Flag | Default | Description | +|------|---------|-------------| +| `--mic-uri` | — | Wyoming microphone service URI (`tcp://ip:port`) | +| `--mic-command` | — | Command for microphone input (`arecord ...`) | +| `--mic-command-rate` | 16000 | Sample rate (Hz) | +| `--mic-command-width` | 2 | Sample width (bytes) | +| `--mic-command-channels` | 1 | Channels (1=mono) | +| `--mic-command-samples-per-chunk` | 1024 | Samples per read | +| `--mic-volume-multiplier` | 1.0 | Volume multiplier | +| `--mic-noise-suppression` | 0 | Noise suppression (0-4) | +| `--mic-auto-gain` | 0 | Auto gain (0-31 dbFS) | +| `--mic-channel-index` | None | Channel index to use | +| `--mic-seconds-to-mute-after-awake-wav` | 0.5 | Mute after awake WAV | +| `--mic-no-mute-during-awake-wav` | false | Don't mute during awake WAV | + +**Example:** +```bash +--mic-command 'arecord -D plughw:CARD=Array,DEV=0 -r 16000 -c 1 -f S16_LE -t raw' \ +--mic-noise-suppression 2 \ +--mic-auto-gain 5 +``` + +--- + +## 🔊 Sound Output (`--snd-*`) + +| Flag | Default | Description | +|------|---------|-------------| +| `--snd-uri` | — | Wyoming sound service URI | +| `--snd-command` | — | Command for sound output (`aplay ...`) | +| `--snd-command-rate` | 22050 | Sample rate (Hz) | +| `--snd-command-width` | 2 | Sample width (bytes) | +| `--snd-command-channels` | 1 | Channels | +| `--snd-volume-multiplier` | 1.0 | Volume multiplier | +| `--awake-wav` | — | WAV played after wake word | +| `--done-wav` | — | WAV played after command | + +**Example:** +```bash +--snd-command 'aplay -D plughw:CARD=Array,DEV=0 -r 22050 -c 1 -f S16_LE -t raw' \ +--awake-wav /home/sirmrak/projects/Satellite/sounds/awake.wav +``` + +--- + +## 🎯 Wake Word (`--wake-*`) + +| Flag | Default | Description | +|------|---------|-------------| +| `--wake-uri` | — | Wyoming wake word service URI | +| `--wake-command` | — | Local wake word command | +| `--wake-word-name` | — | Wake word phrase (can be repeated) | +| `--wake-refractory-seconds` | 5.0 | Delay between detections | + +**Example:** +```bash +--wake-uri tcp://127.0.0.1:10400 \ +--wake-word-name "привет дроид" \ +--wake-word-name "привет придурок" +``` + +--- + +## 🎤 Voice Activity Detection (`--vad*`) + +| Flag | Default | Description | +|------|---------|-------------| +| `--vad` | false | Enable VAD | +| `--vad-system` | silero | `silero` or `webrtc` | +| `--vad-threshold` | 0.5 | Threshold (0-1) | +| `--vad-trigger-level` | 1 | Chunks to activate | +| `--vad-energy-threshold` | None | Energy for webrtc (int16) | +| `--vad-buffer-seconds` | 2.0 | Pre-roll buffer (seconds) | +| `--vad-wake-word-timeout` | 5.0 | Wake word timeout | + +**Example:** +```bash +--vad \ +--vad-system webrtc \ +--vad-threshold 0.5 \ +--vad-energy-threshold 200 \ +--vad-trigger-level 5 +``` + +--- + +## 📡 Event Service (`--event-uri`, `--*-command`) + +| Flag | Event | +|------|-------| +| `--event-uri` | Wyoming event service URI | +| `--startup-command` | Satellite started | +| `--streaming-start-command` | Streaming started | +| `--streaming-stop-command` | Streaming stopped | +| `--detect-command` | Wake detection started | +| `--detection-command` | Wake word detected | +| `--tts-played-command` | Audio played | +| `--transcript-command` | STT transcript | +| `--stt-start-command` | STT started | +| `--stt-stop-command` | STT stopped | +| `--synthesize-command` | TTS text received | +| `--tts-start-command` | TTS started | +| `--tts-stop-command` | TTS stopped | +| `--error-command` | Error occurred | +| `--connected-command` | Connected to server | +| `--disconnected-command` | Disconnected from server | + +**Example:** +```bash +--event-uri tcp://127.0.0.1:10500 \ +--detection-command 'examples/commands/detection.sh' \ +--transcript-command 'examples/commands/transcript.sh' \ +--tts-start-command 'notify-send "TTS started"' +``` + +--- + +## ⏱️ Timers (`--timer-*`) + +| Flag | Default | Description | +|------|---------|-------------| +| `--timer-started-command` | — | Timer started | +| `--timer-updated-command` | — | Timer paused/resumed/changed | +| `--timer-cancelled-command` | — | Timer cancelled | +| `--timer-finished-command` | — | Timer finished | +| `--timer-finished-wav` | — | WAV file to play | +| `--timer-finished-wav-repeat` | `1 0` | ` ` | + +**Example:** +```bash +--timer-finished-wav /path/to/timer.wav \ +--timer-finished-wav-repeat 3 1.0 +``` + +--- + +## 🛰️ Satellite (`--uri`, `--name`, `--area`) + +| Flag | Default | Description | +|------|---------|-------------| +| `--uri` | **required** | Satellite URI (`tcp://0.0.0.0:10700`) | +| `--name` | Wyoming Satellite | Satellite name | +| `--area` | — | Area name (for Home Assistant) | + +--- + +## 🔧 Debug & Discovery (`--debug*`, `--zeroconf*`) + +| Flag | Default | Description | +|------|---------|-------------| +| `--debug` | false | Enable DEBUG logging | +| `--debug-recording-dir` | None | Directory for audio recording | +| `--no-zeroconf` | false | Disable Zeroconf discovery | +| `--zeroconf-name` | MAC address | Name for Zeroconf | +| `--zeroconf-host` | Auto | Host for Zeroconf | +| `--log-format` | BASIC | Log format string | + +--- + +## 📊 Operating Modes + +### Mode 1: Always Streaming (no VAD, no wake) + +```bash +python3 -m wyoming_satellite \ + --name 'my-satellite' \ + --uri 'tcp://0.0.0.0:10700' \ + --mic-command 'arecord -r 16000 -c 1 -f S16_LE -t raw' \ + --snd-command 'aplay -r 22050 -c 1 -f S16_LE -t raw' +``` + +**Use case:** Lowest latency, always streaming to HA. + +--- + +### Mode 2: VAD Streaming (stream after speech detected) + +```bash +python3 -m wyoming_satellite \ + --name 'my-satellite' \ + --uri 'tcp://0.0.0.0:10700' \ + --mic-command 'arecord -r 16000 -c 1 -f S16_LE -t raw' \ + --snd-command 'aplay -r 22050 -c 1 -f S16_LE -t raw' \ + --vad \ + --vad-system webrtc \ + --vad-threshold 0.5 \ + --vad-energy-threshold 200 +``` + +**Use case:** Privacy-focused, stream only when speaking. + +--- + +### Mode 3: Wake Streaming (local wake word detection) + +```bash +python3 -m wyoming_satellite \ + --name 'my-satellite' \ + --uri 'tcp://0.0.0.0:10700' \ + --mic-command 'arecord -r 16000 -c 1 -f S16_LE -t raw' \ + --snd-command 'aplay -r 22050 -c 1 -f S16_LE -t raw' \ + --wake-uri tcp://127.0.0.1:10400 \ + --wake-word-name "привет дроид" \ + --wake-word-name "привет придурок" +``` + +**Use case:** "Hey Google" style, full local wake word. + +--- + +### Mode 4: With Event Service (LED, MQTT, notifications) + +```bash +python3 -m wyoming_satellite \ + --name 'my-satellite' \ + --uri 'tcp://0.0.0.0:10700' \ + --mic-command 'arecord -r 16000 -c 1 -f S16_LE -t raw' \ + --snd-command 'aplay -r 22050 -c 1 -f S16_LE -t raw' \ + --wake-uri tcp://127.0.0.1:10400 \ + --wake-word-name "привет дроид" \ + --event-uri tcp://127.0.0.1:10500 \ + --detection-command 'examples/commands/detection.sh' \ + --transcript-command 'examples/commands/transcript.sh' +``` + +**Use case:** Full integration with LED, MQTT, external scripts. + +--- + +## 🔗 Related + +- [Architecture Overview](architecture/overview.md) +- [Deployment Guide](../../DEPLOY.md) +- [MQTT LED Integration](integration/mqtt-led.md) diff --git a/examples/websocket-service/client.html b/examples/websocket-service/client.html index be7d0f2..5020678 100644 --- a/examples/websocket-service/client.html +++ b/examples/websocket-service/client.html @@ -64,14 +64,94 @@

🛰️ Wyoming Satellite WebSocket

Connecting...
- +
+ + +
+ + +