Lumotia/docs/architecture-map/02-tauri-runtime/commands/tts.md

name, type, slice, last_verified

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

commands::tts

Where you are: Architecture map → Tauri runtime → Commands → 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 TtsVoices.
• 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 — App Nap pattern.
• LLM — the cleanup pipeline that produces the text fed into TTS.
• Cargo and features — the Windows-only base64 dependency.