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

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