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.

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:

1. Neuphonic Account: Sign up at Neuphonic
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

api_key · str · required

Neuphonic API key for authentication.

voice_id · str · default: "None" · deprecated

ID of the voice to use for synthesis.

Deprecated in v0.0.105. Use settings=NeuphonicTTSService.Settings(...) instead.

url · str · default: "wss://api.neuphonic.com"

WebSocket URL for the Neuphonic API.

sample_rate · int · default: "22050"

Output audio sample rate in Hz.

encoding · str · default: "pcm_linear"

Audio encoding format.

text_aggregation_mode · 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.

aggregate_sentences · bool · default: "None" · deprecated

Deprecated in v0.0.104. Use text_aggregation_mode instead.

params · InputParams · default: "None" · deprecated

Runtime-configurable voice and generation settings. See Settings below.

Deprecated in v0.0.105. Use settings=NeuphonicTTSService.Settings(...) instead.

settings · NeuphonicTTSService.Settings · default: "None"

Runtime-configurable settings. See Settings below.

NeuphonicHttpTTSService

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

api_key · str · required

Neuphonic API key for authentication.

voice_id · str · default: "None" · deprecated

ID of the voice to use for synthesis.

Deprecated in v0.0.105. Use settings=NeuphonicHttpTTSService.Settings(...) instead.

aiohttp_session · aiohttp.ClientSession · required

An aiohttp session for HTTP requests.

url · str · default: "https://api.neuphonic.com"

Base URL for the Neuphonic HTTP API.

sample_rate · int · default: "22050"

Output audio sample rate in Hz.

encoding · str · default: "pcm_linear"

Audio encoding format.

params · InputParams · default: "None" · deprecated

Runtime-configurable voice and generation settings. See Settings below.

Deprecated in v0.0.105. Use settings=NeuphonicHttpTTSService.Settings(...) instead.

settings · 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	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)

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)

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

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,
    )

The InputParams / params= pattern is deprecated as of v0.0.105. Use Settings / settings= instead. See the Service Settings guide for migration details.

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:

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