Local AI TTS Guide

Do I need this?

“Local” means one of two things: a voice built into SSN that runs in your browser, or a voice server you run yourself.

Built-in voices (nothing to install)

These run inside SSN in your browser. No server, Docker, or API key.

Set it up in 4 steps

1. Add &speech=en-US&ttsprovider=kokoro to your dock.html link. (Or piper, kitten, espeak.)
2. Add that link to OBS as a Browser Source. That's the page that makes the sound.
3. In its properties, turn on Control audio via OBS.
4. Send a short test chat, like Testing local TTS.

dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=kokoro

Voices, speed, and other languages: provider settings. Prefer clicking? Use the setup guide.

Connect your own TTS server

A server gives you more voices, voice cloning, or one voice you reuse across tools. SSN talks to it like an OpenAI-compatible speech server. No API key needed.

1. Start your server. Kokoro-FastAPI is the easiest.
2. In SSN, open the TTS provider list and pick Custom / Local TTS Endpoint.
3. In Custom / Local API Endpoint, enter your server's address, like http://127.0.0.1:8880/v1/audio/speech.
4. Leave the API key blank.
5. Pick a voice your server knows: af_bella for Kokoro, nova for openedai-speech.
6. Copy the link into OBS and send a test chat.

These need Docker Desktop installed and running. It's free for personal use.

The localhost rule

This is the most common mistake.

Also check the firewall allows the port, and that Docker published it (-p 8880:8880).

Kokoro-FastAPI

Kokoro-FastAPI runs Kokoro as a local server. Works on CPU; no GPU needed.

1. Open a terminal (Command Prompt, PowerShell or Terminal) and run one of these:

   docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.2

   NVIDIA GPU (faster):

   docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:v0.2.0post4

   The first run downloads about 1.5–2 GB, once.
2. Open http://localhost:8880/web/. You should see a page to test voices (67+ available).
3. Use this link (change the address if the server is on another PC):

   dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=customtts&openaiendpoint=http://127.0.0.1:8880/v1/audio/speech&voiceopenai=af_bella

Start it with Docker automatically:

docker run -d --restart unless-stopped -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.2.2

openedai-speech (Piper and XTTS-v2)

Option A: Light Piper server (CPU)

Under 1 GB. No voice cloning.

docker run -d --restart unless-stopped -p 8000:8000 ghcr.io/matatonic/openedai-speech-min

Voices: alloy, echo, fable, onyx, nova, shimmer.

dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=openai&openaiendpoint=http://localhost:8000/v1/audio/speech&voiceopenai=nova

cd openedai-speech
$env:Path = "$PWD\.venv\Scripts;$env:Path"
.\.venv\Scripts\python.exe speech.py --xtts_device none -H 127.0.0.1 -P 8000

Option B: XTTS-v2 voice cloning (GPU)

Needs the full server, not openedai-speech-min. Plan on about 4 GB of GPU memory. CPU works but is slow.

The local TTS bridge

A small helper from SSN. It takes SSN's request, passes it to your voice server, and hands the audio back in a way browsers accept. Needs Node.js.

1. Tell the bridge where your server is. PowerShell:

   $env:SSN_TTS_TARGET="http://127.0.0.1:8880/v1/audio/speech"

   Server on another PC? Use its local IP, like http://192.168.x.x:8880/v1/audio/speech.
2. In the SSN folder, run node scripts/local-tts-bridge.cjs. Leave it running.
3. Point SSN at the bridge:

   dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=customtts&openaiendpoint=http://127.0.0.1:8124/v1/audio/speech&voiceopenai=af_bella

macOS/Linux, in one line: SSN_TTS_TARGET="http://127.0.0.1:8880/v1/audio/speech" node scripts/local-tts-bridge.cjs. Inside the local-tts-bridge folder, node server.cjs does the same. Change the port with SSN_TTS_BRIDGE_PORT=8125. All options: bridge README.

$env:SSN_TTS_REF_AUDIO_PATH="C:\voices\speaker.wav"
$env:SSN_TTS_REF_TEXT="Reference audio transcript here."
$env:SSN_TTS_TARGET="http://127.0.0.1:9880/tts"
node scripts/local-tts-bridge.cjs --mode gptsovits

dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=customtts&openaiendpoint=http://127.0.0.1:8124/v1/audio/speech&openaiformat=wav

$env:SSN_TTS_TARGET="http://127.0.0.1:7860/synthesize_speech/"
node scripts/local-tts-bridge.cjs --mode f5

dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=customtts&openaiendpoint=http://127.0.0.1:8124/v1/audio/speech&voiceopenai=default_en&openaiformat=wav

Voice cloning

Cloning isn't an SSN setting. It's a feature of some voice servers. SSN sends the chat text; the server picks the cloned voice.

1. Record a clean clip of one speaker, usually 3–30 seconds, with little background noise.
2. Some servers also need the exact words spoken in the clip.
3. The server turns the clip into a voice profile.
4. SSN sends chat text with ttsprovider=customtts.
5. The server returns audio (usually WAV or MP3) and SSN plays it.

With 6 GB of GPU memory or less, start with small models on OpenAI-compatible servers. Bigger models work too if hosted elsewhere.

Built-in Kokoro and Kokoro-FastAPI don't clone voices.

What computer do I need?

Rough starting points, not promises. Model size, text length and other apps all change memory use.

Get the audio into OBS

OBS Browser Source (recommended)

Works with built-in voices and your own server.

1. Add a Browser Source with your dock.html TTS link.
2. Turn on Control audio via OBS.
3. Click OK. TTS now shows in the OBS mixer.

SSN desktop app

The desktop app uses the same link settings. But the sound plays from the app, not OBS. Capture it with Desktop Audio or Audio Input Capture. To keep TTS separate from other sounds, send the app to a virtual cable: routing steps.

Side-by-side

Fix problems

For server builders

How SSN talks to a custom server. You only need this if you're building or debugging one.

chat text -> SSN -> your endpoint (or the bridge) -> TTS server -> audio -> SSN plays it

POST /v1/audio/speech
{
  "model": "tts-1",
  "input": "Chat message text",
  "voice": "af_bella",
  "response_format": "mp3",
  "speed": 1.0
}

Kokoro-FastAPI:  dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=customtts&openaiendpoint=http://localhost:8880/v1/audio/speech&voiceopenai=af_bella&openaispeed=1.1
openedai-speech: dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=customtts&openaiendpoint=http://localhost:8000/v1/audio/speech&voiceopenai=nova
kokoro-web:      dock.html?session=YOUR_SESSION&speech=en-US&ttsprovider=customtts&openaiendpoint=http://localhost:3000/api/v1/audio/speech&voiceopenai=af_bella