---
name: Text-to-speech
type: architecture-map-page
slice: 02-tauri-runtime
last_verified: 2026/05/09
---

# `commands::tts`

> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → TTS

**Plain English summary.** Phase 4: Read Page Aloud. Shells out to the platform's built-in TTS binary (`spd-say` with espeak-ng fallback on Linux, `say` on macOS, PowerShell `System.Speech.Synthesis.SpeechSynthesizer` via `-EncodedCommand` on Windows). Stores the spawned child process so a second tap stops in-flight speech cleanly. User text is never interpolated into a shell string — every backend passes it via argv (or, on Windows, inside a here-string delivered as base64 UTF-16-LE).

## At a glance

- Path: `src-tauri/src/commands/tts.rs`.
- LOC: 444.
- Tauri commands exposed:
  - `tts_speak(state, text: String, rate: f32, voice: Option<String>) -> Result<(), String>`. No window guard (any window can request TTS; the read-aloud feature lives in the main window today but secondary windows are cheap to allowlist for).
  - `tts_stop(state) -> Result<(), String>`. No window guard.
  - `tts_list_voices() -> Result<Vec<TtsVoice>, String>`.
- Events emitted: none.
- Depends on: per-platform TTS binaries (no Rust dependencies beyond `std::process::Command` and `serde`). Windows path uses `base64 = "0.22"` to encode UTF-16-LE for `-EncodedCommand`.
- Called from frontend at: dictation result panel ("Read aloud" toggle), Settings → Accessibility → TTS voice picker.

## What's in here

### `TtsState` (`src-tauri/src/commands/tts.rs:20`)

Tauri-managed: `child: Mutex<Option<Child>>`. On Linux `spd-say` returns immediately so the slot is usually empty; macOS `say` and Windows PowerShell speak synchronously, so the handle is retained.

### `TtsVoice` (`:32`)

`{ id, name, language: Option<String> }`. Frontend renders the list as a dropdown.

### Rate clamping and per-platform mapping

- `clamp_rate(rate)` (`:40`) — clamps to `[0.5, 2.0]`, returns 1.0 for NaN.
- Linux: `spd_rate(rate)` maps to `[-100, 100]` (asymmetric: 1.0→0, 2.0→100, 0.5→-50). `espeak_rate(rate)` maps to words-per-minute in `[80, 450]`.
- macOS: `say_rate(rate)` maps to wpm.
- Windows: `win_rate(rate)` maps to `[-10, 10]` (the SAPI rate scale).

### Per-platform spawners

- `spawn_linux` (`:68`) — tries `spd-say -r <rate> [-t voice] -- <text>`. On `NotFound` falls back to `espeak-ng -s <wpm> [-v voice] -- <text>`. Returns `Some(child)` only for espeak-ng (which speaks synchronously); spd-say returns `None`.
- `spawn_macos` (`:125`) — `say -r <wpm> [-v voice] -- <text>`. Returns the child.
- `spawn_windows` (`:158`) — assembles a PowerShell here-string with the user's text inside, base64-encodes UTF-16-LE, invokes `powershell -NoProfile -EncodedCommand <b64>`. Uses `escape_ps_herestring` (`:153`) to defuse the `'@` here-string terminator if the user's text contains it.

### Voice listing

`tts_list_voices` is a thin wrapper. Per-platform implementations (`:197`, `:206`, `:237`, `:296`):

- Linux: queries `spd-say -L` (or returns `[]` if missing), parses output into `TtsVoice`s.
- macOS: runs `say -v ?`, parses each line via `parse_macos_voices` (testable pure helper at `:220`).
- Windows: queries the .NET `[System.Speech.Synthesis.SpeechSynthesizer]::new().GetInstalledVoices()` via PowerShell, parses CSV.
- Other platforms: returns `[]` with a message.

### `tts_speak`, `tts_stop`, `tts_list_voices` (`:302`, `:345`, `:362`)

`tts_speak` trims the text, kills any in-flight child via `kill_child`, dispatches per-platform. Stores a returned child if any. Returns an explicit error on platforms where TTS is not implemented (e.g. Android).

`tts_stop` calls `kill_child` and additionally calls `stop_linux()` (`:102`) — which fires `spd-say -S` to ask speech-dispatcher to flush its own queue, since spd-say-spawned children are not retained in `state.child`.

`kill_child` (`:353`) takes the child out of state, kills it, and waits for it. `wait()` is important to avoid zombies.

### Tests (`:367`)

Cover rate clamping (NaN, bounds), spd_rate / espeak_rate / say_rate / win_rate per-platform, the PowerShell here-string escape (`ps_herestring_terminator_is_broken`), and the macOS voice parser (`parses_macos_voices`).

## Data flow

```
frontend invoke('tts_speak', { text, rate, voice })
  -> kill any in-flight child
  -> per-OS spawn (spd-say / say / powershell)
  -> stash child handle if backend speaks synchronously
frontend invoke('tts_stop')
  -> kill child
  -> Linux: also fire spd-say -S
```

## Watch-outs

- **No `ensure_main_window` guard.** Today the read-aloud UI lives in the main window, but the ACL allows any window to invoke. If you decide to lock down secondary windows from triggering speech, add the guard.
- **Linux `spd-say` is non-blocking** — `tts_stop` cannot kill its synthesis once it has handed off to speech-dispatcher. The `stop_linux` extra call asks speech-dispatcher to flush its own queue, but that's a soft-stop, not a hard kill.
- **Windows path is heavy.** Every speak-call spawns a PowerShell. Acceptable for one-off use; for a streaming TTS pattern you'd want to keep a long-lived child or use the `windows` crate's SAPI bindings directly.
- **Voice id semantics differ per platform.** macOS uses the voice name; Linux uses an spd-say `-t` token; Windows uses the SAPI registered voice token. Frontend treats them as opaque strings, but a saved-voice in Settings will not survive a platform switch.
- **Brand consistency.** `Lumotia` is being renamed to `Lumenote` (per personal memory `project_lumenote_naming.md`). The TTS module currently embeds the string `"lumotia LLM cleanup"` and `"lumotia"`-prefixed temp filenames; rebrand sweep follow-up.
- **No power assertion.** Long read-aloud sessions on macOS could be idled by App Nap. Add `PowerAssertion::begin("lumotia TTS")` to `tts_speak` if longer transcripts ever become a primary use case.

## See also

- [Power assertions and security](power-and-security.md) — App Nap pattern.
- [LLM](llm.md) — the cleanup pipeline that produces the text fed into TTS.
- [Cargo and features](../cargo-and-features.md) — the Windows-only `base64` dependency.
