# Sarvam AI

> Text-to-speech for Indian languages: SarvamTTSService over WebSocket and SarvamHttpTTSService over HTTP.

Source: https://polvallverdu.github.io/pipedog/docs/services/tts/sarvam/



## Overview [#overview]

* **`SarvamTTSService`**: streams text over Sarvam's WebSocket and pushes audio as it arrives. Interruptions reconnect the socket.
* **`SarvamHttpTTSService`**: one HTTP request per sentence.

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

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

  <Card title="Sarvam docs" href="https://docs.sarvam.ai/api-reference-docs/text-to-speech/stream">
    The text-to-speech API reference.
  </Card>
</Cards>

## Installation [#installation]

```bash
bun add @pipedog/sarvam
```

```ts
import { SarvamHttpTTSService, SarvamTTSService } from "@pipedog/sarvam/tts";
```

## Prerequisites [#prerequisites]

* A Sarvam account and an API key from the [Sarvam dashboard](https://dashboard.sarvam.ai/).
* Pass the key as `apiKey`. The examples read it from `SARVAM_API_KEY`.

## Models [#models]

| Model                                   | Pitch and loudness | Temperature | Pace       | Sample rate         |
| --------------------------------------- | ------------------ | ----------- | ---------- | ------------------- |
| `bulbul:v3` (default), `bulbul:v3-beta` | ignored            | 0.01 to 1.0 | 0.5 to 2.0 | 24000 Hz by default |
| `bulbul:v4-flash`                       | supported          | ignored     | 0.5 to 2.0 | 24000 Hz by default |

`TTS_MODEL_CONFIGS` holds each model's speakers and limits, and `getSpeakersForModel(model)` lists
its speakers. Preprocessing is always on for these models. Settings a model doesn't support are
dropped or clamped when the service is constructed.

## SarvamTTSService [#sarvamttsservice]

### Configuration [#configuration]

| Option | Type | Required | Description |
|---|---|---|---|
| `apiKey` | `string` | yes | Sarvam API key for authenticating TTS requests. |
| `url` | `string \| undefined` | no | WebSocket URL for the TTS backend (default production URL). |
| `settings` | `SarvamTTSSettings \| 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. |
| `reconnectOnError` | `boolean \| undefined` | no | Whether to automatically reconnect on connection errors. |
| `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`. |
| `textAggregationMode` | `TextAggregationMode \| null \| undefined` | no | How to aggregate incoming text before synthesis. `TextAggregationMode.SENTENCE` (default) buffers until sentence boundaries, `TextAggregationMode.TOKEN` streams tokens directly for lower latency. |
| `pushTextFrames` | `boolean \| undefined` | no | Whether to push TextFrames and LLMFullResponseEndFrames. |
| `pushStopFrames` | `boolean \| undefined` | no | Whether to automatically push TTSStoppedFrames. |
| `pushStartFrame` | `boolean \| undefined` | no | Whether to automatically create audio contexts and push TTSStartedFrames. When true, the base class handles `createAudioContext` and yields `TTSStartedFrame` before each synthesis call, so `runTts` implementations do not need to. |
| `stopFrameTimeoutS` | `number \| undefined` | no | Idle time before pushing TTSStoppedFrame when pushStopFrames is true. |
| `pushSilenceAfterStop` | `boolean \| undefined` | no | Whether to push silence audio after TTSStoppedFrame. |
| `silenceTimeS` | `number \| undefined` | no | Duration of silence to push when pushSilenceAfterStop is true. |
| `pauseFrameProcessing` | `boolean \| undefined` | no | Whether to hold incoming frames after a turn until its audio contexts end. Needed by services whose audio doesn't carry its request's context ID. |
| `maxConsecutiveZeroAudioContexts` | `number \| undefined` | no | How many consecutive TTS contexts may complete without producing any audio before the service is reported unable to do its job. Catches a provider that accepts requests and stays silent — an unknown voice ID, say — which no error ever surfaces. Every silent context reports an error the service can carry on from, whatever the limit is; on reaching the limit the service reports a permanent error instead, stops being given work, and the pipeline worker applies its `ProcessorUnusablePolicy`. Set to 0 to report silent contexts without ever writing the service off. |
| `appendTrailingSpace` | `boolean \| undefined` | no | Whether to append a trailing space to text before sending to TTS. This helps prevent some TTS services from vocalizing trailing punctuation (e.g., "dot"). Only applied in sentence aggregation mode; when streaming tokens, the incoming text's own whitespace is preserved. |
| `sampleRate` | `number \| null \| undefined` | no | Output sample rate for generated audio. |
| `skipTextTypes` | `string[] \| null \| undefined` | no | List of text types that should not be spoken. |
| `textTransforms` | `[string, TextTransform][] \| null \| undefined` | no | A list of TextTransforms to transform text just before sending it to TTS. Each TextTransform takes the aggregated text and its type, and returns the transformed text. To register, provide a list of tuples of `[textType \| "*", transformFunction]`. |
| `transportDestination` | `string \| null \| undefined` | no | Destination for generated audio frames. |
| `reuseContextIdWithinTurn` | `boolean \| undefined` | no | Whether the service should reuse context IDs within the same turn. |
| `audioCache` | `TTSAudioCacheStore \| null \| undefined` | no | Where to keep synthesized audio for reuse (e.g. a shared `TTSAudioCache`). Text whose audio is in the cache is served from it, with no request to the provider. Lines get there through `warmAudioCache()`, and also from live synthesis when `cacheSynthesizedAudio` allows it. Only services that yield their audio from `runTts` (HTTP and streaming-RPC services, see `supportsAudioCache`) use it, and only in sentence aggregation mode. Defaults to null (no cache). pipedog only. |
| `cacheSynthesizedAudio` | `boolean \| ((text: string) => boolean) \| undefined` | no | Whether audio synthesized live is stored in `audioCache`, or a function that decides per text. Defaults to false: only warmed lines are stored, since a generated reply can repeat what the user said. pipedog only. |
| `audioCacheNamespace` | `string \| undefined` | no | Extra part of the cache key, for constructor options that change the audio but are not in `settings`. pipedog only. |

### Settings [#settings]

Runtime-updatable settings, passed as `settings: new SarvamTTSService.Settings({...})`
(`SarvamTTSSettings`). Any setting you leave out keeps the default below.

| Setting               | Type              | Default       | Description                                                         |
| --------------------- | ----------------- | ------------- | ------------------------------------------------------------------- |
| `model`               | `string`          | `"bulbul:v3"` | TTS model.                                                          |
| `voice`               | `string`          | `"shubh"`     | Speaker.                                                            |
| `language`            | `Language`        | `"en-IN"`     | Language of the text.                                               |
| `enablePreprocessing` | `boolean \| null` | `false`       | Text preprocessing. Always on for v3 and v4-flash.                  |
| `pace`                | `number \| null`  | `1.0`         | Speech pace, 0.5 to 2.0.                                            |
| `pitch`               | `number \| null`  | `null`        | Pitch (`bulbul:v4-flash`).                                          |
| `loudness`            | `number \| null`  | `null`        | Volume multiplier (`bulbul:v4-flash`).                              |
| `temperature`         | `number \| null`  | `null`        | Randomness, 0.01 to 1.0 (`bulbul:v3`; the server's default is 0.6). |
| `minBufferSize`       | `number \| null`  | `50`          | Characters to buffer before generating audio.                       |
| `maxChunkLength`      | `number \| null`  | `150`         | Largest chunk, in characters, processed at once.                    |

### Usage [#usage]

```ts title="tts.ts"
import { TTSUpdateSettingsFrame } from "@pipedog/core/frames/frames";
import { Language } from "@pipedog/core/transcriptions/language";
import { SarvamHttpTTSService, SarvamTTSService } from "@pipedog/sarvam/tts";

const tts = new SarvamTTSService({
  apiKey: process.env.SARVAM_API_KEY ?? "",
  settings: new SarvamTTSService.Settings({
    model: "bulbul:v3",
    voice: "shubh",
    language: Language.HI_IN,
  }),
});
```

Change settings mid-call with a `TTSUpdateSettingsFrame`:

```ts
// Queue it on the worker, or push it from a processor upstream of the service.
const update = new TTSUpdateSettingsFrame({
  delta: new SarvamTTSService.Settings({ pace: 1.2 }),
});
```

### Notes [#notes]

* The socket carries `config`, `text`, `flush` and `ping` messages. The API key and a `User-Agent` go in the handshake headers.
* `sampleRate` can be 8000, 16000, 22050 or 24000; `null` uses the model's default.

## SarvamHttpTTSService [#sarvamhttpttsservice]

### Configuration [#configuration-1]

| Option | Type | Required | Description |
|---|---|---|---|
| `apiKey` | `string` | yes | Sarvam AI API subscription key. |
| `baseUrl` | `string \| undefined` | no | Sarvam AI API base URL. Defaults to "https://api.sarvam.ai". |
| `fetch` | `{ (input: RequestInfo \| URL, init?: RequestInit): Promise<Response>; (input: string \| URL \| Request, init?: RequestInit): Promise<Response>; } \| null \| undefined` | no | `fetch` used for HTTP requests. Defaults to the global `fetch`. DIVERGENCE: upstream takes a shared `aiohttp_session`. |
| `settings` | `SarvamHttpTTSSettings \| 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. |
| `textAggregationMode` | `TextAggregationMode \| null \| undefined` | no | How to aggregate incoming text before synthesis. `TextAggregationMode.SENTENCE` (default) buffers until sentence boundaries, `TextAggregationMode.TOKEN` streams tokens directly for lower latency. |
| `pushTextFrames` | `boolean \| undefined` | no | Whether to push TextFrames and LLMFullResponseEndFrames. |
| `pushStopFrames` | `boolean \| undefined` | no | Whether to automatically push TTSStoppedFrames. |
| `pushStartFrame` | `boolean \| undefined` | no | Whether to automatically create audio contexts and push TTSStartedFrames. When true, the base class handles `createAudioContext` and yields `TTSStartedFrame` before each synthesis call, so `runTts` implementations do not need to. |
| `stopFrameTimeoutS` | `number \| undefined` | no | Idle time before pushing TTSStoppedFrame when pushStopFrames is true. |
| `pushSilenceAfterStop` | `boolean \| undefined` | no | Whether to push silence audio after TTSStoppedFrame. |
| `silenceTimeS` | `number \| undefined` | no | Duration of silence to push when pushSilenceAfterStop is true. |
| `pauseFrameProcessing` | `boolean \| undefined` | no | Whether to hold incoming frames after a turn until its audio contexts end. Needed by services whose audio doesn't carry its request's context ID. |
| `maxConsecutiveZeroAudioContexts` | `number \| undefined` | no | How many consecutive TTS contexts may complete without producing any audio before the service is reported unable to do its job. Catches a provider that accepts requests and stays silent — an unknown voice ID, say — which no error ever surfaces. Every silent context reports an error the service can carry on from, whatever the limit is; on reaching the limit the service reports a permanent error instead, stops being given work, and the pipeline worker applies its `ProcessorUnusablePolicy`. Set to 0 to report silent contexts without ever writing the service off. |
| `appendTrailingSpace` | `boolean \| undefined` | no | Whether to append a trailing space to text before sending to TTS. This helps prevent some TTS services from vocalizing trailing punctuation (e.g., "dot"). Only applied in sentence aggregation mode; when streaming tokens, the incoming text's own whitespace is preserved. |
| `sampleRate` | `number \| null \| undefined` | no | Output sample rate for generated audio. |
| `skipTextTypes` | `string[] \| null \| undefined` | no | List of text types that should not be spoken. |
| `textTransforms` | `[string, TextTransform][] \| null \| undefined` | no | A list of TextTransforms to transform text just before sending it to TTS. Each TextTransform takes the aggregated text and its type, and returns the transformed text. To register, provide a list of tuples of `[textType \| "*", transformFunction]`. |
| `transportDestination` | `string \| null \| undefined` | no | Destination for generated audio frames. |
| `reuseContextIdWithinTurn` | `boolean \| undefined` | no | Whether the service should reuse context IDs within the same turn. |
| `audioCache` | `TTSAudioCacheStore \| null \| undefined` | no | Where to keep synthesized audio for reuse (e.g. a shared `TTSAudioCache`). Text whose audio is in the cache is served from it, with no request to the provider. Lines get there through `warmAudioCache()`, and also from live synthesis when `cacheSynthesizedAudio` allows it. Only services that yield their audio from `runTts` (HTTP and streaming-RPC services, see `supportsAudioCache`) use it, and only in sentence aggregation mode. Defaults to null (no cache). pipedog only. |
| `cacheSynthesizedAudio` | `boolean \| ((text: string) => boolean) \| undefined` | no | Whether audio synthesized live is stored in `audioCache`, or a function that decides per text. Defaults to false: only warmed lines are stored, since a generated reply can repeat what the user said. pipedog only. |
| `audioCacheNamespace` | `string \| undefined` | no | Extra part of the cache key, for constructor options that change the audio but are not in `settings`. pipedog only. |

### Settings [#settings-1]

`settings: new SarvamHttpTTSService.Settings({...})` (`SarvamHttpTTSSettings`) takes the same
fields as above except `minBufferSize` and `maxChunkLength`, with the same defaults.

### Usage [#usage-1]

```ts
const http = new SarvamHttpTTSService({
  apiKey: process.env.SARVAM_API_KEY ?? "",
  settings: new SarvamHttpTTSService.Settings({ voice: "shubh", pace: 1.1 }),
});
```

### Notes [#notes-1]

* `fetch` replaces the global `fetch` (upstream takes an aiohttp session).
* `baseUrl` defaults to `https://api.sarvam.ai`. The WAV header of each reply is stripped before the audio is pushed.
* `sampleRate` can also be 32000, 44100 or 48000 for `bulbul:v3`.

| 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/sarvam/package.json`: ✅ means the compat smoke test passes on that runtime.

## Runtime notes [#runtime-notes]

* HTTP goes through `fetch` and the WebSocket through the core `websocketConnect`. Both work on Bun, Node, Deno and Cloudflare Workers.
* `bulbul:v2`, the `InputParams` class and the `model`, `voice_id`, `params` and `aggregate_sentences` constructor options are deprecated upstream and not ported.
* Tested against local servers, not against Sarvam itself.