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

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 and 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 (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 via useAppConfig, with validation handled by TTSConfigValidator.
3. UI Layer – The TTSConfigList component in 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 and validated in 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).
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 and survive page reloads.

Programmatic TTS Configuration

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

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:

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. Ensure values match the allowed literals defined in app/constant.ts to avoid runtime errors.

Using Edge-TTS vs OpenAI-TTS

When selecting an engine in app/components/tts-config.tsx, you choose between two distinct implementations:

• OpenAI-TTS: Calls the OpenAI API endpoint defined in 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. 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:

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, controlled by the useAppConfig store in 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.
• Use the Settings UI for visual configuration, or invoke updateConfig on useAppConfig.getState() for programmatic control.
• Edge-TTS (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) and requires a valid API key. Edge-TTS uses the Microsoft Edge browser TTS service implemented in 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). 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}