Add complete developer documentation with MkDocs

.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REQUIREMENTS: documentation/requirements.txt
+          CONFIG_FILE: documentation/mkdocs.yml

documentation/README.md

@@ -0,0 +1,51 @@
+# 🧠 Wyoming Documentation
+
+This is the complete documentation for the Wyoming protocol, its Python implementation, and ecosystem.
+
+Built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
+
+---
+
+## 📚 Documentation Index
+
+### 01 – Introduction
+- What is Wyoming?
+- Key Features
+- Supported Use Cases
+
+### 02 – Getting Started
+- Installation
+- Basic Examples
+- Requirements
+
+### 03 – Protocol Overview
+- Wyoming Message Format
+- JSON Headers + Audio Payload
+- Streaming Architecture
+
+### 04 – Wyoming Ecosystem
+- Compatible Services
+- Use in Home Assistant
+- Project Links
+
+### 05 – API Reference
+- [Event Types](05-api-reference/event-types.md)
+- [Timer Events](05-api-reference/timers.md)
+- [Python Modules](05-api-reference/modules.md)
+- [Flow Diagrams](05-api-reference/diagrams.md)
+
+### 06 – HTTP Integration
+- [HTTP Endpoints and Usage](06-http/README.md)
+
+### 07 – Example Projects
+- [Python Clients and Services](07-examples/README.md)
+
+### 08 – Advanced Deployment
+- [Docker, Service Discovery, Security](08-advanced/README.md)
+
+---
+
+## 🛠 Developer Docs
+- [Contributing Guide](CONTRIBUTING.md)
+- [Roadmap](ROADMAP.md)
+- [Appendix / Resources](APPENDIX.md)

documentation/docs/01-introduction/README.md

@@ -0,0 +1,60 @@
+# 🧠 Introduction to Wyoming
+
+Wyoming is a lightweight, streaming-focused protocol and library designed to connect the components of a privacy-respecting, locally-run voice assistant.
+
+Originally created for [Home Assistant's Year of the Voice](https://www.home-assistant.io/blog/2023/01/11/year-of-the-voice/), Wyoming allows voice interfaces to be built using modular services that speak a common protocol: JSON + optional binary payloads, sent peer-to-peer via TCP, Unix sockets or stdin/stdout.
+
+---
+
+## ✨ What is Wyoming?
+
+- 🧩 A **peer-to-peer event protocol** for audio-based services
+- 🔄 Messages consist of structured JSON and optional payloads (e.g. raw audio)
+- 📡 Supports **streaming** audio, TTS, wakeword, ASR, NLU, intent handling, and more
+- ⚙️ Runs over **TCP sockets, Unix sockets, or standard I/O**
+- 💡 Designed to be simple enough for implementation in any language
+
+---
+
+## 🎯 Why Was It Created?
+
+- Replace the legacy MQTT protocol from Snips AI
+- Simplify streaming communication between audio services
+- Allow seamless integration of different implementations (e.g. Whisper, Piper, Porcupine)
+- Work natively with Home Assistant and Rhasspy 3
+- Support multi-language, offline voice control without a cloud dependency
+
+---
+
+## 🧑‍💻 Who Is It For?
+
+- Developers of voice components (ASR, TTS, Wakeword, etc.)
+- Smart home users wanting to build offline, modular voice control
+- Integrators needing a privacy-friendly protocol
+- Researchers working on speech systems for underrepresented languages
+
+---
+
+## 🧭 Philosophy and Design Principles
+
+Wyoming was created to solve real-world pain points in building distributed, open voice assistants:
+
+| Principle              | Explanation |
+|------------------------|-------------|
+| 🔌 Modularity          | Every voice component is a standalone microservice |
+| 🔐 Privacy-by-design   | No cloud required, fully local deployment possible |
+| ⚡ Streaming-first      | No need to buffer entire recordings – supports real-time |
+| 🔄 Simple and hackable | Implementable in a few dozen lines per client/server |
+| 🌍 Language-neutral    | Not tied to English; supports multilingual systems |
+
+---
+
+## 🚀 Where is Wyoming Used?
+
+- 🏡 **Home Assistant Voice** (local TTS/ASR pipelines)
+- 🧠 **Rhasspy 3** (modular assistant architecture)
+- 🔊 **Piper TTS** add-on (used via Wyoming)
+- 🧪 Community ASR/TTS/Wakeword services (Whisper, Vosk, Porcupine, etc.)
+
+Wyoming is becoming a standard interface layer for open voice tooling – offering a flexible bridge between diverse services.
+

documentation/docs/02-architecture/README.md

@@ -0,0 +1,85 @@
+# 🏗️ Wyoming System Architecture
+
+Wyoming is designed to act as the connective tissue between small, modular services in a voice assistant system. These services communicate over simple socket-based connections using Wyoming events.
+
+---
+
+## 🧩 Component-Based Design
+
+A full voice assistant can be built from independent components:
+
+```
+[Mic] → [Wakeword] → [VAD] → [ASR] → [Intent] → [Handler] → [TTS] → [Speaker]
+```
+
+Each component runs independently, speaks the same protocol, and can be swapped out for another.
+
+---
+
+## 🔁 Example Event Flow
+
+Here’s a simplified interaction flow:
+
+1. **Wakeword** detection triggers a pipeline start
+2. **VAD** determines when user has stopped speaking
+3. **ASR** transcribes the audio stream into text
+4. **Intent recognizer** interprets the text into structured meaning
+5. **Handler** processes the command and returns a result
+6. **TTS** converts the result back to speech
+
+Each stage is loosely coupled, allowing fine-grained control, replacement, and scaling.
+
+---
+
+## 🌐 Communication Methods
+
+Wyoming supports multiple connection types:
+
+| Transport         | Use Case                             |
+|------------------|--------------------------------------|
+| TCP socket       | Multi-host communication             |
+| Unix socket      | Fast local communication             |
+| stdin/stdout     | Embedded component process piping    |
+
+All transports speak the exact same protocol format.
+
+---
+
+## 🧱 Microservice Separation
+
+Each voice function lives in its own process:
+
+| Component | Protocol Message Types |
+|----------|--------------------------|
+| Wakeword | `Detect`, `Detection`    |
+| ASR      | `Transcribe`, `Transcript` |
+| TTS      | `Synthesize`, `AudioChunk` |
+| Intent   | `Recognize`, `Intent`    |
+| Handle   | `Handled`, `NotHandled`  |
+
+Each service can:
+- Be implemented in any language
+- Run on separate machines
+- Be restarted/upgraded independently
+
+---
+
+## 🖧 Example Deployment
+
+```
+[ESP32 Mic] → Home Assistant Server
+              ├── wakeword: wyoming-openwakeword
+              ├── asr: wyoming-whisper
+              ├── tts: wyoming-piper
+              ├── handler: native Assist or custom
+              └── speaker: USB audio or Pi audio
+```
+
+Everything communicates through Wyoming socket connections.
+
+---
+
+## 🧪 Test Pipelines
+
+For development/testing, you can chain together services locally using Unix or TCP sockets, or embed components with subprocess pipes for easier control.
+

documentation/docs/03-protocol/README.md

@@ -0,0 +1,98 @@
+# 📜 Wyoming Protocol Specification
+
+Wyoming is a binary-safe event protocol optimized for streaming. Each message consists of:
+
+1. A single-line **JSON header**
+2. Optional binary **data** (e.g. structured config)
+3. Optional binary **payload** (e.g. audio stream)
+
+---
+
+## 🧱 Message Format
+
+```
+{ "type": "...", "data_length": ..., "payload_length": ... }\n
+<data bytes> (optional)
+<payload bytes> (optional)
+```
+
+- `type`: The event type (e.g. `audio-start`, `transcribe`)
+- `data_length`: Length in bytes of optional metadata (JSON)
+- `payload_length`: Length in bytes of binary payload
+
+---
+
+## 🗂️ Example: Audio Stream
+
+```json
+{ "type": "audio-chunk", "data_length": 0, "payload_length": 3200 }
+```
+
+Followed by 3200 bytes of PCM audio.
+
+---
+
+## 🎞️ Streaming Audio Flow (Mermaid)
+
+```mermaid
+sequenceDiagram
+    participant Mic
+    participant Wake
+    participant ASR
+    Mic->>Wake: AudioStart
+    Mic-->>Wake: AudioChunk (stream)
+    Wake-->>ASR: Detection (wakeword)
+    Mic->>ASR: AudioStart
+    Mic-->>ASR: AudioChunk (stream)
+    Mic->>ASR: AudioStop
+    ASR-->>Mic: Transcript
+```
+
+---
+
+## 📦 Message Lifecycle
+
+Each Wyoming component speaks the same protocol. Typical flows include:
+
+### ASR:
+
+- `Transcribe` → `AudioStart` + `AudioChunk` + `AudioStop` → `Transcript`
+
+### TTS:
+
+- `Synthesize` → `AudioStart` + `AudioChunk` + `AudioStop`
+
+### Wakeword:
+
+- `Detect` → `AudioChunk*` → `Detection` or `NotDetected`
+
+---
+
+## 🔄 Streaming vs One-Shot
+
+Unlike HTTP-based APIs, Wyoming supports **true streaming**:
+
+- Send audio while it’s being recorded
+- Receive results as they become available
+- Enables real-time voice interaction
+
+---
+
+## 🛑 Error Handling
+
+Errors are returned as `Error` events:
+
+```json
+{ "type": "error", "data": { "message": "Invalid audio format" } }
+```
+
+Clients should handle unknown types gracefully and support reconnecting to services.
+
+---
+
+## 🔄 Compatibility
+
+- All messages are newline-delimited JSON
+- Binary segments follow directly after header
+- Works across languages and platforms
+