🏠 Overview › ✅ Implementation Tasks ›✅ epic-speech-to-text-input-speech-engine-task-010

Register service in dependency injection and document public API

epic-speech-to-text-input-speech-engine-task-010 — Register SpeechRecognitionService in the Riverpod provider graph as a singleton scoped to the dictation feature. Write DartDoc comments on all public methods and event types. Produce a brief integration guide (inline comments or a code example file) describing how TranscriptionStateManager should subscribe to the event stream, including recommended error handling patterns for consumers.

high priority low complexity documentation pending documentor Tier 9

Acceptance Criteria

A Riverpod Provider (e.g., speechRecognitionServiceProvider) is declared and typed as SpeechRecognitionService; it must be a singleton (keepAlive: true or scoped to a ProviderScope wrapping the dictation feature subtree)
The provider file is co-located with or clearly referenced from the SpeechRecognitionService source file; no orphaned provider declarations in unrelated files
Every public method on SpeechRecognitionService has a DartDoc comment with: a one-line summary, @param annotations for each parameter, @returns description for non-void methods, and @throws / error-stream description for error conditions
Every public event type (SpeechStarted, PartialResult, FinalResult, RecognitionError, SessionInterrupted) has a DartDoc comment explaining when it is emitted and what payload it carries
An integration guide exists as either a code example file (e.g., speech_recognition_service_example.dart) or detailed inline comments on the provider; it must cover: obtaining the provider, subscribing to the event stream, handling PartialResult vs FinalResult, and recommended patterns for disposing the subscription
The guide explicitly documents that DictationScopeGuard validation must be performed before calling startRecognition(), and that consumers must not activate the microphone outside post-activity contexts
Running flutter analyze on the changed files produces zero new warnings or errors
A colleague unfamiliar with the speech engine can integrate TranscriptionStateManager with SpeechRecognitionService using only the DartDoc and integration guide, without reading the implementation

Technical Requirements

frameworks
Flutter
Riverpod (flutter_riverpod)
apis
speech_to_text Flutter Package (iOS SFSpeechRecognizer / Android SpeechRecognizer)
performance requirements
Provider instantiation must be lazy — the underlying platform speech engine must not be initialised until the provider is first read
Singleton scope must prevent duplicate platform channel registrations
security requirements
DictationScopeGuard usage must be prominently documented — integration guide must warn that microphone cannot be activated during sensitive peer conversations
Audio never uploaded to third-party servers; document that on-device recognition is the required approach
Accessibility: screen reader announcement on recording start/stop must be called out in DartDoc as a required side-effect for accessibility compliance

Execution Context

Execution Tier
Tier 9

Tier 9 - 22 tasks

Can start after Tier 8 completes

Implementation Notes

Declare the provider in a dedicated providers file (e.g., lib/features/dictation/providers/speech_recognition_providers.dart) following the project's existing Riverpod provider file convention. Use Provider with .autoDispose omitted (singleton). If the project uses a ProviderScope override for testing, document this in the guide so consumers can inject a mock. For the integration guide, prefer a runnable Dart snippet over prose — show the full subscription lifecycle including StreamSubscription.cancel() in dispose().

DartDoc style should match the existing codebase style; use triple-slash comments (///) and avoid redundant @author tags. Ensure the guide mentions that SpeechRecognitionService is not safe to call from a background isolate.

Testing Requirements

Unit tests are not the primary deliverable for this documentation task, but a compile-time smoke test is required: the integration guide's code example file must compile without errors (dartanalyzer clean). Write one widget test or unit test that reads the speechRecognitionServiceProvider from a ProviderContainer and asserts it returns a non-null SpeechRecognitionService instance, confirming DI registration is valid. Total new test coverage target: 1 test, 100% pass rate.

Component
Speech Recognition Service
service high
Dependencies (1)
Write integration tests using flutter_test that exercise SpeechRecognitionService end-to-end against a fake NativeSpeechApiBridge that simulates realistic platform response sequences: successful Norwegian transcription, mid-session network drop, engine unavailable on cold start, and back-to-back session requests. Validate event ordering and stream completion. epic-speech-to-text-input-speech-engine-task-009
Epic Risks (2)
medium impact medium prob technical

The speech_to_text Flutter package delegates accuracy entirely to the OS-native engine. Norwegian accuracy for domain-specific vocabulary (medical terms, organisation names, accessibility terminology) may fall below the 85% acceptance threshold on older devices or in noisy environments, causing user frustration and manual correction overhead that negates the time saving.

Mitigation & Contingency

Mitigation: Configure the SpeechRecognitionService with Norwegian as the explicit locale and test against a representative corpus of peer mentoring vocabulary on target devices. Expose locale switching so users can fallback to Bokmål vs Nynorsk. Clearly set user expectations in the UI that transcription is a starting point for editing, not a finished product.

Contingency: If accuracy is consistently below threshold on specific device/OS combinations, add a device-capability check that hides the dictation button with an explanatory message rather than offering a degraded experience. Document affected device models for QA and org contacts.

medium impact low prob dependency

The speech_to_text Flutter package is a third-party dependency that may introduce breaking API changes or deprecations on major version upgrades, requiring rework of SpeechRecognitionService when Flutter or platform OS versions are updated.

Mitigation & Contingency

Mitigation: Wrap all speech_to_text API calls behind the SpeechRecognitionService interface so that package changes are isolated to one file. Pin the package version in pubspec.yaml and review changelogs before any upgrade. Write integration tests that exercise the package contract so regressions are caught immediately.

Contingency: If the package is abandoned or has unresolvable issues, NativeSpeechApiBridge already provides the platform-channel abstraction needed to implement a direct plugin replacement with minimal changes to SpeechRecognitionService.

Quick Links
All Tasks Execution Plan