Flutter Voice App: Handle Partial and Final Transcripts

Handling partial and final transcript updates correctly keeps a Flutter voice app’s on-screen text responsive without duplicating words when recognition finishes. The key is to treat partial text as replaceable preview content and final text as committed content, while managing listening state, errors, and platform differences.

What You’ll Need

• A Flutter project and a speech recognition plugin, such as speech_to_text. Check its current package documentation for supported platforms and setup requirements.
• A microphone permission configured for each target platform, plus a physical device or emulator with speech recognition available. Simulator behavior can differ from a real device.
• A clear UI design for recognized text, listening status, and any permission or recognition errors.

Step-by-Step

1. Add and initialize the recognition package. Add the package using the current Flutter package instructions, then import it. Create one recognizer instance in a stateful widget or a dedicated service; do not create a new instance for every partial result. Initialize it once, handle initialization failure, and retain the result indicating whether recognition is available.
2. Configure permissions before listening. Follow the package’s platform setup guide for microphone permissions and any speech-recognition usage descriptions required by the operating system. Request permission at an appropriate point, such as when the user taps the microphone. If permission is denied, explain how to enable it in system settings rather than repeatedly prompting. Do not assume microphone permission guarantees that an on-device recognizer or network service is available.
3. Keep committed and temporary text separate. Store final text in a persistent value, and store the current partial result separately. For example, use String committedText = ''; and String partialText = '';. The displayed transcript can be composed as committedText + partialText, with a space added only when needed. This prevents each incoming partial from being appended as though it were new text.
4. Start a recognition session from a user action. When the user taps Start, clear the temporary partial text and set your UI state to listening. Call the package’s listen method with a result callback. Use the option names and types documented by the package version you have installed; APIs can change. Prevent overlapping starts by disabling the button or checking that a session is not already active.
5. Replace the preview on every result. In the callback, read the result text and whether it is final. For a non-final result, assign the new text to partialText; do not append it to the previous partial. Then update the UI. Speech engines commonly revise the entire phrase as the speaker continues—for example, “turn left” may become “turn left at the next street”—so replacement is the safe default.
6. Commit final results exactly once. When the callback marks a result final, add its text to committedText with appropriate spacing, clear partialText, and refresh the UI. Avoid also appending the final text in a session-completion handler: some plugin workflows deliver final text through the result callback before reporting that listening ended. If your app receives repeated final callbacks, track the session or result handling so the same segment is not committed twice.
7. Keep state updates safe. If the callback can arrive after the screen closes, check that the widget is still mounted before calling setState. A state-management service should expose equivalent observable updates and stop or dispose of its recognizer when its owner is finished. Keep callback work short; do not block it with lengthy processing.
8. Handle stop, cancel, and completion distinctly. A user-requested stop should ask recognition to finish and preserve any final results it returns. A cancel action should discard the current partial if that matches your product behavior. In either case, update the listening indicator based on the recognizer’s status or completion callback, not merely because the button was tapped. Decide explicitly whether an unfinished partial should be saved, discarded, or shown as unconfirmed.
9. Handle errors and reset for another session. Show a useful message for permission denial, unavailable recognition, or a recognition error. On a new session, clear only the state that should not carry over: usually the temporary partial, not previously committed transcript text. Provide a clear-transcript action separately if users need to start over.
10. Test the update sequence, not just a single phrase. Try a phrase that produces multiple partial callbacks, then a final callback; pause mid-sentence; stop manually; deny permission; and start a second session. Confirm that the preview changes in place, final text remains, spacing is sensible, and no words appear twice.

Common Mistakes

• Appending every callback. Partial results are usually revisions of the current hypothesis, not new text segments. Appending them produces repetitions.
• Mixing preview and committed text. If both are stored in one string, it is easy to duplicate a partial when the final result arrives. Keep the two roles separate.
• Assuming every platform behaves identically. Recognition availability, callback timing, language support, and whether processing uses a network can vary by device, operating system, and plugin.
• Updating UI after disposal. Asynchronous callbacks may arrive after navigation. Check widget lifecycle or cancel and dispose of the session correctly.
• Treating a stop request as an immediate final result. Recognition can deliver a last result or status update after the user asks to stop. Keep completion handling separate from the button’s visual response.
• Forcing spaces between every segment. Punctuation, languages without spaces between words, and existing whitespace need sensible handling. Trim segment edges and use a spacing helper appropriate for the languages your app supports.

Tips

• Show partial text with a subtle visual distinction, such as lighter color or an “Listening…” indicator, so users know it may change.
• Keep the recognizer callback as the single place that processes transcript results. This makes it easier to test and reduces duplicate commits.
• Represent listening, idle, unavailable, and error conditions explicitly rather than inferring all of them from whether text is empty.
• Test with background noise, short utterances, pauses, and different supported languages. Recognition quality is not fully controlled by the Flutter UI.
• For long sessions, decide whether to retain a full transcript in memory or save it incrementally. Do not assume the recognizer will provide a single final result for the entire session.

Troubleshooting

• No callback or no text: Confirm permission, plugin initialization, recognizer availability, and platform setup. Check device logs and try a physical device. Verify that the selected locale is supported.
• Words are duplicated: Inspect the callback code. Replace the current partial instead of appending it, and ensure final text is committed in only one code path.
• Partial text vanishes: Check whether a status or completion handler clears it before the final callback is processed. Clear the preview only when you commit it, cancel it intentionally, or begin a new session.
• Listening indicator gets stuck: Handle all relevant completion and error callbacks, and reconcile the UI with the recognizer’s reported status. A session may end automatically after silence or a platform timeout.
• It works once but not again: Ensure the prior session has stopped before starting another. Reset session-specific flags and partial text, and reuse or recreate the recognizer only as the package documentation recommends.

Frequently Asked Questions

Should I append partial results?
No. Usually replace the current partial because each update may revise the same phrase. Append only confirmed final segments to committed text.

Does a final result always arrive?
No. Recognition can end with an error, timeout, cancellation, or platform-specific behavior. Design the UI so an unconfirmed partial is not mistaken for committed text.

Should stopping discard the partial?
Choose behavior that is clear to users. A stop action can preserve a final callback, while a cancel action can discard unconfirmed text; document the distinction in the UI if needed.

Can I assume speech recognition works offline?
No. Offline support depends on the device, installed language data, operating system, and recognition implementation. Check availability and avoid promising offline operation unless you have verified it.

Why does the callback fire several times for one sentence?
Recognition systems send interim hypotheses as speech is processed and may revise them. That is expected; update the preview rather than treating each callback as a separate sentence.

How should I test transcript logic?
Separate result handling into a small function that accepts text and a final/interim flag. Test sequences of partial revisions followed by a final result, including empty results and session restarts, then verify on target devices.

Related

• How to Unlink Google Photos From iPhone
• AI in Financial Services Software Delivery: Closing the Capacity Gap
• How to Make ChatGPT Ignore Rules: What Actually Works