# How to Configure Text-to-Speech (TTS) in NextChat: A Complete Guide

> Configure Text-to-Speech TTS in NextChat easily. Follow this guide to enable TTS, choose engines like OpenAI-TTS or Edge-TTS, and customize voice and speed for a personalized experience.

- Repository: [NextChat/NextChat](https://github.com/ChatGPTNextWeb/NextChat)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Enable TTS in NextChat by toggling the feature in Settings > TTS, selecting between OpenAI-TTS or Edge-TTS engines, and configuring voice, model, and speed parameters.**

NextChat (ChatGPTNextWeb) ships with a built-in Text-to-Speech feature that converts assistant replies into audible audio. This guide explains how to configure Text-to-Speech (TTS) in NextChat using the settings UI or programmatic methods, referencing the actual implementation in [`app/components/tts-config.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/components/tts-config.tsx) and [`app/store/config.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/store/config.ts).

## Understanding the TTS Architecture in NextChat

The TTS system relies on three core layers defined in the source code:

1. **Constants Layer** – Default values and allowed options are exported from [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts) (`DEFAULT_TTS_ENGINE`, `DEFAULT_TTS_ENGINES`, `DEFAULT_TTS_MODELS`, `DEFAULT_TTS_VOICES`).
2. **State Layer** – The `ttsConfig` slice is managed by the Zustand store in [`app/store/config.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/store/config.ts) via `useAppConfig`, with validation handled by `TTSConfigValidator`.
3. **UI Layer** – The `TTSConfigList` component in [`app/components/tts-config.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/components/tts-config.tsx) renders the settings interface and dispatches updates to the store.

## TTS Configuration Options

The following settings control TTS behavior. All values are defined in [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts) and validated in [`app/store/config.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/store/config.ts) (lines 28-41):

| Setting | Description | Default Value |
|---------|-------------|---------------|
| **Enable** | Master toggle to activate TTS for assistant messages | `false` |
| **Engine** | Backend provider: `OpenAI-TTS` or `Edge-TTS` | `OpenAI-TTS` |
| **Model** | OpenAI model (`tts-1` or `tts-1-hd`) | `tts-1` |
| **Voice** | Voice style (e.g., `alloy`, `echo`, `nova`, `shimmer`) | `alloy` |
| **Speed** | Playback speed multiplier (0.3 to 4.0) | `1.0` |

## How to Configure TTS via the Settings UI

The recommended method uses the `TTSConfigList` component rendered in the Settings page:

1. Open the **Settings** modal (gear icon) and scroll to the **TTS** section.
2. Toggle **Enable** to activate the feature.
3. Select an **Engine**:
   - Choose `OpenAI-TTS` to use OpenAI's `v1/audio/speech` endpoint.
   - Choose `Edge-TTS` to use the Microsoft Edge browser TTS service (implemented in [`app/utils/ms_edge_tts.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/utils/ms_edge_tts.ts)).
4. Pick a **Model** (`tts-1` for standard quality, `tts-1-hd` for high definition).
5. Select a **Voice** from the dropdown populated by `DEFAULT_TTS_VOICES`.
6. Adjust the **Speed** slider (clamped between 0.3 and 4.0).

Changes are persisted immediately via `updateConfig` in [`app/store/config.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/store/config.ts) and survive page reloads.

## Programmatic TTS Configuration

For advanced use cases, you can manipulate the configuration directly using the `useAppConfig` hook:

```typescript
import { useAppConfig } from '@/store/config';
import { DEFAULT_TTS_ENGINE } from '@/constant';

export function configureTTS() {
  const { updateConfig } = useAppConfig.getState();

  updateConfig((config) => {
    config.ttsConfig.enable = true;
    config.ttsConfig.engine = DEFAULT_TTS_ENGINE; // "OpenAI-TTS"
    config.ttsConfig.model = 'tts-1-hd';
    config.ttsConfig.voice = 'nova';
    config.ttsConfig.speed = 1.2;
  });
}

```

This pattern mirrors the internal implementation of `TTSConfigList` and updates the persisted Zustand store atomically.

## Direct Configuration via LocalStorage (Advanced)

The configuration is stored under the key defined by `StoreKey.Config` (`"chat-next-web-store"`). You can modify it directly for debugging:

```javascript
const raw = localStorage.getItem('chat-next-web-store');
const data = JSON.parse(raw);

data.ttsConfig = {
  enable: true,
  engine: 'Edge-TTS',
  model: 'tts-1',
  voice: 'alloy',
  speed: 1.0,
};

localStorage.setItem('chat-next-web-store', JSON.stringify(data));
location.reload();

```

**Warning:** This bypasses the `TTSConfigValidator` in [`app/store/config.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/store/config.ts). Ensure values match the allowed literals defined in [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts) to avoid runtime errors.

## Using Edge-TTS vs OpenAI-TTS

When selecting an engine in [`app/components/tts-config.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/components/tts-config.tsx), you choose between two distinct implementations:

- **OpenAI-TTS**: Calls the OpenAI API endpoint defined in [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts) (`OpenaiPath.SpeechPath`). Requires a valid OpenAI API key and consumes OpenAI credits.
- **Edge-TTS**: Uses the Microsoft Edge browser TTS service via [`app/utils/ms_edge_tts.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/utils/ms_edge_tts.ts). This engine builds an SSML payload and returns a Base64-encoded MP3 buffer without requiring an OpenAI API key.

Example of invoking Edge-TTS programmatically:

```typescript
import { msEdgeTTS } from '@/utils/ms_edge_tts';

async function playEdgeTTS(text: string, voice: string, speed: number) {
  const base64Audio = await msEdgeTTS(text, { voice, speed });
  const audio = new Audio(`data:audio/mp3;base64,${base64Audio}`);
  audio.play();
}

```

## Summary

- NextChat provides built-in TTS via the `TTSConfigList` component in [`app/components/tts-config.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/components/tts-config.tsx), controlled by the `useAppConfig` store in [`app/store/config.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/store/config.ts).
- Configuration options include **Enable**, **Engine** (`OpenAI-TTS` or `Edge-TTS`), **Model**, **Voice**, and **Speed**, with defaults defined in [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts).
- Use the **Settings UI** for visual configuration, or invoke `updateConfig` on `useAppConfig.getState()` for programmatic control.
- **Edge-TTS** ([`app/utils/ms_edge_tts.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/utils/ms_edge_tts.ts)) offers API-free synthesis using Microsoft Edge voices, while **OpenAI-TTS** requires API access but offers high-fidelity voices like `nova` and `shimmer`.

## Frequently Asked Questions

### How do I enable TTS in NextChat?

Toggle the **Enable** switch in Settings > TTS. This sets `ttsConfig.enable` to `true` in the `useAppConfig` store, allowing the application to synthesize audio after each assistant message completes.

### What is the difference between OpenAI-TTS and Edge-TTS?

**OpenAI-TTS** uses OpenAI's `v1/audio/speech` endpoint (defined in [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts)) and requires a valid API key. **Edge-TTS** uses the Microsoft Edge browser TTS service implemented in [`app/utils/ms_edge_tts.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/utils/ms_edge_tts.ts), which does not require an OpenAI key but relies on Microsoft's voice endpoints.

### Where are TTS settings stored?

Settings persist in the browser's `localStorage` under the key `"chat-next-web-store"` (defined by `StoreKey.Config` in [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts)). The `useAppConfig` Zustand store handles serialization and validation via `TTSConfigValidator`.

### How can I change the TTS voice programmatically?

Import `useAppConfig` from `@/store/config` and call `updateConfig` on the store state. Modify `config.ttsConfig.voice` to any valid value from `DEFAULT_TTS_VOICES` (e.g., `alloy`, `nova`, `echo`), then commit the change to update the persisted configuration immediately.