# Contribute a TTS extension (/en/ai/reference/ten-agent/create-tts-extension)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

This guide explains how a TTS extension fits into a voice agent graph and how to choose an implementation path for a vendor text-to-speech service.

In a voice agent graph, a TTS extension receives generated text and streams synthesized audio to downstream RTC, playback, or audio-processing extensions.

## What a TTS extension does [#what-a-tts-extension-does]

The TTS Extension is a **standard extension building block** in the TEN Framework ecosystem, designed specifically for text-to-speech functionality.

### Core responsibilities [#core-responsibilities]

The TTS Extension is mainly responsible for:

1. **Receiving text**: Continuously receiving text from upstream extensions that needs to be turned into speech, usually from an LLM.
2. **Real-time synthesis**: Converting the text into an audio stream in real time.
3. **Sending audio**: Passing the synthesized audio to downstream extensions for further processing.

### Position in the Conversation Flow [#position-in-the-conversation-flow]

As a standard building block, the TTS Extension plays the key role of converting text into audio inside a voice agent conversation flow:

```json
[Upstream Extension]  ──text stream──>  [TTS Extension]  ──audio stream──>  [Downstream Extension]
```

**Typical upstream extensions**:

* **LLM Extension**: Generates reply text.
* **Translation Extension**: Produces translated text.
* **Text Processing Extension**: Outputs preprocessed text.

**Typical downstream extensions**:

* **RTC Extension**: Pushes audio into an RTC channel.
* **Audio Playback Extension**: Plays audio locally.
* **Audio Processing Extension**: Applies post-processing such as mixing or effects.

## Implementation modes [#implementation-modes]

TTS implementations usually fall into two categories: [HTTP mode](#http-mode) and [WebSocket mode](#websocket-mode). Most TTS vendors support one or both of these. Some vendors also provide SDKs, but the underlying behavior is still usually HTTP or WebSocket, so choose the implementation path based on how the SDK actually works.

HTTP is the more basic implementation approach. If this is your first TTS Extension, it is recommended to start with the [HTTP mode](#http-mode), and then move on to the more advanced [WebSocket mode](#websocket-mode).

### HTTP mode [#http-mode]

Use HTTP mode when the vendor API accepts text requests and returns synthesized audio data through request-response calls. This is usually the simplest path for a first TTS extension.

### WebSocket mode [#websocket-mode]

Use WebSocket mode when the vendor API streams synthesis results incrementally or requires a long-lived session. This path is better for low-latency streaming, but it usually needs more client lifecycle and reconnection handling.

### Architecture overview [#architecture-overview]

Two base classes are available today for developers: `AsyncTTS2BaseExtension` and `AsyncTTS2HttpExtension`. Inheriting from these classes makes TTS Extension implementation much easier.

### Basic implementation paths [#basic-implementation-paths]

**Path 1: Inherit directly from `AsyncTTS2BaseExtension` (WebSocket mode)**

```text
┌─────────────────────────────────────────────────────────────┐
│                    AsyncTTS2BaseExtension                  │
│  [Generic base class] Provides TTS Extension infrastructure│
│  - Message queue management                                │
│  - Lifecycle management                                    │
│  - Audio data sending                                      │
│  - Metrics reporting                                       │
│  - Error handling                                          │
└─────────────────────────────────────────────────────────────┘
                              ↑ Inheritance (Path 1)
┌─────────────────────────────────────────────────────────────┐
│        VendorTTSExtension (WebSocket/SDK subclass)         │
│  [Subclass implementation] Vendor-specific logic           │
│  - Full request_tts() implementation                       │
│  - WebSocket/SDK client implementation                     │
│  - Config class implementation                             │
│  - Vendor metadata                                         │
│  - Sample rate configuration                               │
└─────────────────────────────────────────────────────────────┘
```

**Path 2: Inherit from `AsyncTTS2HttpExtension` (HTTP mode)**

```text
┌─────────────────────────────────────────────────────────────┐
│                    AsyncTTS2BaseExtension                  │
│  [Generic base class] Provides TTS Extension infrastructure│
│  - Message queue management                                │
│  - Lifecycle management                                    │
│  - Audio data sending                                      │
│  - Metrics reporting                                       │
│  - Error handling                                          │
└─────────────────────────────────────────────────────────────┘
                              ↑ Inheritance
┌─────────────────────────────────────────────────────────────┐
│               AsyncTTS2HttpExtension (HTTP mode)           │
│  [Mode base class] Full HTTP-mode implementation           │
│  - Config loading and validation                           │
│  - Client management                                       │
│  - Request handling logic (full request_tts())             │
│  - TTFB calculation and reporting                          │
│  - PCMWriter management                                    │
└─────────────────────────────────────────────────────────────┘
                              ↑ Inheritance (Path 2)
┌─────────────────────────────────────────────────────────────┐
│              VendorTTSExtension (HTTP subclass)            │
│  [Subclass implementation] Vendor-specific logic           │
│  - Config class implementation (create_config())           │
│  - Client implementation (create_client())                 │
│  - Vendor metadata (vendor())                              │
│  - Sample rate config (synthesize_audio_sample_rate())     │
└─────────────────────────────────────────────────────────────┘
```