Implement Android SpeechRecognizer platform bridge
epic-speech-to-text-input-foundation-task-008 — Implement the Android-specific NativeSpeechApiBridge using Flutter MethodChannel to invoke android.speech.SpeechRecognizer via native Kotlin plugin code. Handle: RECORD_AUDIO permission request via ActivityResultContracts, RecognitionListener lifecycle events, partial results via RESULTS_RECOGNITION with UNSTABLE_TEXT, recognition intent configuration for Norwegian locale (nb-NO), and RecognizerIntent.ACTION_RECOGNIZE_SPEECH setup.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Implement in android/src/main/kotlin/SpeechPlugin.kt as a FlutterPlugin. Use the same MethodChannel and EventChannel names as the iOS implementation for symmetry. SpeechRecognizer must be created on the main thread — use mainLooper when initializing. For permission requests: since ActivityResultContracts requires an Activity, store a reference to the FlutterActivity and use ActivityCompat.requestPermissions with a request code, handling the result in onRequestPermissionsResult forwarded from the Activity.
Alternatively, use the newer ActivityPluginBinding approach with ActivityResultLauncher. The UNSTABLE_TEXT key is only available in API 23+ — add a null check. Be aware that Android's built-in SpeechRecognizer has a ~60-second timeout and will auto-stop — handle this in onEndOfSpeech and treat it as a final result. For nb-NO: EXTRA_LANGUAGE='nb-NO', EXTRA_LANGUAGE_MODEL=LANGUAGE_MODEL_FREE_FORM, EXTRA_MAX_RESULTS=1.
Testing Requirements
Write flutter_test integration tests using mock MethodChannel handlers simulating all RecognitionListener callback paths: (1) onReadyForSpeech → onPartialResults with nb-NO text → onResults (happy path), (2) onError with ERROR_NETWORK, (3) onError with ERROR_NO_MATCH, (4) onError with ERROR_INSUFFICIENT_PERMISSIONS, (5) stopRecognition called during active recognition. Verify destroy() is called after stop via mock call log assertions. Run on an Android emulator API 30+ with Google Play Services for recognition availability. Manual QA on a physical device with Norwegian speech input must confirm nb-NO locale accuracy.
iOS 15 on-device speech recognition has a 1-minute session limit and requires network fallback for longer sessions. Peer mentor way-forward dictation may routinely exceed this limit, causing silent truncation of transcribed content without user feedback.
Mitigation & Contingency
Mitigation: Implement session-chunking logic in NativeSpeechApiBridge that automatically restarts recognition before the limit is reached, preserving continuity via partial concatenation. Document the iOS 15 vs iOS 16 on-device recognition behaviour difference in code comments.
Contingency: If chunking causes user-visible interruptions, surface a non-blocking informational banner on iOS 15 devices informing users that very long dictation sessions may need to be broken into segments, and use PartialTranscriptionRepository to persist each chunk immediately.
On iOS, speech recognition permission can only be requested once. If the user denies the permission, the app cannot re-request it. A poor first-impression permission flow will permanently disable dictation for those users, impacting the Blindeforbundet blind-user base who rely on dictation most.
Mitigation & Contingency
Mitigation: Design the NativeSpeechApiBridge permission flow to show a clear pre-permission rationale screen before the OS dialog. Implement a graceful degradation path that hides the microphone button and shows a settings deep-link when permission is permanently denied.
Contingency: If users have already denied permission before the rationale screen is added, provide a settings deep-link in DictationScopeGuard's denial message directing users to iOS Settings > Privacy > Speech Recognition to re-enable manually.
The approved field IDs and screen routes configuration in DictationScopeGuard may fall out of sync with the actual report form schema as new fields are added by org administrators, silently blocking dictation on legitimately approved fields.
Mitigation & Contingency
Mitigation: Source the approved field configuration from the same org-field-config-loader used by the report form, rather than a hardcoded list. Add a developer-time assertion that logs a warning when a dictation-eligible field type is rendered but not in the approved routes map.
Contingency: Provide a runtime override mechanism in the scope guard that coordinators or admins can use to temporarily whitelist a field ID while the config is updated, with an automatic expiry.