SpeakTrue

Quick Speak Accessibility Mode Plan

Status

Proposed native-first implementation plan for fast, accessible typed or prepared speech on iOS and Android.

Product Thesis

When speech is time-sensitive, the user should not have to navigate the full TTS studio, choose technical generation settings, wait without feedback, or lose the ability to communicate when the network fails. Quick Speak should optimize the path from intent to audible speech while preserving an obvious route to the full studio.

User Outcome

A user can open Quick Speak, type or select a pinned phrase, and activate one large Speak control. SpeakTrue uses the selected cloud voice when available and a clearly labeled platform voice fallback when cloud generation is unavailable or the user chooses offline mode.

Principles

• Communication speed over configuration density.
• Predictable one-action playback; no surprise autoplay on ordinary app launch.
• Local utility without sign-in; cloud voices and synced pins use normal auth.
• Basic local speech remains free.
• Full screen-reader, switch-control, font-scaling, contrast, and reduced-motion support.
• Phrase content never enters telemetry, shortcut URLs, notification text, or crash breadcrumbs.

Scope

MVP

• iOS and Android Quick Speak destination;
• large multiline composer and primary Speak/Stop control;
• local recent phrases with explicit clear action;
• pinned phrases;
• existing SpeakTrue cloud TTS path;
• iOS AVSpeechSynthesizer and Android TextToSpeech fallback;
• offline and auth-expiry behavior;
• opaque-ID app shortcuts after phrase identity is stable;
• content-free latency/fallback diagnostics.

Later

• web Quick Speak;
• lock-screen widgets or live activities;
• wearable surfaces;
• gaze-specific layouts;
• importing OS Personal Voice capabilities, subject to entitlement/API review;
• predictive phrase suggestions;
• shared caregiver-managed phrase sets.

Non-Goals

• replacing the full TTS studio;
• claiming that platform voices match a selected cloned/cloud voice;
• background microphone listening;
• storing arbitrary phrase text inside deep links;
• auto-speaking a phrase merely because the app was opened;
• making cloud synthesis appear offline-capable when no audio is cached.

UX Contract

Default screen

• Focus lands on the composer when opened normally.
• The composer supports multiline text and a visible character count only near service limits.
• One high-prominence Speak button becomes Stop during playback.
• Secondary controls expose voice, speed, and output route with current values summarized; advanced TTS settings stay in the full studio.
• Pinned phrases appear before recent phrases and can be activated without entering edit mode.
• A phrase tap loads it into the composer; a separate explicit Speak action prevents accidental speech in sensitive settings.
• An optional user preference may enable one-tap speak for pinned phrases after onboarding explains it.

Playback states

• Ready: local UI is immediately usable.
• Generating: cancellable cloud request with concise progress.
• Speaking with SpeakTrue voice: cloud artifact playing.
• Speaking with device voice: platform fallback is active and visibly distinct.
• Offline: cloud unavailable; device voice remains offered.
• Needs sign-in: cloud voice unavailable; device voice remains offered.
• Error: stable message with Retry and Use Device Voice.

Accessibility behavior

• Controls have stable accessibility labels, values, hints, and focus order.
• Dynamic Type/font scaling never hides composer, Speak, or Stop.
• Speak/Stop is reachable with switch access and external keyboards.
• Haptic and visual state changes supplement audio; they do not replace labels.
• Reduced motion removes nonessential animation.
• VoiceOver/TalkBack announces playback-state changes without repeatedly reading phrase content.
• A user can stop speech immediately from the same control position.

Speech Routing

1. If the user explicitly chooses Device Voice, synthesize locally.
2. Otherwise, if a valid cached cloud artifact exists for the exact phrase/voice/settings identity, play it.
3. Otherwise, attempt the existing protected tts-generate path.
4. On offline/auth/provider failure, offer or automatically use Device Voice according to the user’s saved fallback preference.
5. Label the active voice source and record only content-free result/fallback metadata.

Do not upload or save locally synthesized audio to Soundboard automatically. Save generated audio remains a cloud-artifact action with the existing canonical artifact contract.

Phrase Persistence

Local MVP

• Store recent/pinned phrase records in platform-protected app storage.
• Record a random local ID, text, locale hint, sort order, pin state, and timestamps.
• Cap recents and provide Clear recent phrases.
• Exclude phrase content from normal debug descriptions and state dumps.

Authenticated sync

Add quick_speak_phrases only after the local interaction is validated:

Field	Type	Notes
id	uuid	Stable shortcut/sync identity
user_id	uuid	Owner
text	text	Bounded; never emitted to telemetry
locale_code	text nullable	Device/cloud voice hint
sort_order	integer	User ordering
is_pinned	boolean	Synced pin state
preferred_voice_id	text nullable	Cloud voice preference, not a provider key
linked_clip_id	uuid nullable	Optional saved cloud artifact
timestamps	timestamptz	UTC

Use RLS for owner CRUD, a maximum phrase count, idempotent upsert, and conflict rules based on updated_at plus a client mutation ID. Local-only users never need this table.

Shortcut Contract

• iOS: App Intents/App Shortcuts entry opens Quick Speak with an owned opaque phrase ID.
• Android: static/dynamic app shortcuts open the same destination with an owned opaque phrase ID.
• Phrase text is not embedded in URLs, intents exported to other apps, analytics, or logs.
• MVP shortcuts load the phrase and require an explicit Speak action.
• Direct speak from a shortcut is a later opt-in behavior requiring device-lock, audio-route, privacy, and interruption review.
• Deleted or signed-out phrase IDs fail closed to an empty composer with a clear message.

Platform references:

• Apple App Shortcuts
• Apple AVSpeechSynthesizer
• Android app shortcuts
• Android TextToSpeech

File Ownership Map

Shared backend

• Reuse backend/supabase/functions/tts-generate/ and canonical artifact fields.
• Add a migration for quick_speak_phrases only in the sync slice.
• Add owner-scoped quick-speak-phrases-* handler/index/tests or a single resource handler with method dispatch.
• Add content-free product telemetry outside billable provider accounting.

iOS

• Add a Quick Speak feature view/view model under ios/SpeakTrue/ following current flat feature organization.
• Reuse ios/SpeakTrue/AIProxyService.swift and existing audio player behavior.
• Add a small AVSpeechSynthesizer adapter with injectable protocol for tests.
• Add App Intent types only after synced/local stable phrase IDs exist.
• Wire navigation through ios/SpeakTrue/MainTabView.swift without hiding existing studio access.

Android

• Add features/quickspeak/{data,presentation,ui} under android/app/src/main/java/com/speaktrue/.
• Reuse features/tts/data contracts where practical without coupling Quick Speak UI to TTS studio state.
• Wrap android.speech.tts.TextToSpeech behind an injectable lifecycle-aware service.
• Add shortcut declarations/updates through the app manifest and shortcut APIs.
• Wire navigation through the existing app navigation graph.

Vertical Slices

• Q01: Ship local iOS Quick Speak with cloud TTS — Risk: medium; Depends: interaction copy approval; Mode: HITL.

  Add destination, composer, Speak/Stop, local recents, existing cloud generation/playback, error states, and focused view-model/UI accessibility tests. No backend or sync changes.

  After this: an iOS user can type and speak a phrase through the familiar SpeakTrue voice path with fewer steps than the full studio.

• Q02: Ship local Android Quick Speak with cloud TTS — Risk: medium; Depends: Q01 interaction review; Mode: AFK.

  Add the parallel feature module, navigation, composer, Speak/Stop, local recents, cloud playback, tests, and the mandatory Android gate.

  After this: the same focused cloud Quick Speak flow works on Android.

• Q03: Add explicit device-voice fallback on iOS — Risk: high; Depends: Q01; Mode: HITL.

  Add the synthesizer adapter, locale/voice selection, audio-session/interrupt handling, visible fallback labeling, offline/auth failure routes, and device tests.

  After this: an iOS user can communicate with a device voice when cloud speech is unavailable.

• Q04: Add explicit device-voice fallback on Android — Risk: high; Depends: Q02; Mode: HITL.

  Add lifecycle-safe TextToSpeech initialization, language availability checks, audio focus, visible labeling, fallback preference, tests, and the Android gate.

  After this: an Android user can communicate with a device voice when cloud speech is unavailable.

• Q05: Add synced pinned phrases — Risk: high; Depends: Q01-Q04 and sync-default decision; Mode: HITL.

  Add schema/RLS/API, migration rollback, local-first synchronization, conflict handling, pin ordering, clear/delete behavior, and cross-platform sync tests.

  After this: a signed-in user’s pinned phrases follow them between iOS and Android while local-only use still works.

• Q06: Connect favorites and saved audio — Risk: medium; Depends: Library L02 and Q05; Mode: AFK.

  Allow a pinned phrase to link to an owned Soundboard clip, prefer valid cached audio, surface favorite library items as optional Quick Speak sources, and refresh expired URLs safely.

  After this: frequently reused speech can play quickly from existing saved audio while remaining editable as text.

• Q07: Add opaque-ID app shortcuts — Risk: high; Depends: Q05; Mode: HITL.

  Add iOS App Shortcuts and Android shortcuts that resolve a phrase ID, open Quick Speak, require explicit Speak, handle sign-out/deletion, and prove that phrase text is absent from URLs/logs.

  After this: a user can reach a pinned phrase from the operating system without navigating the app or leaking its text.

• Q08: Accessibility and staged-release hardening — Risk: high; Depends: Q03-Q07; Mode: HITL.

  Complete VoiceOver/TalkBack, Dynamic Type/font scale, switch/keyboard, reduced motion, audio-route, interruption, offline, lock-state, and rollback tests; release through independent flags.

  After this: Quick Speak has accessibility and reliability evidence suitable for an allowlisted then broad release.

Verification

Automated

• Unit-test routing across cloud success, cached artifact, offline, auth expiry, provider failure, fallback disabled, and fallback accepted.
• Assert telemetry payloads exclude phrase/transcript text, filenames, paths, and URLs.
• Test local recent caps, pin ordering, clear/delete, and sync conflict behavior.
• Test shortcut resolution with valid, deleted, cross-user, and signed-out IDs.
• Run focused iOS XCTest and simulator builds.
• Run focused Android tests during development and bash scripts/verify_android_ci_local.sh before commit/push.
• Run backend Deno/migration regression gates for Q05-Q07.

Manual device matrix

• airplane mode, poor network, and provider timeout;
• Bluetooth, speaker, headphones, incoming call, and app background/foreground;
• device voice missing requested locale;
• VoiceOver/TalkBack and largest supported text size;
• switch control/external keyboard;
• device locked and shortcut invoked;
• signed out after synced pins were cached;
• immediate Stop during cloud and local speech.

Acceptance Gate

• Speak/Stop remains reachable and stable at all supported text sizes.
• Local device speech works without sign-in or network when a compatible voice is installed.
• Cloud and device voices are never visually conflated.
• A shortcut contains only opaque identity and does not auto-speak in MVP.
• Phrase text is absent from telemetry, logs, URLs, and crash breadcrumbs.
• The full TTS studio remains available and unchanged.
• Quick Speak can be independently disabled without breaking TTS or Soundboard.

Rollback

Disable Quick Speak UI, fallback, and shortcuts through separate flags. Leave local phrase data intact for re-enable. Keep synced phrase schema additive and readable; do not delete user phrases during feature rollback. Existing TTS generation and Soundboard contracts remain the fallback product path.

Open Decisions

1. Whether Quick Speak is a top-level tab, home action, or both.
2. Whether pinned phrase taps speak immediately after explicit opt-in.
3. Whether synced phrases are enabled by default for signed-in users.
4. Local recent-phrase retention count and clear-on-sign-out behavior.
5. Whether a web Quick Speak surface enters this 90-day scope.
6. Whether OS Personal Voice integration is technically and policy-feasible in a later plan.