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

# Neuphonic

> Text-to-speech service implementation using Neuphonic's API

## Overview

Neuphonic provides high-quality text-to-speech synthesis with two service implementations: `NeuphonicTTSService` (WebSocket-based) with real-time streaming and interruption support, and `NeuphonicHttpTTSService` (HTTP-based) with server-sent events. `NeuphonicTTSService` is recommended for interactive applications requiring low latency.

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

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

  <Card title="Neuphonic Documentation" icon="book" href="https://docs.neuphonic.com/api-reference/tts/websocket">
    Official Neuphonic TTS API documentation
  </Card>

  <Card title="Voice Library" icon="microphone" href="https://docs.neuphonic.com/">
    Browse available voices and features
  </Card>
</CardGroup>

## Installation

To use Neuphonic services, install the required dependencies:

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

## Prerequisites

### Neuphonic Account Setup

Before using Neuphonic TTS services, you need:

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

### Required Environment Variables

* `NEUPHONIC_API_KEY`: Your Neuphonic API key for authentication

## Configuration

### NeuphonicTTSService

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

<ParamField path="voice_id" type="str" default="None" deprecated>
  ID of the voice to use for synthesis.

  *Deprecated in v0.0.105. Use `settings=NeuphonicTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="url" type="str" default="wss://api.neuphonic.com">
  WebSocket URL for the Neuphonic API.
</ParamField>

<ParamField path="sample_rate" type="int" default="22050">
  Output audio sample rate in Hz.
</ParamField>

<ParamField path="encoding" type="str" default="pcm_linear">
  Audio encoding format.
</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>
  *Deprecated in v0.0.104.* Use `text_aggregation_mode` instead.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  Runtime-configurable voice and generation settings. See
  [InputParams](#inputparams) below.

  *Deprecated in v0.0.105. Use `settings=NeuphonicTTSService.Settings(...)` instead.*
</ParamField>

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

### NeuphonicHttpTTSService

The HTTP service uses SSE (server-sent events) for streaming audio.

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

<ParamField path="voice_id" type="str" default="None" deprecated>
  ID of the voice to use for synthesis.

  *Deprecated in v0.0.105. Use `settings=NeuphonicHttpTTSService.Settings(...)` instead.*
</ParamField>

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

<ParamField path="url" type="str" default="https://api.neuphonic.com">
  Base URL for the Neuphonic HTTP API.
</ParamField>

<ParamField path="sample_rate" type="int" default="22050">
  Output audio sample rate in Hz.
</ParamField>

<ParamField path="encoding" type="str" default="pcm_linear">
  Audio encoding format.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  Runtime-configurable voice and generation settings. See
  [InputParams](#inputparams) below.

  *Deprecated in v0.0.105. Use `settings=NeuphonicHttpTTSService.Settings(...)` instead.*
</ParamField>

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

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `NeuphonicTTSService.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.)* |
| `speed`    | `float`           | `NOT_GIVEN` | Speech rate control.                   |

## Usage

### Basic Setup (WebSocket)

```python theme={null}
from pipecat.services.neuphonic import NeuphonicTTSService

tts = NeuphonicTTSService(
    api_key=os.getenv("NEUPHONIC_API_KEY"),
    settings=NeuphonicTTSService.Settings(
        voice="your-voice-id",
    ),
)
```

### With Customization (WebSocket)

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

tts = NeuphonicTTSService(
    api_key=os.getenv("NEUPHONIC_API_KEY"),
    sample_rate=22050,
    settings=NeuphonicTTSService.Settings(
        voice="your-voice-id",
        language=Language.FR,
        speed=1.2,
    ),
)
```

### HTTP Service

```python theme={null}
import aiohttp
from pipecat.services.neuphonic import NeuphonicHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = NeuphonicHttpTTSService(
        api_key=os.getenv("NEUPHONIC_API_KEY"),
        settings=NeuphonicHttpTTSService.Settings(
            voice="your-voice-id",
        ),
        aiohttp_session=session,
    )
```

<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

* **WebSocket vs HTTP**: The WebSocket service (`NeuphonicTTSService`) supports interruption handling and keepalive connections, making it better for interactive conversations. The HTTP service (`NeuphonicHttpTTSService`) uses server-sent events and is simpler to integrate.
* **Keepalive**: The WebSocket service automatically sends keepalive messages every 10 seconds to maintain the connection.
* **Default sample rate**: Both services default to 22050 Hz, which differs from most other TTS services.

## Event Handlers

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

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

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