# 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.