listen method

Future listen({ SpeechResultListener? onResult, Duration? listenFor, Duration? pauseFor, String? localeId, SpeechSoundLevelChange? onSoundLevelChange, dynamic cancelOnError = false, dynamic partialResults = true, dynamic onDevice = false, ListenMode listenMode = ListenMode.confirmation, dynamic sampleRate = 0, })

Starts a listening session for speech and converts it to text, invoking the provided onResult method as words are recognized.

Cannot be used until a successful initialize call. There is a time limit on listening imposed by both Android and iOS. The time depends on the device, network, etc. Android is usually quite short, especially if there is no active speech event detected, on the order of ten seconds or so.

When listening is done always invoke either cancel or stop to end the session, even if it times out. cancelOnError provides an automatic way to ensure this happens.

onResult is an optional listener that is notified when words are recognized.

listenFor sets the maximum duration that it will listen for, after that it automatically stops the listen for you.

pauseFor sets the maximum duration of a pause in speech with no words detected, after that it automatically stops the listen for you.

localeId is an optional locale that can be used to listen in a language other than the current system default. See locales to find the list of supported languages for listening.

onSoundLevelChange is an optional listener that is notified when the sound level of the input changes. Use this to update the UI in response to more or less input. The values currently differ between Ancroid and iOS, haven't yet been able to determine from the Android documentation what the value means. On iOS the value returned is in decibels.

cancelOnError if true then listening is automatically canceled on a permanent error. This defaults to false. When false cancel should be called from the error handler.

partialResults if true the listen reports results as they are recognized, when false only final results are reported. Defaults to true.

onDevice if true the listen attempts to recognize locally with speech never leaving the device. If it cannot do this the listen attempt will fail. This is usually only needed for sensitive content where privacy or security is a concern.

listenMode tunes the speech recognition engine to expect certain types of spoken content. It defaults to ListenMode.confirmation which is the most common use case, words or short phrases to confirm a command. ListenMode.dictation is for longer spoken content, sentences or paragraphs, while ListenMode.search expects a sequence of search terms.

sampleRate optional for compatibility with certain iOS devices, some devices crash with sampleRate != device's supported sampleRate, try 44100 if seeing crashes

Implementation

Future listen(
    {SpeechResultListener? onResult,
    Duration? listenFor,
    Duration? pauseFor,
    String? localeId,
    SpeechSoundLevelChange? onSoundLevelChange,
    cancelOnError = false,
    partialResults = true,
    onDevice = false,
    ListenMode listenMode = ListenMode.confirmation,
    sampleRate = 0}) async {
  if (!_initWorked) {
    throw SpeechToTextNotInitializedException();
  }
  _lastRecognized = '';
  _userEnded = false;
  _lastSpeechResult = null;
  _cancelOnError = cancelOnError;
  _recognized = false;
  _notifiedFinal = false;
  _notifiedDone = false;
  _resultListener = onResult;
  _soundLevelChange = onSoundLevelChange;
  _partialResults = partialResults;
  _notifyFinalTimer?.cancel();
  _notifyFinalTimer = null;
  try {
    var started = await SpeechToTextPlatform.instance.listen(
        partialResults: partialResults || null != pauseFor,
        onDevice: onDevice,
        listenMode: listenMode.index,
        sampleRate: sampleRate,
        localeId: localeId);
    if (started) {
      _listenStartedAt = clock.now().millisecondsSinceEpoch;
      _lastSpeechEventAt = _listenStartedAt;
      _setupListenAndPause(pauseFor, listenFor);
    }
  } on PlatformException catch (e) {
    throw ListenFailedException(e.message, e.details, e.stacktrace);
  }
}