Smart Reading

Smart Reading

Smart Reading is what makes Read Aloud sound like a person instead of a screen reader. It has two layers, and the order matters.

flowchart TB
    RAW[Selected text] --> NORM[1 · TTSTextNormalizer<br/>instant, offline, always runs]
    NORM --> AION{Natural reading AI on<br/>and model installed?}
    AION -->|no| OUT[Cleaned text → synthesis]
    AION -->|yes| LLM[2 · TTSNaturalizer<br/>on-device Gemma rewrite]
    LLM --> VALID{Usable rewrite?}
    VALID -->|yes| OUT2[Rewritten text → synthesis]
    VALID -->|no, self-intro / off-length| OUT

Loading

The normalizer always runs first. The AI layer only refines already-clean text, and if it misbehaves the result falls back to the clean text — so the voice can never read junk, symbol names, or a chatty "I am an AI model…".

Layer 1 — TTSTextNormalizer (instant, deterministic, offline)

A pure, mechanical pass. Always on (TTSSettings.smartCleanup). Highlights:

Input	Spoken as
API, CPU	"A P I", "C P U" (letter-acronyms spelled; NASA/JSON kept)
config.yaml	"config dot yaml"
https://github.com/x	"github dot com"
dev@example.com	"dev at example dot com"
/usr/bin	"usr bin"
Error: ENOENT	"Error: file not found"
$5, 95%	"5 dollars", "95 percent"
fetchSelectedText, my_var	"fetch Selected Text", "my var"
✅ ❌ ⚠️	"check", "no", "warning" (other emoji stripped)
│ a │ b │ table row	"a, b." (borders stripped, rows → sentences)
markdown, box-drawing	removed

Tables are flattened first: rows become comma-separated, period-terminated sentences; border/separator rows collapse.

Layer 2 — TTSNaturalizer (optional, on-device AI)

Off by default (TTSSettings.naturalReadingAI); needs the Gemma model. Rewrites the cleaned text into natural spoken prose via LocalLLMModelManager.

Design notes that keep a small model well-behaved:

• Imperative, completion-style prompt (TEXT: … REWRITTEN:), not "You are…" — the latter makes small models introduce themselves.
• A one-shot example anchors the format.
• Output validation (isUsableRewrite): rejects self-introductions, refusals, and wildly off-length responses → falls back to the cleaned text.
• Low temperature (0.3) for faithfulness.

Settings

A Smart reading section (Read Aloud settings) exposes both toggles plus the on-device model download card. The same model and card also appear on the AI Models screen for dictation enhancement.

See: Read Aloud · On-Device LLM · AI Enhancement