> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-source-analytics-user-turn-strategies.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Smallest AI

> Text-to-speech service using Smallest AI's WebSocket streaming API

## 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 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 multiple languages including Arabic, Bengali, German, English, Spanish, French, Gujarati, Hebrew, Hindi, Italian, Kannada, Marathi, Dutch, Polish, Russian, and Tamil.

## 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")
```