Neuphonic Text-to-Speech

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.

Neuphonic TTS API Reference

Pipecat’s API methods for Neuphonic TTS integration

Example Implementation

Complete example with WebSocket streaming

Neuphonic Documentation

Official Neuphonic TTS API documentation

Voice Library

Browse available voices and features

Installation

To use Neuphonic services, install the required dependencies:

uv add "pipecat-ai[neuphonic]"

Prerequisites

Neuphonic Account Setup

Before using Neuphonic TTS services, you need:

Neuphonic Account: Sign up at Neuphonic
API Key: Generate an API key from your account dashboard
Voice Selection: Choose from available voice models

Required Environment Variables

NEUPHONIC_API_KEY: Your Neuphonic API key for authentication

Configuration

NeuphonicTTSService

str

required

Neuphonic API key for authentication.

str

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=NeuphonicTTSService.Settings(...) instead.

str

default:"wss://api.neuphonic.com"

WebSocket URL for the Neuphonic API.

int

default:"22050"

Output audio sample rate in Hz.

str

default:"pcm_linear"

Audio encoding format.

TextAggregationMode

default:"None"

Controls how incoming text is aggregated before synthesis. SENTENCE (used when None) buffers text until sentence boundaries, producing more natural speech. TOKEN streams tokens directly for lower latency. Import from pipecat.services.tts_service.

bool

default:"None"

deprecated

Deprecated since 0.0.104, removed in 2.0.0. Use text_aggregation_mode instead.

InputParams

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=NeuphonicTTSService.Settings(...) instead.

NeuphonicTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

NeuphonicHttpTTSService

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

str

required

Neuphonic API key for authentication.

str

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=NeuphonicHttpTTSService.Settings(...) instead.

aiohttp.ClientSession

required

An aiohttp session for HTTP requests.

str

default:"https://api.neuphonic.com"

Base URL for the Neuphonic HTTP API.

int

default:"22050"

Output audio sample rate in Hz.

str | None

default:"pcm_linear"

Audio encoding format.

InputParams

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=NeuphonicHttpTTSService.Settings(...) instead.

NeuphonicHttpTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

Settings

Runtime-configurable settings passed via the settings constructor argument using NeuphonicTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
`model`	`str`	`None`	Not sent by this service; reported only as the model name in metrics and traces. (Inherited.)
`voice`	`str`	`None`	Voice identifier. (Inherited.)
`language`	`Language \| str`	`Language.EN`	Language for synthesis. (Inherited.)
`speed`	`float`	`1.0`	Speech rate control.
`temperature`	`float \| None`	`None`	Randomness in synthesis (0.0–1.0). Left to Neuphonic’s default when unset.
`ipa_key`	`str \| None`	`None`	Regional variant (`es-castilian` or `pt-br`) whose sounds `<phoneme:...>` tags in the text are read with. Left to Neuphonic’s default when unset.

Usage

Basic Setup (WebSocket)

import os

from pipecat.services.neuphonic.tts import NeuphonicTTSService

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

With Customization (WebSocket)

from pipecat.services.neuphonic.tts 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

import aiohttp
from pipecat.services.neuphonic.tts 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,
    )

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.
Settings updates reconnect: NeuphonicTTSService disconnects and reconnects its WebSocket whenever a setting changes.
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:

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

@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Neuphonic")

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Neuphonic Text-to-Speech

Overview

Neuphonic TTS API Reference

Example Implementation

Neuphonic Documentation

Voice Library

Installation

Prerequisites

Neuphonic Account Setup

Required Environment Variables

Configuration

NeuphonicTTSService

NeuphonicHttpTTSService

Settings

Usage

Basic Setup (WebSocket)

With Customization (WebSocket)

HTTP Service

Notes

Event Handlers

​Overview

Neuphonic TTS API Reference

Example Implementation

Neuphonic Documentation

Voice Library

​Installation

​Prerequisites

​Neuphonic Account Setup

​Required Environment Variables

​Configuration

​NeuphonicTTSService

​NeuphonicHttpTTSService

​Settings

​Usage

​Basic Setup (WebSocket)

​With Customization (WebSocket)

​HTTP Service

​Notes

​Event Handlers

Overview

Installation

Prerequisites

Neuphonic Account Setup

Required Environment Variables

Configuration

NeuphonicTTSService

NeuphonicHttpTTSService

Settings

Usage

Basic Setup (WebSocket)

With Customization (WebSocket)

HTTP Service

Notes

Event Handlers