> ## 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.

# Rime

> Text-to-speech service implementations using Rime AI

## Overview

Rime AI provides two TTS service implementations: `RimeTTSService` (WebSocket-based) with word-level timing and interruption support, and `RimeHttpTTSService` (HTTP-based) for simpler use cases. `RimeTTSService` is recommended for real-time interactive applications.

<CardGroup cols={2}>
  <Card title="Rime TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.rime.tts.html">
    Pipecat's API methods for Rime TTS integration
  </Card>

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

  <Card title="Rime Documentation" icon="book" href="https://docs.rime.ai/api-reference/endpoint/websockets-json">
    Official Rime WebSocket and HTTP API documentation
  </Card>

  <Card title="Voice Models" icon="microphone" href="https://docs.rime.ai/">
    Explore available voice models and features
  </Card>
</CardGroup>

## Installation

To use Rime services, install the required dependencies:

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

## Prerequisites

### Rime Account Setup

Before using Rime TTS services, you need:

1. **Rime Account**: Sign up at [Rime AI](https://docs.rime.ai/)
2. **API Key**: Generate an API key from your account dashboard
3. **Voice Selection**: Choose from available voice models

### Required Environment Variables

* `RIME_API_KEY`: Your Rime API key for authentication

## Configuration

### RimeTTSService

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

<ParamField path="voice_id" type="str" required deprecated>
  ID of the voice to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=RimeTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="url" type="str" default="wss://users-ws.rime.ai/ws3">
  Rime WebSocket API endpoint.
</ParamField>

<ParamField path="model" type="str" default="arcana" deprecated>
  Model ID to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=RimeTTSService.Settings(model=...)` instead.*
</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="text_aggregation_mode" type="TextAggregationMode" default="TextAggregationMode.SENTENCE">
  Controls how incoming text is aggregated before synthesis. `SENTENCE`
  (default) buffers text until sentence boundaries, producing more natural
  speech. `TOKEN` streams tokens directly for lower latency. Import from
  `pipecat.services.tts_service`.
</ParamField>

<ParamField path="aggregate_sentences" type="bool" default="None">
  *Deprecated in v0.0.104.* Use `text_aggregation_mode` instead.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  *Deprecated in v0.0.105. Use `settings=RimeTTSService.Settings(...)` instead.*
</ParamField>

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

### RimeHttpTTSService

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

<ParamField path="voice_id" type="str" required deprecated>
  ID of the voice to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=RimeHttpTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  An aiohttp session for HTTP requests.
</ParamField>

<ParamField path="model" type="str" default="mistv2" deprecated>
  Model ID to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=RimeHttpTTSService.Settings(model=...)` instead.*
</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="params" type="InputParams" default="None" deprecated>
  *Deprecated in v0.0.105. Use `settings=RimeHttpTTSService.Settings(...)`
  instead.*
</ParamField>

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

### RimeNonJsonTTSService

A non-JSON WebSocket service for models like Arcana that use plain text messages.

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

<ParamField path="voice_id" type="str" required deprecated>
  ID of the voice to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=RimeNonJsonTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="url" type="str" default="wss://users.rime.ai/ws">
  Rime WebSocket API endpoint.
</ParamField>

<ParamField path="model" type="str" default="arcana" deprecated>
  Model ID to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=RimeNonJsonTTSService.Settings(model=...)` instead.*
</ParamField>

<ParamField path="audio_format" type="str" default="pcm">
  Audio output format.
</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="text_aggregation_mode" type="TextAggregationMode" default="TextAggregationMode.SENTENCE">
  Controls how incoming text is aggregated before synthesis. `SENTENCE`
  (default) buffers text until sentence boundaries. `TOKEN` streams tokens
  directly for lower latency. Import from `pipecat.services.tts_service`.
</ParamField>

<ParamField path="aggregate_sentences" type="bool" default="None" deprecated>
  *Deprecated in v0.0.104.* Use `text_aggregation_mode` instead.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  *Deprecated in v0.0.105. Use `settings=RimeNonJsonTTSService.Settings(...)`
  instead.*
</ParamField>

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

#### RimeTTSService Settings

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

| Parameter                  | Type              | Default     | Description                            |
| -------------------------- | ----------------- | ----------- | -------------------------------------- |
| `model`                    | `str`             | `None`      | Model identifier. *(Inherited.)*       |
| `voice`                    | `str`             | `None`      | Voice identifier. *(Inherited.)*       |
| `language`                 | `Language \| str` | `None`      | Language for synthesis. *(Inherited.)* |
| `segment`                  | `str`             | `NOT_GIVEN` | Segment type for synthesis.            |
| `speedAlpha`               | `float`           | `NOT_GIVEN` | Speed alpha parameter.                 |
| `reduceLatency`            | `bool`            | `NOT_GIVEN` | Whether to reduce latency.             |
| `pauseBetweenBrackets`     | `bool`            | `NOT_GIVEN` | Pause between brackets.                |
| `phonemizeBetweenBrackets` | `bool`            | `NOT_GIVEN` | Phonemize between brackets.            |
| `noTextNormalization`      | `bool`            | `NOT_GIVEN` | Disable text normalization.            |
| `saveOovs`                 | `bool`            | `NOT_GIVEN` | Save out-of-vocabulary words.          |
| `inlineSpeedAlpha`         | `str`             | `NOT_GIVEN` | Inline speed alpha.                    |
| `repetition_penalty`       | `float`           | `NOT_GIVEN` | Repetition penalty.                    |
| `temperature`              | `float`           | `NOT_GIVEN` | Temperature for sampling.              |
| `top_p`                    | `float`           | `NOT_GIVEN` | Top-p sampling parameter.              |

#### RimeNonJsonTTSService Settings

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

| Parameter            | Type              | Default     | Description                            |
| -------------------- | ----------------- | ----------- | -------------------------------------- |
| `model`              | `str`             | `None`      | Model identifier. *(Inherited.)*       |
| `voice`              | `str`             | `None`      | Voice identifier. *(Inherited.)*       |
| `language`           | `Language \| str` | `None`      | Language for synthesis. *(Inherited.)* |
| `segment`            | `str`             | `NOT_GIVEN` | Segment type for synthesis.            |
| `repetition_penalty` | `float`           | `NOT_GIVEN` | Repetition penalty.                    |
| `temperature`        | `float`           | `NOT_GIVEN` | Temperature for sampling.              |
| `top_p`              | `float`           | `NOT_GIVEN` | Top-p sampling parameter.              |

## Usage

### Basic Setup (WebSocket)

```python theme={null}
from pipecat.services.rime import RimeTTSService

tts = RimeTTSService(
    api_key=os.getenv("RIME_API_KEY"),
    settings=RimeTTSService.Settings(
        voice="cove",
    ),
)
```

### With Customization (WebSocket)

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

tts = RimeTTSService(
    api_key=os.getenv("RIME_API_KEY"),
    settings=RimeTTSService.Settings(
        voice="cove",
        model="mistv2",
        language=Language.ES,
        speedAlpha=1.2,
        reduceLatency=True,
    ),
)
```

### HTTP Service

```python theme={null}
import aiohttp
from pipecat.services.rime import RimeHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = RimeHttpTTSService(
        api_key=os.getenv("RIME_API_KEY"),
        settings=RimeHttpTTSService.Settings(
            voice="cove",
        ),
        aiohttp_session=session,
    )
```

### Non-JSON WebSocket (Arcana)

```python theme={null}
from pipecat.services.rime import RimeNonJsonTTSService

tts = RimeNonJsonTTSService(
    api_key=os.getenv("RIME_API_KEY"),
    settings=RimeNonJsonTTSService.Settings(
        voice="cove",
        model="arcana",
    ),
)
```

## Customizing Speech

`RimeTTSService` provides a set of helper methods for implementing Rime-specific customizations, meant to be used as part of text transformers. These include methods for spelling out text, adjusting speech rate, and modifying pitch. See the [Text Transformers for TTS](/pipecat/learn/text-to-speech#text-transformers-for-tts) section in the Text-to-Speech guide for usage examples.

### SPELL(text: str) -> str:

Implements [Rime's spell function](https://docs.rime.ai/api-reference/spell) to spell out text character by character.

```python theme={null}
# Text transformers for TTS
# This will insert Rime's spell tags around the provided text.
async def spell_out_text(text: str, type: str) -> str:
    return RimeTTSService.SPELL(text)

tts = RimeTTSService(
    api_key=os.getenv("RIME_API_KEY"),
    text_transforms=[
        ("phone_number", spell_out_text),
    ],
)
```

### PAUSE\_TAG(seconds: float) -> str:

Implements [Rime's custom pause functionality](https://docs.rime.ai/api-reference/custom-pauses) to generate a properly formatted pause tag you can insert into the text.

```python theme={null}
# Text transformers for TTS
# This will insert a one second pause after questions.
async def pause_after_questions(text: str, type: str) -> str:
    if text.endswith("?"):
        return f"{text}{RimeTTSService.PAUSE_TAG(1.0)}"
    return text

tts = RimeTTSService(
    api_key=os.getenv("RIME_API_KEY"),
    text_transforms=[
        ("sentence", pause_after_questions), # Only apply to sentence aggregations
    ],
)
```

### PRONOUNCE(self, text: str, word: str, phoneme: str) -> str:

Convenience method to support Rime's [custom pronunciations feature](https://docs.rime.ai/api-reference/custom-pronunciation). It takes a word and its desired phoneme representation, returning the text with the provided word replaced by the appropriate phoneme tag.

```python theme={null}
# Text transformers for TTS
# This will a phoneme in place of the word "potato" to define how it
# should be pronounced.
async def maybe_say_potato_all_fancylike(text: str, type: str) -> str:
    if using_fancy_voice:
        return RimeTTSService.PRONOUNCE(text, "potato", "potato")
    else:
        return RimeTTSService.PRONOUNCE(text, "potato", "poteto")

tts = RimeTTSService(
    api_key=os.getenv("RIME_API_KEY"),
    text_transforms=[
        ("*", maybe_say_potato_all_fancylike), # Apply to all text
    ],
)
```

### INLINE\_SPEED(self, text: str, speed: float) -> str:

A convenience method to support Rime's [inline speed adjustment feature](https://docs.rime.ai/api-reference/speed). It will wrap the provided text in the `[]` tags and add the provided speed to the `inlineSpeedAlpha` field in the request metadata.

```python theme={null}
# Text transformers for TTS
# This will make the word slow always be spoken more slowly.
async def slow_down_slow_words(text: str, type: str) -> str:
    return text.replace(
        "slow",
        RimeTTSService.INLINE_SPEED("slow", speed=0.5)
    )

tts = RimeTTSService(
    api_key=os.getenv("RIME_API_KEY"),
    text_transforms=[
        ("*", slow_down_slow_words), # Apply to all text
    ],
)
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Notes

* **Word-level timestamps**: `RimeTTSService` provides word-level timing information, enabling synchronized text highlighting.
* **WebSocket vs HTTP**: The WebSocket service supports word-level timestamps, interruption handling, and maintains context across messages within a turn. The HTTP service is simpler but lacks these features.
* **Non-JSON WebSocket**: `RimeNonJsonTTSService` is for models like Arcana that use plain text messages instead of JSON. It does not support word-level timestamps.

## Event Handlers

Rime WebSocket TTS services support the standard [service connection events](/api-reference/server/events/service-events):

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

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