> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuralcleave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Providers

> Configure STT and TTS backends — from local faster-whisper to ElevenLabs cloud.

NeuralCleave supports multiple STT (speech-to-text) and TTS (text-to-speech) backends. The defaults work fully offline.

## STT backends

### faster-whisper (default, local)

[faster-whisper](https://github.com/SYSTRAN/faster-whisper) is a CTranslate2-optimized Whisper implementation. It runs on CPU or CUDA, requires no API key, and is completely local.

```toml theme={null}
[voice]
stt = "whisper"
stt_model = "base"      # tiny | base | small | medium | large-v3
stt_device = "cpu"      # cpu | cuda
```

Model sizes:

| Model      | Size   | Speed   | Accuracy |
| ---------- | ------ | ------- | -------- |
| `tiny`     | 75 MB  | Fastest | Lowest   |
| `base`     | 145 MB | Fast    | Good     |
| `small`    | 465 MB | Medium  | Better   |
| `medium`   | 1.5 GB | Slow    | High     |
| `large-v3` | 3 GB   | Slowest | Highest  |

Start with `base`. Models are downloaded automatically on first use.

### Disable STT

```toml theme={null}
[voice]
stt = "none"
```

## TTS backends

NeuralCleave always tries ElevenLabs → Kokoro → pyttsx3, in that order, using whichever provider succeeds first (ElevenLabs is skipped automatically when no API key is configured). `tts_engine` only gates whether TTS is enabled at all (any value other than `"none"` turns it on) — it does not currently pin synthesis to one specific engine or change the try-order, despite the name. Setting it to `"kokoro"` or `"pyttsx3"` does not skip ElevenLabs if a key happens to be configured.

### Kokoro (local, high quality)

[Kokoro](https://github.com/hexgrad/kokoro) is an open-source neural TTS model. It runs on CPU and produces near-ElevenLabs quality without any API key.

```toml theme={null}
[voice]
tts_engine = "kokoro"
```

There is no config key for selecting a Kokoro voice yet — `TTSEngine` always uses its `"af_sarah"` default, and `[voice]` has no field that reaches it.

### ElevenLabs (cloud, best quality)

```toml theme={null}
[voice]
tts_engine = "elevenlabs"
elevenlabs_api_key = "ENV:ELEVENLABS_API_KEY"
elevenlabs_voice_id = "21m00Tcm4TlvDq8ikWAM"  # Rachel (default)
```

Find voice IDs at [elevenlabs.io/voice-library](https://elevenlabs.io/voice-library).

### pyttsx3 (local, system TTS)

Fallback that uses the OS text-to-speech engine. No install required.

```toml theme={null}
[voice]
tts_engine = "pyttsx3"
```

### Disable TTS

```toml theme={null}
[voice]
tts_engine = "none"
```

## Audio devices

Configure input/output devices to route audio correctly on systems with multiple devices:

```toml theme={null}
[voice]
input_device = ""     # empty = system default
output_device = ""    # empty = system default
```

The Settings → Voice page in the dashboard shows a live dropdown of available devices populated from `GET /api/v1/voice/devices`.

## Privacy note

Privacy mode (the in-chat `/privacy on|off` command) only affects text generation — it forces `ModelRouter` onto local-only models and has no effect on the voice pipeline at all. It does **not** force TTS to Kokoro or stop ElevenLabs from being used, and there is no `privacy_mode` entry in `[voice]` or anywhere else in `config.py` — it isn't a config setting. To keep voice fully local today, don't configure `elevenlabs_api_key` and leave `tts_engine` set to `"kokoro"` or `"pyttsx3"`.