listen method

Future listen(
  1. {SpeechResultListener? onResult,
  2. Duration? listenFor,
  3. Duration? pauseFor,
  4. String? localeId,
  5. SpeechSoundLevelChange? onSoundLevelChange,
  6. @Deprecated('Use SpeechListenOptions.cancelOnError instead') dynamic cancelOnError = false,
  7. @Deprecated('Use SpeechListenOptions.partialResults instead') dynamic partialResults = true,
  8. @Deprecated('Use SpeechListenOptions.onDevice instead') dynamic onDevice = false,
  9. @Deprecated('Use SpeechListenOptions.listenMode instead') ListenMode listenMode = ListenMode.confirmation,
  10. @Deprecated('Use SpeechListenOptions.sampleRate instead') dynamic sampleRate = 0,
  11. SpeechListenOptions? listenOptions}
)

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. The system may impose a shorter maximum listen due to resource limitations or other reasons. The plugin ensures that listening is no longer than this but it may be shorter.

pauseFor sets the maximum duration of a pause in speech with no words detected, after that it automatically stops the listen for you. On some systems, notably Android, there is a system imposed pause of from one to three seconds that cannot be overridden. The plugin ensures that the pause is no longer than the pauseFor value but it may be shorter.

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 Android 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. Deprecated use listenOptions.partialResults instead.

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. Deprecated use listenOptions.onDevice instead.

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. Deprecated use listenOptions.listenMode instead.

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

listenOptions used to specify the options to use for the listen session. See SpeechListenOptions for details.

Implementation

Future listen(
    {SpeechResultListener? onResult,
    Duration? listenFor,
    Duration? pauseFor,
    String? localeId,
    SpeechSoundLevelChange? onSoundLevelChange,
    @Deprecated('Use SpeechListenOptions.cancelOnError instead')
    cancelOnError = false,
    @Deprecated('Use SpeechListenOptions.partialResults instead')
    partialResults = true,
    @Deprecated('Use SpeechListenOptions.onDevice instead') onDevice = false,
    @Deprecated('Use SpeechListenOptions.listenMode instead')
    ListenMode listenMode = ListenMode.confirmation,
    @Deprecated('Use SpeechListenOptions.sampleRate instead') sampleRate = 0,
    SpeechListenOptions? listenOptions}) async {
  if (!_initWorked) {
    throw SpeechToTextNotInitializedException();
  }
  _lastError = null;
  _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,
        options: listenOptions);
    if (started) {
      _listenStartedAt = clock.now().millisecondsSinceEpoch;
      _lastSpeechEventAt = _listenStartedAt;
      _setupListenAndPause(pauseFor, listenFor);
    }
  } on PlatformException catch (e) {
    throw ListenFailedException(e.message, e.details, e.stacktrace);
  }
}