OHF-Voice/wyoming

Wyoming Protocol – a lightweight, open‑source wire‑format for voice‑assistant components

What it is – A tiny TCP‑based protocol that shuttles JSON‑lines control messages together with raw PCM audio. It lets a Home Assistant server talk to separate programs that handle microphone input, wake‑word detection, speech‑to‑text, text‑to‑speech, intent parsing, etc.

Why it matters – By standardising the message layout (a one‑line JSON header followed by optional UTF‑8 data and a binary payload) every component can be swapped out without rewriting integration code. The protocol is deliberately unauthenticated and unencrypted, so it is only safe on a trusted local network – exactly the environment most smart‑home hubs run in.

Key concepts

• Header – type, optional data, and length fields (data_length, payload_length).
• Payload – Usually PCM audio, but any binary blob is allowed.
• Event flow – Clients send a describe request, receive an info response describing available services, optionally pick a program with select-program, then exchange domain‑specific events (transcribe, synthesize, detect, …).

Main event families

• Audio – audio-start/stop and audio-chunk to stream raw audio.
• Speech‑to‑text – transcribe → transcript (or streaming transcript‑start/chunk/stop).
• Text‑to‑speech – synthesize → audio stream (or streaming synthesize‑start/chunk/stop).
• Wake‑word – detect → detection / not-detected.
• Intent handling – recognize → intent (or intents‑start/stop for multiple intents) and handled/not‑handled for execution results.
• Satellite control – events for remote voice‑satellite devices (run‑satellite, run‑pipeline, etc.).

How it’s used – Home Assistant includes a built‑in integration (wyoming) that talks to separate programs (e.g. wyoming‑faster‑whisper for ASR, wyoming‑piper for TTS). Each of those programs implements the same protocol, making it easy to mix‑and‑match models and back‑ends.

Security note – No encryption or auth; keep it behind your LAN or inside a container network. The repo links to a SECURITY.md that explains the threat model.

Related projects – The README lists a collection of companion implementations (mic, VAD, Whisper, Piper, etc.) that all speak Wyoming.

Bottom line – Wyoming is an open‑standard, low‑overhead protocol that enables modular, interchangeable voice‑assistant services in Home Assistant and similar ecosystems.