> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SILMA Text-to-Speech

> SilmaTTSService streams Arabic and English speech from SILMA AI's low-latency WebSocket API.

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="silma-ai" maintainerUrl="https://github.com/silma-ai" repo="https://github.com/silma-ai/pipecat-silma" />

## Overview

`SilmaTTSService` provides low-latency real-time text-to-speech Pipecat integration via a WebSocket API.
It streams audio from [SILMA TTS](https://silma.ai/) over a WebSocket you can
play through any Pipecat transport.

SILMA selects the language by **model** rather than by a language parameter:

* `silma-tts-v2-english` — English
* `silma-tts-v2-msa` — Modern Standard Arabic
* `silma-tts-v2-ksa` — Arabic in the Saudi (Najdi) dialect

For an updated list of languages, please visit [SILMA AI Products](https://silma.ai/products)

Pick a preset voice, or a voice you have cloned in your SILMA account.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/silma-ai/pipecat-silma">
    Package source, the foundational example, and issue tracker
  </Card>

  <Card title="PyPI Package" icon="cube" href="https://pypi.org/project/pipecat-silma/">
    The `pipecat-silma` package on PyPI
  </Card>

  <Card title="SILMA AI" icon="book" href="https://silma.ai/">
    Product overview, voices, and the TTS playground
  </Card>

  <Card title="API Keys" icon="key" href="https://app.silma.ai/api-keys">
    Create and manage your SILMA API keys
  </Card>
</CardGroup>

## Installation

Install the community package. It is published separately from `pipecat-ai`:

```bash theme={null}
uv add pipecat-silma
```

## Prerequisites

### Account and API key

1. Create an account at [SILMA App](https://app.silma.ai/)
2. Copy an API key from [API Keys](https://app.silma.ai/api-keys)

Set it in the environment:

```bash theme={null}
export SILMA_API_KEY="..."
```

## Configuration

<ParamField path="api_key" type="str" default="None">
  SILMA API key. If omitted, the service reads `SILMA_API_KEY`.
</ParamField>

<ParamField path="settings" type="SilmaTTSService.Settings" default="None">
  Model, voice, and prosody. See [Settings](#settings). Every field is also
  available as a direct constructor argument.
</ParamField>

<ParamField path="base_url" type="str" default="https://api.silma.ai/tts/v2">
  Override this only for a non-production SILMA endpoint. The WebSocket URL is
  derived from it, so `http://` becomes `ws://` for a local mock server.
</ParamField>

<ParamField path="keepalive_interval_s" type="float" default="20.0">
  How often to ping an idle connection, in seconds. It has to stay comfortably
  inside the read timeout of whatever proxy fronts the API — lower it if yours
  is shorter than the default assumes. Getting it wrong is not fatal: the next
  utterance reopens the socket, at the cost of a reconnect on its first word.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  SILMA renders 24 kHz audio and takes no sample-rate parameter, so the service
  pins its rate at `24000`. Leave this unset; passing anything other than
  `24000` raises `ValueError` rather than mislabelling the audio. Let the output
  transport resample if it needs a different rate.
</ParamField>

### Settings

Pass these through `SilmaTTSService.Settings(...)`. They can also be updated
while the pipeline is running, with `TTSUpdateSettingsFrame`.

| Parameter                               | Type       | Default              | Description                                                                              |
| --------------------------------------- | ---------- | -------------------- | ---------------------------------------------------------------------------------------- |
| `model`                                 | `str`      | `"silma-tts-v2-msa"` | Model id, which also selects the language.                                               |
| `voice`                                 | `str`      | `"sarah"`            | Preset voice id. See the table below.                                                    |
| `language`                              | `Language` | `None`               | Convenience: sets `model` to the one that speaks it. `EN`, `AR`, and `AR_SA` are mapped. |
| `creativity`                            | `float`    | `None`               | Variance in speech prosody 0-1. Left to SILMA's default when unset.                      |
| `speed`                                 | `float`    | `None`               | Speaking rate 0-1. Left to SILMA's default when unset.                                   |
| `user_id`                               | `str`      | `None`               | Your SILMA user id. Required for cloned voices and pronunciation overrides.              |
| `custom_audio_id`                       | `str`      | `None`               | Cloned voice id, e.g. `voice_1769817467123`. Requires `user_id`.                         |
| `enable_server_pronunciation_overrides` | `bool`     | `False`              | Apply the pronunciation overrides configured on your account. Requires `user_id`.        |

`creativity` and `speed` are omitted from the request entirely unless you set
them, so SILMA's own defaults apply.

### Models and voices

| Model                  | Language                      | Voices                                                                     |
| ---------------------- | ----------------------------- | -------------------------------------------------------------------------- |
| `silma-tts-v2-english` | English                       | `james`, `emma`                                                            |
| `silma-tts-v2-msa`     | Modern Standard Arabic        | `sarah`, `salma`, `salwa`, `saja`, `sultan`, `salman`, `sulaiman`, `salim` |
| `silma-tts-v2-ksa`     | Arabic, Saudi (Najdi) dialect | same as MSA                                                                |

<Note>
  Voice catalogs and model coverage can change. See
  [app.silma.ai](https://app.silma.ai) or [API specification](https://dev.silma.ai/) for the current list.
</Note>

## Usage

```python theme={null}
import os

from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.worker import PipelineParams, PipelineWorker
from pipecat_silma import SilmaTTSService

tts = SilmaTTSService(
    api_key=os.getenv("SILMA_API_KEY"),
    settings=SilmaTTSService.Settings(
        model="silma-tts-v2-msa",
        voice="sarah",
    ),
)

pipeline = Pipeline(
    [
        transport.input(),
        stt,
        user_aggregator,
        llm,
        tts,
        transport.output(),
        assistant_aggregator,
    ]
)

worker = PipelineWorker(
    pipeline,
    params=PipelineParams(enable_metrics=True, enable_usage_metrics=True),
)
```

To speak English instead of Arabic, change the model and pick an English voice:

```python theme={null}
tts = SilmaTTSService(
    settings=SilmaTTSService.Settings(
        model="silma-tts-v2-english",
        voice="emma",
    ),
)
```

## Pronunciation hints

SILMA reads phone numbers, email addresses and links correctly when they are
tagged in the text:

```
You can reach us on <STAG_PN>92005455</STAG_PN> or at <STAG_EMAIL>hi@silma.ai</STAG_EMAIL>.
```

The API caps a request at 250 characters, so the service splits longer text on
word boundaries and sends it as sequential requests over the same socket. The
splitter keeps these tags intact, so a tag is never cut in half across two
requests. Instruct your LLM to emit them — the
[foundational example](https://github.com/silma-ai/pipecat-silma/blob/main/examples/foundational.py)
shows how.

Account-level pronunciation overrides configured at
[app.silma.ai/control](https://app.silma.ai/control) apply when you pass both
`user_id` and `enable_server_pronunciation_overrides=True`.

## Cloned voices

Upload a voice under **Custom Voices** at
[app.silma.ai/voices](https://app.silma.ai/voices), then pass its id together
with your user id:

```python theme={null}
tts = SilmaTTSService(
    settings=SilmaTTSService.Settings(
        model="silma-tts-v2-ksa",
        voice="sarah",
        user_id="...",
        custom_audio_id="voice_1769817467123",
    ),
)
```

A cloned voice overrides the preset, so the `voice` you pair it with does not
matter.

## Interruptions

`SilmaTTSService` extends `InterruptibleTTSService`. SILMA's protocol has no
cancel message, so speech is stopped by dropping the socket and reconnecting —
which the service does without blocking the frame that clears buffered audio, so
a barge-in takes effect immediately rather than after the teardown completes.

## Compatibility

Tested with Pipecat 1.8.1 (`pipecat-ai>=1.8.1`), on Python 3.11 and later.