tts

Deepgram Flux text-to-speech service implementation.

This module provides integration with Deepgram’s Flux TTS WebSocket API (/v2/speak), a streaming-first speech synthesis service designed for voice agents.

class pipecat.services.deepgram.flux.tts.DeepgramFluxTTSSettings(model: str | None | _NotGiven = <factory>, extra: dict[str, Any]=<factory>, voice: str | None | _NotGiven = <factory>, language: Language | str | None | _NotGiven = <factory>)[source]

Bases: TTSSettings

Settings for DeepgramFluxTTSService.

The Flux voice is a single flux-{voice}-{language} identifier (e.g. flux-alexis-en), carried by voice. Deepgram’s API passes it as its model query parameter, so model is kept in sync with voice and is not directly settable.

class pipecat.services.deepgram.flux.tts.DeepgramFluxTTSService(*, api_key: str, url: str = 'wss://api.deepgram.com/v2/speak', sample_rate: int | None = None, mip_opt_out: bool | None = None, tag: list[str] | None = None, text_aggregation_mode: TextAggregationMode = TextAggregationMode.TOKEN, settings: DeepgramFluxTTSSettings | None = None, **kwargs)[source]

Bases: InterruptibleTTSService

Deepgram Flux WebSocket text-to-speech service (early access).

Provides real-time speech synthesis using Deepgram’s Flux TTS API at wss://api.deepgram.com/v2/speak. LLM tokens are streamed to the server as Speak messages and each agent response is synthesized as a discrete turn ended by a Flush. Flux keeps acoustic state across turns on a single connection, so prosody and pacing stay consistent throughout a conversation.

By default, LLM tokens are streamed to Flux as they arrive (TextAggregationMode.TOKEN) — Flux is built to take raw LLM output and places synthesis boundaries internally, so buffering for sentence punctuation only adds latency. Pass text_aggregation_mode=TextAggregationMode.SENTENCE to aggregate text into sentences before synthesis instead.

Flux does not yet provide a message to cancel the active turn, so interruptions are handled by the InterruptibleTTSService behavior of reconnecting the websocket while the bot is speaking. A reconnect (interruption or the server’s one-hour session cap) resets Flux’s cross-turn prosody state, which is expected. Once Deepgram ships the planned Interrupt message, the base class can change to WebsocketTTSService and send it instead of reconnecting.

Flux TTS is early access: the voice catalog and parts of the protocol may change before general availability.

Event handlers:

  • on_connected: Called when the websocket connection is established.

  • on_disconnected: Called when the websocket connection is closed.

  • on_connection_error: Called when a websocket connection error occurs.

Example:

tts = DeepgramFluxTTSService(
    api_key=os.getenv("DEEPGRAM_API_KEY"),
    settings=DeepgramFluxTTSService.Settings(voice="flux-alexis-en"),
)
Settings

alias of DeepgramFluxTTSSettings

SUPPORTED_SAMPLE_RATES = (8000, 16000, 24000, 32000, 44100, 48000)
__init__(*, api_key: str, url: str = 'wss://api.deepgram.com/v2/speak', sample_rate: int | None = None, mip_opt_out: bool | None = None, tag: list[str] | None = None, text_aggregation_mode: TextAggregationMode = TextAggregationMode.TOKEN, settings: DeepgramFluxTTSSettings | None = None, **kwargs)[source]

Initialize the Deepgram Flux WebSocket TTS service.

Parameters:

  • api_key – Deepgram API key for authentication.

  • url – WebSocket URL for the Flux TTS API. Defaults to “wss://api.deepgram.com/v2/speak”.

  • sample_rate – Audio sample rate in Hz. If None, uses the pipeline default. Must be one of SUPPORTED_SAMPLE_RATES.

  • mip_opt_out – Opt out of the Deepgram Model Improvement Program. See https://dpgr.am/deepgram-mip for pricing impacts before setting to True.

  • tag – Tags to label requests for identification during usage reporting.

  • text_aggregation_mode – How to aggregate incoming text before synthesis. Defaults to TextAggregationMode.TOKEN, streaming LLM tokens straight to Flux for the lowest latency.

  • settings – Runtime-updatable settings.

  • **kwargs – Additional arguments passed to parent InterruptibleTTSService class.

Raises:

ValueError – If an explicit sample_rate is not supported.

can_generate_metrics() → bool[source]

Check if the service can generate metrics.

Returns:

True, as Deepgram Flux TTS supports metrics generation.

async start(frame: StartFrame)[source]

Start the Deepgram Flux TTS service.

Parameters:

frame – The start frame containing initialization parameters.

async flush_audio(context_id: str | None = None)[source]

Flush any pending audio synthesis by sending a Flush message.

This ends the active turn: the server generates any remaining audio and reports the turn’s SpeechMetadata.

async run_tts(text: str, context_id: str) → AsyncGenerator[Frame | None, None][source]

Generate speech from text using Deepgram’s Flux WebSocket TTS API.

Parameters:

  • text – The text to synthesize into speech.

  • context_id – The context ID for tracking audio frames.

Yields:

Frame – Audio frames containing the synthesized speech, plus start/stop frames.

async setup(setup: FrameProcessorSetup)

Set up the processor with required components.

Parameters:

setup – Configuration object containing setup parameters.