Metadata-Version: 2.4
Name: vad2mqtt
Version: 0.1.0a1
Summary: Voice Activity Detection to MQTT bridge using ovos-plugin-manager
Author-email: TigreGotico <opensource@tigregotico.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/TigreGotico/vad2mqtt
Project-URL: Issues, https://github.com/TigreGotico/vad2mqtt/issues
Keywords: vad,mqtt,home-assistant,ovos,openvoiceos,silero,voice-activity-detection,occupancy-detection,iot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Home Automation
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ovos-plugin-manager
Requires-Dist: ovos-vad-plugin-silero
Requires-Dist: paho-mqtt>=1.6
Requires-Dist: numpy
Requires-Dist: sounddevice
Dynamic: license-file

# vad2mqtt

> **Bring the entire OpenVoiceOS VAD ecosystem into Home Assistant as IoT sensors.**

`vad2mqtt` is a real-time Voice Activity Detection bridge built on
**ovos-plugin-manager**. It listens to any microphone, loads any OPM VAD
plugin, and publishes speech probability, noise level, and a speech-detected
binary sensor to MQTT — with full Home Assistant auto-discovery.

Because OPM plugins are interchangeable, **every current and future OVOS VAD
plugin instantly becomes a Home Assistant sensor** with zero code changes.
Install `ovos-vad-plugin-silero` today, swap to `ovos-vad-plugin-webrtcvad`
tomorrow, or drop in a community plugin next week — `vad2mqtt` adapts
automatically.

> **A complementary occupancy signal from the microphone you already own.**

## Why this exists — complementary occupancy detection

Most rooms already have a microphone (smart speakers, SBCs with a cheap USB
mic, intercom panels, old phones running Home Assistant Companion). A **Voice
Activity Detector** adds a privacy-respecting *complementary* occupancy signal
with zero extra hardware:

- **Complementary, not standalone.** VAD is one input among many (PIR, mmWave,
  door sensors, etc.). It feeds into a probabilistic occupancy estimator such
  as [Area Occupancy Detection](https://github.com/Hankanman/Area-Occupancy-Detection).
  Both the binary `Speech Detected` sensor and the continuous `Noise Level`
  sensor are useful inputs.
- **No audio ever leaves the device.** Only a 0–1 float (speech probability) and
  a dB value cross the wire. No transcription, no wake-word, no cloud.
- **Lightweight.** Silero VAD runs in ~1 ms per 30 ms frame on a Raspberry Pi.
  CPU usage is negligible.
- **Fills gaps PIR leaves behind.** PIR sensors need motion + heat. VAD catches
  presence when someone is sitting still at a desk or behind a PIR blind spot.
  It also *misses* people who are silent, which is why it must be fused with
  other sensors rather than used alone.

## What it does

1. **Real-time audio** — captures microphone input in small chunks (default 30 ms).
2. **OPM VAD plugin** — loads any `ovos-plugin-manager` VAD engine. Default is
   `ovos-vad-plugin-silero` (ONNX, lightweight).
3. **Speech probability** — publishes a 0.0–1.0 float every chunk.
4. **Noise level** — publishes RMS dB at a throttled interval.
5. **MQTT + Home Assistant** — 4 auto-discovered entities under one device.

## Quick start (Docker)

```bash
# PipeWire / PulseAudio host (most modern desktops)
vim docker-compose.yml   # set MQTT_HOST
docker compose up -d
```

```bash
# Pure ALSA host (e.g. Raspberry Pi)
# Uncomment the `devices:` line in docker-compose.yml and set ALSA_CARD
vim docker-compose.yml
docker compose up -d
```

## Quick start (pip)

```bash
pip install vad2mqtt
vad2mqtt
```

## Home Assistant entities (4 under one device)

| Entity | Type | Payload | Note |
|--------|------|---------|------|
| VAD Probability | sensor | `0.87` | 0.0–1.0, `state_class: measurement` |
| VAD Model | sensor | `ovos-vad-plugin-silero` | Static-ish, updates on startup |
| Noise Level | sensor | `-45.2` | dB, `device_class: sound_pressure` |
| Speech Detected | binary_sensor | `ON` / `OFF` | Derived from threshold |

## Configuration

All settings are environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `MQTT_HOST` | `localhost` | Broker host |
| `MQTT_PORT` | `1883` | Broker port |
| `MQTT_USER` | — | Auth user |
| `MQTT_PASSWORD` | — | Auth password |
| `MQTT_TOPIC_PREFIX` | `vad2mqtt` | Topic root |
| `SAMPLE_RATE` | `16000` | Audio sample rate |
| `SOUND_DEVICE` | — | `sounddevice` device index/name |
| `ALSA_CARD` | — | ALSA card string (for PipeWire/ALSA) |
| `VAD_PLUGIN_MODULE` | `ovos-vad-plugin-silero` | OPM plugin module name |
| `VAD_PLUGIN_CONFIG` | — | JSON extra config for plugin |
| `VAD_THRESHOLD` | `0.5` | Speech / silence cutoff |
| `HA_ENABLED` | `true` | Auto-discovery toggle |
| `DEVICE_NAME` | `vad2mqtt` | HA entity prefix |
| `DEVICE_ID` | `vad2mqtt_01` | HA device identifier |
| `PUBLISH_INTERVAL` | `0.5` | Min seconds between VAD publishes |
| `NOISE_LEVEL_INTERVAL` | `2.0` | Min seconds between noise publishes |
| `NOISE_LEVEL_DELTA` | `3.0` | dB jump that bypasses interval |
| `LOG_LEVEL` | `INFO` | Logging level |

## Switching VAD plugins — the OPM advantage

Because `vad2mqtt` uses `ovos-plugin-manager`, you can swap VAD engines with
a single environment variable. Every current and future OVOS VAD plugin is
supported:

```bash
# Silero VAD — best accuracy, ONNX, ~1 ms/frame on Pi (default)
pip install ovos-vad-plugin-silero
VAD_PLUGIN_MODULE=ovos-vad-plugin-silero

# WebRTC VAD — lighter, no ML model
pip install ovos-vad-plugin-webrtcvad
VAD_PLUGIN_MODULE=ovos-vad-plugin-webrtcvad

# Noise-based VAD — threshold-based, minimal CPU
pip install ovos-vad-plugin-noise
VAD_PLUGIN_MODULE=ovos-vad-plugin-noise

# Future community plugins — just install and point VAD_PLUGIN_MODULE at them
```

This is the power of the OVOS plugin ecosystem: new VAD research (new ONNX
models, new algorithms) ships as a plain pip package. `vad2mqtt` consumes it
immediately with zero code changes.

## Architecture

```
Mic ──► sounddevice ──► 30 ms chunks ──► OPM VAD Plugin
                                               │
                    ┌──────────────────────────┘
                    ▼
            MQTT ──► Home Assistant
            │
            ├── vad_probability (continuous)
            ├── noise_level (throttled)
            ├── model_name (startup)
            └── speech_detected (binary, derived)
```

## Related

- [ovos-plugin-manager](https://github.com/OpenVoiceOS/ovos-plugin-manager)
- [ovos-vad-plugin-silero](https://github.com/OpenVoiceOS/ovos-vad-plugin-silero)
- [shazam2mqtt](https://github.com/TigreGotico/shazam2mqtt) — music recognition bridge
