satellite/docs/settings-cheatsheet.md

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:

--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:

--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:

--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:

--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:

--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	<plays> <delay_seconds>

Example:

--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)

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)

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)

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)

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
• Deployment Guide
• MQTT LED Integration