# Local speech

Canonical: https://suzo.app/docs/local-speech

The optional Suzo speech helper connects your service to TTS and STT engines. It runs on macOS, Windows, or Linux with Node.js 22.13+. Model runtimes have their own hardware and language requirements.

## Three connections

The helper makes an outbound HTTPS/WSS connection to Suzo, and connects to your TTS and STT API bases. It needs no public listening port and does not need direct access to the agent process.

Speech models may run on the helper computer or another reachable machine. Plain HTTP model endpoints are accepted only on loopback; other endpoints need HTTPS, including LAN and Tailscale. `localhost` means the helper’s computer.

<figure class="docs-flow" role="img" aria-label="The speech helper makes an outbound HTTPS or WSS connection to Suzo and separate API connections to TTS and STT endpoints. It has no direct connection to the task agent and needs no public listening port.">
<div class="docs-flow-node docs-flow-node-suzo"><strong>Suzo service</strong><span>Relays call audio</span></div>
<div class="docs-flow-edge"><span>Helper opens<br/>HTTPS/WSS</span><b aria-hidden="true">←</b></div>
<div class="docs-flow-node"><strong>Speech helper</strong><span>No public listener</span></div>
<div class="docs-flow-edge"><span>Endpoint APIs</span><b aria-hidden="true">→</b></div>
<div class="docs-flow-endpoints"><div class="docs-flow-node"><strong>TTS</strong><span>Text → audio</span></div><div class="docs-flow-node"><strong>STT</strong><span>Audio → text</span></div></div>
</figure>

## Use the setup wizard

In the agent’s **Voice → Local speech → Set up manually** guide, copy the contact-specific command. Download [the setup client](https://api.suzo.app/setup/client.mjs) from the hosted API, or `/setup/client.mjs` from your own trusted Suzo service and run:

```sh
node suzo-connect.mjs --speech --agent <contact-id>
```

The wizard reuses that agent’s private connection file. On another computer it asks for the existing file’s path; no new agent pairing is required. It asks for endpoint, model, voice, and audio settings, accepts hidden key entry, installs the supplied helper, and offers to start it.

Leave the helper running during calls. Installing an operating-system service or a third-party model runtime is a separate action. Never pass secrets as command arguments or put them in chat.

## TTS endpoint contract

Use an OpenAI-compatible API base, usually ending in `/v1`. The helper appends `/audio/speech` and sends:

```json
{
  "model":"<your-model-id>",
  "input":"Text to speak",
  "voice":"<your-voice-id>",
  "response_format":"pcm",
  "stream":true
}
```

Return streaming raw signed 16-bit little-endian mono PCM as `audio/pcm`, `audio/raw`, or `application/octet-stream`. The configured sample rate must match, between 8 and 48 kHz; the helper converts playback to 24 kHz. WAV, MP3, and JSON synthesis responses are rejected.

## STT endpoint contract

The helper POSTs multipart form data to `/audio/transcriptions`: a 16 kHz mono WAV `file`, a `model`, and optional `language`. Return:

```json
{"text":"Recognized speech"}
```

TTS and STT may share a base or use separate ones. Optional endpoint keys use bearer authentication and remain in private helper configuration. A compatible model name alone is insufficient; the serving runtime must implement these request and audio formats.

## Verify before choosing

Once the helper is online, audition a voice in Suzo, then explicitly choose **Use [voice]**. Setup and auditions never ring the phone automatically or silently change the contact’s provider.

The optional built-in CPU engines are English Kokoro TTS and Whisper STT with `tiny`, `base`, or `small`. They download models only when explicitly selected. Endpoint configuration has no preferred model family. Compare quality and measured latency for the intended language and hardware.

The [complete local speech guide](https://api.suzo.app/setup/local) includes private configuration examples, external endpoint adapters, installation, benchmarks, audio transport, and limits. Audio is relayed through Suzo; this is not end-to-end encryption.