Jake
26c7307607
Phase 9 of the rebrand cascade. Sweep covers everything the Phase 8
frontend pass deliberately skipped: docs/, root markdown, scripts,
Cargo.toml descriptions, code comments that survived earlier
word-boundary sed, plus a handful of identifiers caught on the final
verify pass.
transcription-app changes:
- README.md, HANDOVER.md, KNOWN-ISSUES.md, run.sh — magnotia/Magnotia
-> lumotia/Lumotia.
- docs/ — sweep across all subdirs except docs/handovers/ (preserved
as immutable audit trail). Includes architecture-map references
to magnotia_core::*, magnotia_storage::*, etc. now pointing at
lumotia_*; dev-setup.md tracing output examples (lumotia_startup
target); brief/ + superpowers/ + issues/ + whisper-ecosystem/ +
audit/.
- Cargo.toml descriptions on 9 crates (core, audio, cloud-providers,
hotkey, llm, mcp, plus referenced others).
- crates/core/src/{error,hardware,recommendation,paths}.rs +
crates/audio/src/wav.rs + crates/llm/src/model_manager.rs +
crates/cloud-providers/src/keystore.rs + crates/mcp/src/lib.rs —
doc comments and a model-manager user-agent string.
- Caught on final pass: BroadcastChannel("magnotia_task_sync") -> ...
("lumotia_task_sync"); magnotia_locale i18n localStorage key
renamed + migration shim added; CSS keyframe names
magnotiaPulse / magnotiaBar / magnotiaFade renamed in the design-
system kit; magnotia_viewer_item / magnotia_viewer_mode handoff
keys renamed in HistoryPage + viewer/+page.svelte; src/assets/
wordmark.svg text.
- src-tauri/src/lib.rs comment cleanup ("magnotia era" was sed'd
to "lumotia era" earlier — restored).
Preserved (intentional):
- crates/core/src/paths.rs — keeps "magnotia" / "Magnotia" / ".magnotia"
legacy detection strings in legacy_and_target_paths() so the
migration shim can still find user data from the magnotia era.
- src/lib/stores/{page,focusTimer}.svelte.ts + src/lib/i18n/index.ts
— migration call sites reference the legacy magnotia keys
deliberately.
- docs/handovers/ — historical audit trail.
cargo build --workspace passes. npm run check: 0 errors / 0 warnings
(3958 files). cargo test --workspace: 339 pass / 0 fail.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
96 lines
6.1 KiB
Markdown
96 lines
6.1 KiB
Markdown
---
|
|
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.
|