v0.5: TCP STT client with PTT on/off, server endpoint in config + UI

2026-08-11 09:03:50 +00:00
parent 08d6eeb46e
commit 4a58b94f35
11 changed files with 696 additions and 53 deletions
@@ -0,0 +1,70 @@
+# Robovoice TCP STT Protocol
+
+## Overview
+
+Robovoice acts as a **client**: it connects to a remote STT server over TCP,
+sends control messages when the user presses/releases the PTT key, and
+receives transcript messages back. The STT server captures audio from a
+microphone, runs speech recognition (Moonshine), and sends transcripts back
+over the same connection.
+
+```
+[Robovoice client] --TCP--> [STT server :5210]
+     │                            │
+     ├── {"event":"on"}\n  ──────►│
+     │                            ├── capture audio
+     ├── {"event":"off"}\n ──────►│
+     │                            ├── run STT
+     │◄── {"final":true,...}\n ──┤
+```
+
+## Transport
+
+- **Protocol:** TCP (reliable, ordered, connection-oriented)
+- **Server endpoint:** configurable in Robovoice UI (default `127.0.0.1:5210`)
+- **Framing:** newline-delimited JSON (NDJSON) — each message is a single
+  UTF-8 JSON object terminated by `\n`
+- **Auto-reconnect:** if the connection drops, Robovoice retries every 3
+  seconds until the server is available
+
+## Control messages (client → server)
+
+Sent by Robovoice when the user presses/releases the PTT key.
+
+```json
+{"event": "on"}
+```
+
+```json
+{"event": "off"}
+```
+
+| Field   | Type   | Description                        |
+|---------|--------|------------------------------------|
+| `event` | string | `"on"` (PTT pressed) or `"off"` (PTT released) |
+
+## Transcript messages (server → client)
+
+Sent by the server back to Robovoice over the same TCP connection.
+
+```json
+{"final": false, "text": "hello world"}
+```
+
+```json
+{"final": true, "text": "hello world how are you"}
+```
+
+| Field   | Type    | Required | Description                                      |
+|---------|---------|----------|--------------------------------------------------|
+| `final` | bool    | yes      | `true` = final result, `false` = partial         |
+| `text`  | string  | yes      | The transcript text (may be empty for partials)  |
+
+### Semantics
+
+- **`final: false`** — intermediate recognition result (partial). Robovoice
+  logs these but does not act on them (only `final` triggers TTS).
+- **`final: true`** — complete utterance. Robovoice feeds this to the TTS
+  engine and speaks it.
+
+Malformed JSON or unknown field values are silently dropped by the client.