native first

docs/local-sidecar-protocol.md

@@ -0,0 +1,60 @@
+# Local ASR Sidecar Protocol
+
+Mastermind local-first mode expects speech-to-text to run as an external local
+streaming service. The app connects to the service over WebSocket and sends
+16 kHz mono PCM audio.
+
+## Default Endpoint
+
+```text
+ws://127.0.0.1:8765/v1/asr/stream
+```
+
+The endpoint is configurable in the Local AI settings.
+
+## Client Start Message
+
+After the WebSocket opens, the app sends a JSON start frame:
+
+```json
+{
+  "type": "start",
+  "sampleRate": 16000,
+  "channels": 1,
+  "encoding": "pcm_s16le",
+  "language": "en-US"
+}
+```
+
+After that, the app sends binary frames containing raw little-endian signed
+16-bit PCM audio at 16 kHz.
+
+## Sidecar Events
+
+The sidecar should send JSON text frames:
+
+```json
+{ "type": "ready" }
+```
+
+```json
+{ "type": "partial", "text": "intermediate transcript" }
+```
+
+```json
+{ "type": "final", "text": "final transcript" }
+```
+
+```json
+{ "type": "error", "error": "human-readable error" }
+```
+
+Only `final` transcript events are sent to the local LLM. `partial` events are
+shown as status text.
+
+## v1 Scope
+
+- STT target: English, `en-US`.
+- Sidecar implementation is external to this repository.
+- The app does not require a specific Nemotron, NeMo, Riva, or ONNX runtime as
+  long as the WebSocket protocol above is implemented.