How to Configure Text-to-Speech Providers in AnythingLLM: Complete Setup Guide

Configure Text-to-Speech providers in AnythingLLM by setting the TextToSpeechProvider system value—either through the Audio Preference UI or by editing environment variables directly—to enable spoken AI responses using native browser capabilities, OpenAI, ElevenLabs, Piper TTS, or generic OpenAI-compatible endpoints.

AnythingLLM supports multiple Text-to-Speech (TTS) backends to vocalize AI assistant responses. According to the Mintplex-Labs/anything-llm source code, the system uses a centralized configuration model that synchronizes backend environment variables with frontend React contexts, allowing seamless provider switching without code changes.

Understanding the TTS Architecture

The Text-to-Speech system in AnythingLLM operates across three distinct layers that communicate via the System.keys() and System.updateSystem() APIs.

Backend Configuration Layer

In server/models/systemSettings.js, the currentSettings() function aggregates all TTS-related environment variables into a configuration object exposed to the frontend:

// server/models/systemSettings.js
TextToSpeechProvider: process.env.TTS_PROVIDER || "native",
TTSOpenAIKey: !!process.env.TTS_OPEN_AI_KEY,
TTSOpenAIVoiceModel: process.env.TTS_OPEN_AI_VOICE_MODEL,
TTSElevenLabsKey: !!process.env.TTS_ELEVEN_LABS_KEY,
TTSElevenLabsVoiceModel: process.env.TTS_ELEVEN_LABS_VOICE_MODEL,
TTSPiperTTSVoiceModel: process.env.TTS_PIPER_VOICE_MODEL ?? "en_US-hfc_female-medium",

The TextToSpeechProvider key determines which service renders speech. When updating settings via the API, server/utils/helpers/updateENV.js validates the provider against an allowed list using the supportedTTSProvider check, ensuring only valid values (native, openai, elevenlabs, piper_local, generic-openai) are persisted to the .env file.

Frontend State Management

The React application maintains TTS state through the TTSProvider context defined in frontend/src/components/contexts/TTSProvider.jsx. This context fetches the current configuration on mount:

// frontend/src/components/contexts/TTSProvider.jsx
useEffect(() => {
  async function getSettings() {
    const _settings = await System.keys();
    setProvider(_settings?.TextToSpeechProvider ?? "native");
    setSettings(_settings);
    setLoading(false);
  }
  getSettings();
}, []);

Components throughout the application consume this context via the useTTSProvider() hook to determine which TTS engine to invoke for chat message playback.

Supported Text-to-Speech Providers

AnythingLLM supports five distinct TTS backends, each requiring specific configuration keys:

• System Native: Uses the browser's built-in Web Speech API. Requires no external credentials.
• OpenAI: Uses OpenAI's TTS API. Requires TTS_OPEN_AI_KEY.
• ElevenLabs: Uses ElevenLabs' voice synthesis. Requires TTS_ELEVEN_LABS_KEY.
• Piper (Local): Runs local Piper TTS inference. Configured via TTS_PIPER_VOICE_MODEL.
• OpenAI Compatible: Connects to custom TTS endpoints matching the OpenAI API format. Requires endpoint, key, and model variables.

Configuration Methods

You can configure Text-to-Speech providers using either the web interface or manual environment file editing.

Method 1: Using the Web UI

Navigate to Settings > Audio Preference > Text-to-Speech. The UI component frontend/src/pages/GeneralSettings/AudioPreference/tts.jsx renders the provider selection form:

// frontend/src/pages/GeneralSettings/AudioPreference/tts.jsx
const PROVIDERS = [
  {
    name: "System native",
    value: "native",
    logo: AnythingLLMIcon,
    options: (settings) => <BrowserNative settings={settings} />,
    description: "Uses your browser's built in TTS service if supported."
  },
  {
    name: "OpenAI",
    value: "openai",
    logo: OpenAiLogo,
    options: (settings) => <OpenAiTTSOptions settings={settings} />,
    description: "Use OpenAI's text to speech voices."
  },
  // ... additional providers
];

When you select a provider and click Save, the component constructs a payload and calls System.updateSystem():

const handleSubmit = async (e) => {
  e?.preventDefault();
  const form = e.target;
  const data = { TextToSpeechProvider: selectedProvider };
  const formData = new FormData(form);
  for (var [key, value] of formData.entries()) data[key] = value;
  const { error } = await System.updateSystem(data);
};

This performs a POST /system/update-env request. The backend validates the payload via updateENV.js and writes the values to the environment configuration.

Method 2: Manual Environment Variables

For Docker deployments or headless configuration, edit the .env file directly:

# .env configuration example

TTS_PROVIDER=elevenlabs
TTS_ELEVEN_LABS_KEY=your-elevenlabs-api-key-here
TTS_ELEVEN_LABS_VOICE_MODEL=en_us_female

After saving changes, restart the AnythingLLM server (or run docker compose up -d for containerized instances). The System.keys() call will reflect the new TextToSpeechProvider value on the next frontend initialization.

Provider-Specific Setup Instructions

Each provider requires distinct configuration parameters validated by the backend schema.

OpenAI TTS

Set the following environment variables or UI fields:

• TTS_OPEN_AI_KEY: Your OpenAI API key (required)
• TTS_OPEN_AI_VOICE_MODEL: Voice model identifier (optional, defaults to OpenAI's standard voices)

In the UI, the OpenAiTTSOptions component renders input fields for these values.

ElevenLabs

Configure ElevenLabs integration with:

• TTS_ELEVEN_LABS_KEY: ElevenLabs API key (required)
• TTS_ELEVEN_LABS_VOICE_MODEL: Voice ID (optional)

The frontend validates these inputs before submitting to System.updateSystem().

Piper Local

For local TTS using Piper, specify the voice model path:

• TTS_PIPER_VOICE_MODEL: Defaults to en_US-hfc_female-medium if not specified

This provider requires the Piper binary installed locally on the server hosting AnythingLLM.

OpenAI Compatible

For custom TTS endpoints matching the OpenAI API specification:

• TTS_OPEN_AI_COMPATIBLE_KEY: API key for the endpoint
• TTS_OPEN_AI_COMPATIBLE_ENDPOINT: Base URL for the TTS service
• TTS_OPEN_AI_COMPATIBLE_MODEL: Model identifier
• TTS_OPEN_AI_COMPATIBLE_VOICE_MODEL: Voice selection parameter

System Native

Requires no configuration. The frontend checks browser Web Speech API support automatically when TextToSpeechProvider is set to native.

Programmatic Configuration via API

You can update the TTS provider programmatically using the internal System model:

import System from "@/models/system";

async function configureTTSProvider(provider, config) {
  const payload = {
    TextToSpeechProvider: provider,
    ...config
  };
  
  const { error } = await System.updateSystem(payload);
  if (error) {
    console.error("Failed to update TTS provider:", error);
    return false;
  }
  console.log(`Successfully configured TTS provider: ${provider}`);
  return true;
}

// Example: Switch to OpenAI
configureTTSProvider("openai", {
  TTSOpenAIKey: "sk-xxxxxxxxxxxxxxxxxxxx",
  TTSOpenAIVoiceModel: "alloy"
});

This method directly invokes the POST /system/update-env endpoint with the same validation used by the UI.

Summary

• TextToSpeechProvider is the central configuration key stored in server/models/systemSettings.js that determines which TTS backend AnythingLLM uses.
• The frontend retrieves this setting via System.keys() and distributes it through the TTSProvider React context defined in frontend/src/components/contexts/TTSProvider.jsx.
• Valid provider values include native, openai, elevenlabs, piper_local, and generic-openai, validated by server/utils/helpers/updateENV.js.
• Configuration persists through the System.updateSystem() API, which updates both the database and the .env file.
• Each provider requires specific environment variables (e.g., TTS_OPEN_AI_KEY, TTS_ELEVEN_LABS_KEY) detailed in the respective UI option components.

Frequently Asked Questions

What Text-to-Speech providers does AnythingLLM support?

AnythingLLM supports five TTS providers: System Native (browser Web Speech API), OpenAI, ElevenLabs, Piper (Local), and OpenAI Compatible endpoints. These are defined in frontend/src/pages/GeneralSettings/AudioPreference/tts.jsx and validated by the backend in server/utils/helpers/updateENV.js.

How do I change the TTS provider without using the web interface?

Edit the .env file in your AnythingLLM root directory and set TTS_PROVIDER to your desired value (e.g., openai, elevenlabs). Add any required provider-specific keys such as TTS_OPEN_AI_KEY or TTS_ELEVEN_LABS_KEY, then restart the server. The changes will be reflected in the next System.keys() call.

Where are TTS settings stored in the AnythingLLM codebase?

TTS settings are defined in server/models/systemSettings.js where environment variables are mapped to configuration keys. The frontend consumes these settings through the TTSProvider context in frontend/src/components/contexts/TTSProvider.jsx, and the UI for changing providers is implemented in frontend/src/pages/GeneralSettings/AudioPreference/tts.jsx.

Can I use a custom TTS endpoint that mimics OpenAI's API?

Yes. Select the OpenAI Compatible provider in the UI or set TTS_PROVIDER=generic-openai in your .env file. You must provide TTS_OPEN_AI_COMPATIBLE_ENDPOINT, TTS_OPEN_AI_COMPATIBLE_KEY, TTS_OPEN_AI_COMPATIBLE_MODEL, and TTS_OPEN_AI_COMPATIBLE_VOICE_MODEL to authenticate and configure the custom endpoint.

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