listen method
- SpeechResultListener? onResult,
- Duration? listenFor,
- Duration? pauseFor,
- String? localeId,
- SpeechSoundLevelChange? onSoundLevelChange,
- @Deprecated('Use SpeechListenOptions.cancelOnError instead') dynamic cancelOnError = false,
- @Deprecated('Use SpeechListenOptions.partialResults instead') dynamic partialResults = true,
- @Deprecated('Use SpeechListenOptions.onDevice instead') dynamic onDevice = false,
- @Deprecated('Use SpeechListenOptions.listenMode instead') ListenMode listenMode = ListenMode.confirmation,
- @Deprecated('Use SpeechListenOptions.sampleRate instead') dynamic sampleRate = 0,
- 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);
}
}