--- 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) -> 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, 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>`. 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 }`. 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 [-t voice] -- `. On `NotFound` falls back to `espeak-ng -s [-v voice] -- `. Returns `Some(child)` only for espeak-ng (which speaks synchronously); spd-say returns `None`. - `spawn_macos` (`:125`) — `say -r [-v voice] -- `. 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 `. 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.