> ## Documentation Index
> Fetch the complete documentation index at: https://daily-ms-pcc-self-hosted.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Smallest AI Text-to-Speech

> SmallestTTSService streams real-time TTS through Smallest AI's Waves WebSocket API with configurable voice parameters.

## Overview

Smallest AI provides real-time text-to-speech synthesis through a WebSocket-based integration with their Waves API. The service supports configurable voice parameters, multiple languages, and handles interruptions by reconnecting the WebSocket.

<CardGroup cols={2}>
  <Card title="Smallest AI TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.smallest.tts.html">
    Complete API reference for all parameters and methods
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-smallest.py">
    Complete example with WebSocket streaming
  </Card>
</CardGroup>

## Installation

```bash theme={null}
uv add "pipecat-ai[smallest]"
```

## Prerequisites

1. **Smallest AI Account**: Sign up at [Smallest AI](https://www.smallest.ai/)
2. **API Key**: Generate an API key from your account dashboard

Set the following environment variable:

```bash theme={null}
export SMALLEST_API_KEY=your_api_key
```

## Configuration

<ParamField path="api_key" type="str" required>
  Smallest AI API key for authentication.
</ParamField>

<ParamField path="base_url" type="str" default="wss://api.smallest.ai">
  Base WebSocket URL for the Smallest API. Override for custom or proxied
  deployments.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output audio sample rate in Hz. When `None`, uses the pipeline's configured
  sample rate.
</ParamField>

<ParamField path="output_format" type="str" default="pcm">
  Audio format returned by the API. One of `pcm`, `mp3`, `wav`, `ulaw`, `alaw`.
  Defaults to `pcm`, which is what Pipecat expects internally. Fixed at init
  time.
</ParamField>

<ParamField path="word_timestamps" type="bool" default="True">
  Whether to request per-word timing events. When `True`, the server interleaves
  word timestamp messages and the service emits aligned per-word `TTSTextFrame`s
  for downstream consumers (captions, lip-sync, RTVI). Supported on base-queue
  English and Hindi voices (`meher`, `devansh`, `kartik`, `maithili`, `liam`,
  `avery`); other voices silently emit no word events, so leaving this on is
  safe regardless of voice. Fixed at init time.
</ParamField>

<ParamField path="settings" type="SmallestTTSService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `SmallestTTSService.Settings(...)`. These can be updated mid-conversation with `TTSUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default              | Description                                                        |
| ---------- | ----------------- | -------------------- | ------------------------------------------------------------------ |
| `model`    | `str`             | `lightning_v3.1_pro` | Model identifier: `lightning_v3.1` or `lightning_v3.1_pro`.        |
| `voice`    | `str`             | `meher`              | Voice identifier. Default is `meher` for `lightning_v3.1_pro`.     |
| `language` | `Language \| str` | `Language.EN`        | Language code for synthesis.                                       |
| `speed`    | `float`           | `None`               | Speech speed multiplier (0.5–2.0). When `None`, uses API defaults. |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.smallest.tts import SmallestTTSService

tts = SmallestTTSService(
    api_key=os.getenv("SMALLEST_API_KEY"),
    settings=SmallestTTSService.Settings(
        voice="sophia",
    ),
)
```

### With Voice Customization

```python theme={null}
from pipecat.transcriptions.language import Language

tts = SmallestTTSService(
    api_key=os.getenv("SMALLEST_API_KEY"),
    settings=SmallestTTSService.Settings(
        voice="sophia",
        language=Language.ES,
        speed=1.2,
    ),
)
```

### Updating Settings at Runtime

Voice settings can be changed mid-conversation using `TTSUpdateSettingsFrame`:

```python theme={null}
from pipecat.frames.frames import TTSUpdateSettingsFrame
from pipecat.services.smallest.tts import SmallestTTSSettings

await worker.queue_frame(
    TTSUpdateSettingsFrame(
        delta=SmallestTTSSettings(
            voice="new_voice",
            speed=1.1,
        )
    )
)
```

## Notes

* **WebSocket streaming**: The service uses WebSocket connections for real-time streaming. The connection is automatically managed and will reconnect if interrupted.
* **Keepalive**: The service sends periodic keepalive messages (every 30 seconds) to prevent idle timeouts on the WebSocket connection.
* **Word timestamps**: When enabled (the default), word-level timing events are emitted as per-word `TTSTextFrame`s aligned to audio playback. Multiple TTS requests within a turn are automatically offset onto a continuous timeline. Supported on specific voices (`meher`, `devansh`, `kartik`, `maithili`, `liam`, `avery`); other voices produce no word events but function normally.
* **Language support**: Supports 31 languages including Arabic, Bengali, Chinese, Dutch, English, Finnish, French, German, Greek, Gujarati, Hindi, Indonesian, Italian, Japanese, Kannada, Korean, Malayalam, Malay, Marathi, Norwegian, Odia, Polish, Portuguese, Punjabi, Russian, Spanish, Swedish, Tamil, Telugu, Turkish, and Vietnamese.

## Event Handlers

Smallest AI TTS supports the standard [service connection events](/api-reference/server/events/service-events):

| Event                 | Description                          |
| --------------------- | ------------------------------------ |
| `on_connected`        | Connected to Smallest AI WebSocket   |
| `on_disconnected`     | Disconnected from Smallest WebSocket |
| `on_connection_error` | WebSocket connection error occurred  |

```python theme={null}
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Smallest AI")
```