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

# otter-vox

> Convert text to speech on-device with an embedded Kokoro TTS model. Requires the otter-shell-extras metapackage.

otter-vox turns text into speech on your machine using an embedded Kokoro TTS model. No internet connection required.

<Note>
  `otter-vox` is part of **`otter-shell-extras`**, not the base `otter-shell` metapackage. Install with `pikman install otter-shell-extras`.
</Note>

## Usage

Pipe text into otter-vox or pass it as a positional argument. Use `--no-play` to write a WAV stream to stdout, or `-o` to save to a file.

```bash theme={null}
printf 'Welcome to Otter Shell.' | otter-vox --no-play | pw-play -  # pipe to PipeWire
printf 'Welcome to Otter Shell.' | otter-vox -o speech.wav           # save to file
otter-vox --voice bm_lewis --play 'Welcome to Otter Shell.'          # speak with voice
otter-vox --check-model                                               # verify model
otter-vox --list-voices                                               # list all voices
```

## Voices

otter-vox ships with Kokoro voice files embedded in the binary, covering several languages and accents.

| Prefix | Language / Accent | Example voices                                                      |
| ------ | ----------------- | ------------------------------------------------------------------- |
| `af_*` | American female   | alloy, bella, jessica, nova, heart, kore, nicole, river, sarah, sky |
| `am_*` | American male     | adam, echo, michael, onyx, eric, fenrir, liam, puck                 |
| `bf_*` | British female    | alice, emma, isabella, lily                                         |
| `bm_*` | British male      | daniel, george, lewis, fable                                        |
| `df_*` | German female     | eva, victoria                                                       |
| `dm_*` | German male       | bernd, martin                                                       |
| `ef_*` | Spanish female    | dora                                                                |
| `em_*` | Spanish male      | alex, santa                                                         |
| `ff_*` | French female     | siwis                                                               |
| `hf_*` | Hindi female      | alpha, beta                                                         |
| `hm_*` | Hindi male        | omega, psi                                                          |
| `if_*` | Italian female    | sara                                                                |
| `im_*` | Italian male      | nicola                                                              |
| `jf_*` | Japanese female   | alpha, gongitsune, nezumi, tebukuro                                 |
| `jm_*` | Japanese male     | kumo                                                                |
| `pf_*` | Portuguese female | dora                                                                |
| `pm_*` | Portuguese male   | alex, santa                                                         |
| `zf_*` | Chinese female    | xiaobei, xiaoni, xiaoxiao, xiaoyi                                   |
| `zm_*` | Chinese male      | yunjian, yunxi, yunxia, yunyang                                     |

<Tip>
  Run `otter-vox --list-voices` to see all embedded voice names available in your install.
</Tip>

## Output Options

* **Default**: plays audio through your system audio output
* **`--no-play`**: writes a raw WAV stream to stdout for piping to another program
* **`-o PATH` / `--output PATH`**: saves audio to a file instead of (or alongside) playing it
* **`-o speech.wav` with playback enabled**: saves the file and plays it at the same time

## Configuration

otter-vox reads `~/.config/otter-shell/otter-vox.conf`.

```conf theme={null}
model_dir = ""
output_path = "-"
playback = true
voice = "bm_george"
cpu_threads = 4
```

* `model_dir`: empty uses the embedded model, extracted at runtime. Set a directory path to use your own Kokoro model and voice files
* `output_path`: output destination (`-` for stdout)
* `playback`: play audio after synthesis
* `voice`: default voice name
* `cpu_threads`: thread count for inference