# Smallest AI with LiveKit

> Smallest AI in a LiveKit agent: through our plugin, or through LiveKit's Smallest AI plugin with changed URLs.

## With our plugin

Smallest AI’s Lightning voices with the settings of LiveKit’s Smallest AI plugin. `TTS`’s `sample_rate` is 8000, 16000, 24000 or 44100.

```shell
pip install livekit-plugins-tts-cache-router
```

**agent.py**

```python
from livekit.plugins import tts_cache_router as tcr

# The API key comes from TTS_CACHE_ROUTER_API_KEY.
tts = tcr.TTS(
    provider=tcr.SmallestAI(
        model="lightning_v3.1_pro",
        voice_id="meher",
        language="en",
    ),
)
```

Pass `tts` to `AgentSession(tts=tts)`. Set `TTS_CACHE_ROUTER_API_KEY` in the agent’s environment, and store your Smallest AI key under [Provider keys](https://ttscacherouter.dev/dashboard/provider-keys). `TTS`’s own arguments are on [the plugin’s page](https://docs.ttscacherouter.dev/livekit.md#tts).

### `tcr.SmallestAI(...)`

- `model` (`str`, Default `"lightning_v3.1_pro"`): `"lightning_v3.1_pro"` or `"lightning_v3.1"`.
- `voice_id` (`str | None`, Default `None`): A Smallest AI voice of `model`: each model has its own voices, and Smallest AI refuses another model’s. A cloned voice works with the model it was cloned for. `None` picks `meher` for `lightning_v3.1_pro` and `sophia` for `lightning_v3.1`, as LiveKit’s plugin does.
- `language` (`str`, Default `"en"`): The language of the text, e.g. `en` or `hi`, or `auto` for Smallest AI to detect it. The languages differ by model.
- `speed` (`float`, Default `1.0`): Speaking rate, 0.5–2.0.

Every accepted value, and the languages per model: [Models and options](https://docs.ttscacherouter.dev/reference/models.md#smallestai).

### Changing settings

Replies that start afterwards use the new settings:

```python
tts.update_options(language="hi", speed=1.1)
```

## With LiveKit's Smallest AI plugin

Keep `livekit-plugins-smallestai` and point it at the router: your router API key in place of your Smallest AI key, and the router’s address.

```shell
pip install livekit-plugins-smallestai
```

**agent.py**

```python
import os

from livekit.plugins import smallestai

tts = smallestai.TTS(
    model="lightning_v3.1_pro",
    voice_id="meher",
    language="en",
    api_key=os.environ["TTS_CACHE_ROUTER_API_KEY"],
    base_url="https://api.ttscacherouter.dev/smallestai/waves/v1",
    ws_url="wss://api.ttscacherouter.dev/smallestai/waves/v1/tts/live",
)
```

Set both URLs: `ws_url` for streaming, as an agent speaks, and `base_url` for `synthesize()`.

The router splits the reply into sentences and synthesizes each on its own: a sentence’s audio starts once the sentence is complete, and each sentence is a take of its own rather than a continuation of the one before. `use_continuations`, `max_buffer_delay_ms` and `max_buffer_flush_ms` change nothing, and `word_timestamps=True` gets no word timings. The other differences from Smallest AI’s own messages are on [Smallest AI API drop-in](https://docs.ttscacherouter.dev/clients/smallestai.md#websocket).

Requests, responses and errors keep Smallest AI’s own shape; the endpoints are on [Smallest AI API drop-in](https://docs.ttscacherouter.dev/clients/smallestai.md).

## Which to choose

Both use your org's cache and your stored provider key, and sound the same.

- **Our plugin** reports only the characters Smallest AI billed in `TTSMetrics` (cache hits count zero), and switches provider with `update_options`.
- **Smallest AI’s plugin** is the smallest change to an agent that already uses it. Its metrics count every character, cached or not; [Usage](https://docs.ttscacherouter.dev/dashboard.md#usage) has the real split.