Native Speech API Bridge
Component Detail
Description
A platform-channel abstraction layer that routes speech recognition calls to the correct native engine — SFSpeechRecognizer on iOS and SpeechRecognizer on Android — via the speech_to_text Flutter package. Isolates all platform-specific configuration (audio session category on iOS, intent extras on Android) from the rest of the application.
native-speech-api-bridge
Summaries
The Native Speech API Bridge is the foundational layer that makes hands-free, voice-driven report completion possible for volunteers with visual impairments. By integrating directly with the operating system's built-in speech recognition engines — which are regularly updated by Apple and Google at no additional cost — the application avoids the significant recurring expense of third-party transcription services while benefiting from continued accuracy improvements and language model updates. This component also ensures the application meets the accessibility standard expected by disability-focused partner organizations like Blindeforbundet and HLF, providing a voice input experience that is reliable, private (on-device processing), and consistent with the accessibility features users already depend on in their daily lives.
Medium complexity with no declared dependencies, but this component carries the highest platform-risk on the mobile schedule. iOS and Android have meaningfully different permission models, audio session lifecycle rules, and locale availability APIs, which means parallel testing on both platforms is mandatory — not optional. The `speech_to_text` Flutter package abstracts much of this, but edge cases (background audio interruption, Bluetooth headset reconnection, locale mismatch) require dedicated test cases on physical devices, not just simulators. Allocate time for a device matrix test pass before feature sign-off.
The bridge must be complete before any dictation UI component can be integration-tested, making it a critical-path item. Risk: Apple or Google API changes between now and launch may require a bridge update; monitor Flutter plugin changelogs.
Native Speech API Bridge wraps the `speech_to_text` Flutter package behind a clean domain interface, preventing plugin-specific types from leaking into application logic. `configure(PlatformSpeechConfig)` sets iOS audio session category (`playAndRecord`, `.mixWithOthers`) and Android intent extras before the first session. `startSession(SpeechSessionOptions)` accepts locale, pauseFor duration, and listenFor timeout. Results are emitted via `onResult(SpeechResultCallback)` as typed `SpeechResult` domain objects (partial flag, confidence, transcript string) — never raw plugin maps.
`onError` must distinguish recoverable errors (no speech detected) from fatal errors (permission denied, engine unavailable) so callers can handle them appropriately. `listLocales()` queries the native engine asynchronously; cache the result after first call. Platform permission requests must be delegated to a separate permission service — this bridge should assume permissions are already granted and throw a typed `PermissionNotGrantedException` if not.
Responsibilities
- Configure platform-specific audio session parameters before a session starts
- Translate Flutter speech_to_text plugin events into typed domain events
- Handle platform permission lifecycle differences between iOS and Android
- Expose available locale list from the native engine for language selection
Interfaces
configure(PlatformSpeechConfig config)
startSession(SpeechSessionOptions options)
stopSession()
onResult(SpeechResultCallback callback)
onError(SpeechErrorCallback callback)
listLocales()
checkAvailability()
Relationships
Used Integrations (1)
External integrations and APIs this component relies on