# Gladia

> Realtime multilingual speech-to-text with Gladia.

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



## Overview [#overview]

`GladiaSTTService` opens a Gladia live session over HTTP (`POST /v2/live`), then streams base64 audio over the returned WebSocket, with code-switching, translation, custom vocabulary and realtime processing options (see `@pipedog/gladia/config`).

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

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

## Installation [#installation]

```bash
bun add @pipedog/gladia
```

## Prerequisites [#prerequisites]

* A [Gladia](https://www.gladia.io) account and API key, passed as `apiKey` (the examples read `GLADIA_API_KEY`).

## GladiaSTTService [#gladiasttservice]

### Configuration [#configuration]

| Option | Type | Required | Description |
|---|---|---|---|
| `apiKey` | `string` | yes | Gladia API key for authentication. |
| `region` | `"eu-west" \| "us-west" \| null \| undefined` | no | Region used to process audio. eu-west or us-west. Defaults to eu-west. |
| `url` | `string \| undefined` | no | Gladia API URL. Defaults to "https://api.gladia.io/v2/live". |
| `encoding` | `string \| undefined` | no | Audio encoding format. Defaults to `"wav/pcm"`. |
| `bitDepth` | `number \| undefined` | no | Audio bit depth. Defaults to 16. |
| `channels` | `number \| undefined` | no | Number of audio channels. Defaults to 1. |
| `maxBufferSize` | `number \| undefined` | no | Maximum size of audio buffer in bytes. Defaults to 20MB. |
| `shouldInterrupt` | `boolean \| undefined` | no | Determine whether the bot should be interrupted when Gladia VAD detects user speech. 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` | `GladiaSTTSettings \| null \| undefined` | no | Runtime-updatable settings. |
| `fetch` | `((input: RequestInfo \| URL, init?: RequestInit) => Promise<Response>) \| undefined` | no | `fetch` used for the session init request. Defaults to the global one. |
| `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 GladiaSTTService.Settings({...})`. Settings you leave out keep their defaults.

| Setting                                                 | Default       | Description                                   |
| ------------------------------------------------------- | ------------- | --------------------------------------------- |
| `model`                                                 | `"solaria-1"` | Gladia model.                                 |
| `language`                                              |               | Single language.                              |
| `languageConfig`                                        |               | `LanguageConfig` (languages, code switching). |
| `endpointing`                                           |               | Endpointing, in seconds.                      |
| `maximumDurationWithoutEndpointing`                     | `5`           | Seconds.                                      |
| `preProcessing`, `realtimeProcessing`, `messagesConfig` |               | Config classes from `@pipedog/gladia/config`. |
| `enableVad`                                             |               | Gladia-side VAD.                              |
| `customMetadata`                                        |               | Metadata attached to the session.             |

### Usage [#usage]

```ts title="stt.ts"
import { LanguageConfig } from "@pipedog/gladia/config";
import { GladiaSTTService } from "@pipedog/gladia/stt";

const stt = new GladiaSTTService({
  apiKey: process.env.GLADIA_API_KEY ?? "",
  region: "eu-west",
  settings: new GladiaSTTService.Settings({
    languageConfig: new LanguageConfig({ languages: ["en", "fr"], codeSwitching: true }),
  }),
});
```

### Notes [#notes]

* `region` is `"us-west"` or `"eu-west"`. Pass `fetch` to customize the session request.

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