# Soniox

> Realtime multilingual speech-to-text with Soniox.

Source: https://polvallverdu.github.io/pipedog/docs/services/stt/soniox/



## Overview [#overview]

`SonioxSTTService` streams audio to Soniox's real-time WebSocket API, with endpoint detection, speaker diarization, language identification and context.

<Cards>
  <Card title="Upstream page" href="https://docs.pipecat.ai/api-reference/server/services/stt/soniox">
    Pipecat's documentation for the same service.
  </Card>

  <Card title="Source" href="https://github.com/polvallverdu/pipedog/tree/main/packages/soniox/src">
    `packages/soniox/src`.
  </Card>
</Cards>

## Installation [#installation]

```bash
bun add @pipedog/soniox
```

## Prerequisites [#prerequisites]

* A [Soniox](https://soniox.com) account and API key, passed as `apiKey` (the examples read `SONIOX_API_KEY`).

## SonioxSTTService [#sonioxsttservice]

### Configuration [#configuration]

| Option | Type | Required | Description |
|---|---|---|---|
| `apiKey` | `string` | yes | Soniox API key. |
| `url` | `string \| undefined` | no | Soniox WebSocket API URL. |
| `audioFormat` | `string \| undefined` | no | Audio format for transcription. Defaults to `"pcm_s16le"`. |
| `numChannels` | `number \| undefined` | no | Number of audio channels. Defaults to 1. |
| `vadForceTurnEndpoint` | `boolean \| undefined` | no | Controls turn detection mode. When true (pipedog mode, default): Soniox endpoint detection is disabled and a `VADUserStoppedSpeakingFrame` sends a finalize message to Soniox. When false (Soniox turn detection mode): Soniox endpoint detection is enabled and controls turn endings. Proposes a turn start on the local VAD signal when a VAD analyzer is configured (most responsive) or on the first transcript token otherwise, and a turn stop when the endpoint is detected. |
| `shouldInterrupt` | `boolean \| undefined` | no | Whether to interrupt the bot when the user starts speaking in Soniox turn detection mode (`vadForceTurnEndpoint: false`). Passed along to the user turn strategies this service recommends, which own the interruption; a user-supplied `userTurnStrategies` overrides the recommendation and this setting with it. Defaults to true. |
| `settings` | `STTSettings \| null \| undefined` | no | Runtime-updatable settings. |
| `name` | `string \| null \| undefined` | no | Custom name; defaults to `ClassName#count`. |
| `taskManager` | `BaseTaskManager \| null \| undefined` | no | Task manager for handling tasks. |
| `enableDirectMode` | `boolean \| undefined` | no | Process frames immediately instead of using internal queues. |
| `metrics` | `FrameProcessorMetrics \| null \| undefined` | no | Optional metrics collector for this processor. |
| `reconnectBackoffMinWait` | `number \| undefined` | no | Minimum time, in seconds, to wait between reconnection attempts. |
| `reconnectBackoffMaxWait` | `number \| undefined` | no | Maximum time, in seconds, to wait between reconnection attempts. |
| `wsCloseTimeout` | `number \| undefined` | no | Maximum time, in seconds, to wait for the peer to acknowledge the websocket closing handshake before dropping the connection. Applied to connections opened through `_websocketConnect()`. Increase it for peers that need longer to complete a graceful close. |
| `wsSendTimeout` | `number \| null \| undefined` | no | Maximum time, in seconds, a single send may wait on a peer that has stopped reading before the connection is dropped and the send throws `ConnectionClosedError`. Applied to connections opened through `_websocketConnect()`. Pass `null` to wait indefinitely. Defaults to `WS_SEND_TIMEOUT`. |
| `audioPassthrough` | `boolean \| undefined` | no | Whether to pass audio frames downstream after processing. Defaults to true. |
| `sampleRate` | `number \| null \| undefined` | no | The sample rate for audio input. If null, will be determined from the start frame. |
| `sttTtfbTimeout` | `number \| undefined` | no | Time in seconds to wait after VAD stop before reporting TTFB. This delay allows the final transcription to arrive. Defaults to 2.0. |
| `ttfsP99Latency` | `number \| null \| undefined` | no | P99 latency from speech end to final transcript in seconds. Broadcast via STTMetadataFrame at pipeline start. |
| `keepaliveTimeout` | `number \| null \| undefined` | no | Seconds of no audio before sending silence to keep the connection alive. null disables keepalive. |
| `keepaliveInterval` | `number \| undefined` | no | Seconds between idle checks when keepalive is enabled. |
| `reconnectOnError` | `boolean \| undefined` | no | Whether to automatically reconnect on websocket errors. Defaults to true. |

### Settings [#settings]

Runtime-updatable settings, passed as `settings: new SonioxSTTService.Settings({...})`. Settings you leave out keep their defaults.

| Setting                                                                       | Default       | Description                  |
| ----------------------------------------------------------------------------- | ------------- | ---------------------------- |
| `model`                                                                       | `"stt-rt-v5"` | Soniox model.                |
| `language`                                                                    |               | Language.                    |
| `languageHints`, `languageHintsStrict`                                        |               | Bias language detection.     |
| `context`                                                                     |               | A `SonioxContextObject`.     |
| `enableSpeakerDiarization`, `enableLanguageIdentification`                    |               | Diarization and language ID. |
| `maxEndpointDelayMs`, `endpointSensitivity`, `endpointLatencyAdjustmentLevel` |               | Endpointing.                 |
| `clientReferenceId`                                                           |               | Your own reference.          |

### Usage [#usage]

```ts title="stt.ts"
import { Language } from "@pipedog/core/transcriptions/language";
import { SonioxSTTService } from "@pipedog/soniox/stt";

const stt = new SonioxSTTService({
  apiKey: process.env.SONIOX_API_KEY ?? "",
  settings: new SonioxSTTService.Settings({ languageHints: [Language.EN, Language.ES] }),
});
```

### Notes [#notes]

* With `vadForceTurnEndpoint` (default), a VAD stop sends a finalize message.

## Runtimes [#runtimes]

| Runtime            | Works | What it needs |
| ------------------ | ----- | ------------- |
| Bun                | ✅ yes | Nothing.      |
| Node.js            | ✅ yes | Nothing.      |
| Deno               | ✅ yes | Nothing.      |
| Cloudflare Workers | ✅ yes | Nothing.      |

Generated from `pipecat.runtimes` and `pipecat.compat` in `packages/soniox/package.json`: ✅ means the compat smoke test passes on that runtime.

The service uses `fetch` and the global `WebSocket` (through core's `websocketConnect`, which sends the auth header on the handshake on Cloudflare Workers too). Pass no SDK; nothing is Node-only.