From 9169d33ab637d76fb341ee2236916dae877b71ee Mon Sep 17 00:00:00 2001 From: Bungeefan Date: Tue, 27 Jun 2023 16:49:38 +0200 Subject: [PATCH] Fixed typos and improved documentation --- speech_to_text/example/lib/main.dart | 2 +- .../lib/speech_recognition_error.dart | 2 +- .../lib/speech_recognition_result.dart | 4 +- speech_to_text/lib/speech_to_text.dart | 106 +++++++++++------- speech_to_text/lib/speech_to_text_web.dart | 4 +- .../lib/speech_to_text_macos.dart | 2 +- .../speech_to_text_platform_interface.dart | 2 +- 7 files changed, 74 insertions(+), 48 deletions(-) diff --git a/speech_to_text/example/lib/main.dart b/speech_to_text/example/lib/main.dart index fc666942..36369c4e 100644 --- a/speech_to_text/example/lib/main.dart +++ b/speech_to_text/example/lib/main.dart @@ -123,7 +123,7 @@ class _SpeechSampleAppState extends State { lastError = ''; final pauseFor = int.tryParse(_pauseForController.text); final listenFor = int.tryParse(_listenForController.text); - // Note that `listenFor` is the maximum, not the minimun, on some + // Note that `listenFor` is the maximum, not the minimum, on some // systems recognition will be stopped before this value is reached. // Similarly `pauseFor` is a maximum not a minimum and may be ignored // on some devices. diff --git a/speech_to_text/lib/speech_recognition_error.dart b/speech_to_text/lib/speech_recognition_error.dart index d76c3f81..bca555ad 100644 --- a/speech_to_text/lib/speech_recognition_error.dart +++ b/speech_to_text/lib/speech_recognition_error.dart @@ -6,7 +6,7 @@ part 'speech_recognition_error.g.dart'; /// /// Errors are either transient or permanent. Permanent errors /// block speech recognition from continuing and must be -/// addressed before recogntion will work. Transient errors +/// addressed before recognition will work. Transient errors /// cause individual recognition sessions to fail but subsequent /// attempts may well succeed. @JsonSerializable() diff --git a/speech_to_text/lib/speech_recognition_result.dart b/speech_to_text/lib/speech_recognition_result.dart index d001481f..fae15326 100644 --- a/speech_to_text/lib/speech_recognition_result.dart +++ b/speech_to_text/lib/speech_recognition_result.dart @@ -19,7 +19,7 @@ class SpeechRecognitionResult { /// value. Use the confidence for each alternate transcription /// to determine how likely it is. Note that not all platforms /// do a good job with confidence, there are convenience methods - /// on [SpeechRecogntionWords] to work with possibly missing + /// on [SpeechRecognitionWords] to work with possibly missing /// confidence values. // TODO: Fix up the interface. // List get alternates => @@ -55,7 +55,7 @@ class SpeechRecognitionResult { ? alternates.first.isConfident(threshold: threshold) : false; - /// true if [confidence] is not the [missingConfidence] value, false + /// true if [confidence] is not the [SpeechRecognitionWords.missingConfidence] value, false /// otherwise. bool get hasConfidenceRating => alternates.isNotEmpty ? alternates.first.hasConfidenceRating : false; diff --git a/speech_to_text/lib/speech_to_text.dart b/speech_to_text/lib/speech_to_text.dart index c0c1952f..868f4fdc 100644 --- a/speech_to_text/lib/speech_to_text.dart +++ b/speech_to_text/lib/speech_to_text.dart @@ -9,68 +9,88 @@ import 'package:speech_to_text/speech_recognition_error.dart'; import 'package:speech_to_text/speech_recognition_result.dart'; import 'package:speech_to_text_platform_interface/speech_to_text_platform_interface.dart'; +/// Describes the goal of your speech recognition to the system. +/// +/// Currently only supported on **iOS**. +/// +/// See also: +/// * https://developer.apple.com/documentation/speech/sfspeechrecognitiontaskhint enum ListenMode { + /// The device default. deviceDefault, + + /// When using captured speech for text entry. + /// + /// Use this when you are using speech recognition for a task that's similar to the keyboard's built-in dictation function. dictation, + + /// When using captured speech to specify search terms. + /// + /// Use this when you are using speech recognition to identify search terms. search, + + /// When using captured speech for short, confirmation-style requests. + /// + /// Use this when you are using speech recognition to handle confirmation commands, such as "yes", "no" or "maybe". confirmation, } /// A single locale with a [name], localized to the current system locale, -/// and a [localeId] which can be used in the [listen] method to choose a +/// and a [localeId] which can be used in the [SpeechToText.listen] method to choose a /// locale for speech recognition. class LocaleName { final String localeId; final String name; + LocaleName(this.localeId, this.name); } /// Notified as words are recognized with the current set of recognized words. /// -/// See the [onResult] argument on the [listen] method for use. +/// See the [onResult] argument on the [SpeechToText.listen] method for use. typedef SpeechResultListener = void Function(SpeechRecognitionResult result); -/// Notified if errors occur during recognition or intialization. +/// Notified if errors occur during recognition or initialization. /// /// Possible errors per the Android docs are described here: /// https://developer.android.com/reference/android/speech/SpeechRecognizer -/// "error_audio_error" -/// "error_client" -/// "error_permission" -/// "error_network" -/// "error_network_timeout" -/// "error_no_match" -/// "error_busy" -/// "error_server" -/// "error_speech_timeout" -/// "error_language_not_supported" -/// "error_language_unavailable" -/// "error_server_disconnected" -/// "error_too_many_requests" +/// * "error_audio_error" +/// * "error_client" +/// * "error_permission" +/// * "error_network" +/// * "error_network_timeout" +/// * "error_no_match" +/// * "error_busy" +/// * "error_server" +/// * "error_speech_timeout" +/// * "error_language_not_supported" +/// * "error_language_unavailable" +/// * "error_server_disconnected" +/// * "error_too_many_requests" /// /// iOS errors are not well documented in the iOS SDK, so far these are the /// errors that have been observed: -/// "error_speech_recognizer_disabled" -/// "error_retry" -/// "error_no_match" +/// * "error_speech_recognizer_disabled" +/// * "error_retry" +/// * "error_no_match" /// /// Both platforms use this message for an unrecognized error: -/// "error_unknown ($errorCode)" where $errorCode provides more detail - -/// See the [onError] argument on the [initialize] method for use. +/// * "error_unknown ($errorCode)" where `$errorCode` provides more detail +/// +/// See the [onError] argument on the [SpeechToText.initialize] method for use. typedef SpeechErrorListener = void Function( SpeechRecognitionError errorNotification); /// Notified when recognition status changes. /// -/// See the [onStatus] argument on the [initialize] method for use. +/// See the [onStatus] argument on the [SpeechToText.initialize] method for use. typedef SpeechStatusListener = void Function(String status); /// Notified when the sound level changes during a listen method. /// /// [level] is a measure of the decibels of the current sound on /// the recognition input. See the [onSoundLevelChange] argument on -/// the [listen] method for use. +/// the [SpeechToText.listen] method for use. typedef SpeechSoundLevelChange = Function(double level); /// An interface to device specific speech recognition services. @@ -216,6 +236,7 @@ class SpeechToText { /// /// Also goes false when listening times out if listenFor was set. bool get isListening => _listening; + bool get isNotListening => !isListening; /// The last error received or null if none, see [initialize] to @@ -242,6 +263,7 @@ class SpeechToText { /// successful, false if failed. /// /// This method must be called before any other speech functions. + /// /// If this method returns false no further [SpeechToText] methods /// should be used. Should only be called once if successful but does protect /// itself if called repeatedly. False usually means that the user has denied @@ -250,22 +272,26 @@ class SpeechToText { /// /// [onError] is an optional listener for errors like /// timeout, or failure of the device speech recognition. + /// /// [onStatus] is an optional listener for status changes. There are three /// possible status values: - /// - 'listening' when speech recognition begins after calling the [listen] - /// method; - /// - 'notListening' when speech recognition is no longer listening to the - /// microphone after a timeout, [cancel] or [stop] call; - /// - 'done' when all results have been delivered. + /// * `listening` when speech recognition begins after calling the [listen] + /// method. + /// * `notListening` when speech recognition is no longer listening to the + /// microphone after a timeout, [cancel] or [stop] call. + /// * `done` when all results have been delivered. + /// /// [debugLogging] controls whether there is detailed logging from the /// underlying platform code. It is off by default, usually only useful - /// for troubleshooting issueswith a paritcular OS version or device, + /// for troubleshooting issues with a particular OS version or device, /// fairly verbose + /// /// [finalTimeout] a duration to wait for a final result from the device /// speech recognition service. If no final result is received within this /// time the last partial result is returned as final. This defaults to /// two seconds. A duration of fifty milliseconds or less disables the /// check and final results will only be returned from the device. + /// /// [options] pass platform specific configuration options to the /// platform specific implementation. Future initialize( @@ -368,7 +394,7 @@ class SpeechToText { /// /// [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, + /// 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. /// @@ -391,8 +417,7 @@ class SpeechToText { /// /// [sampleRate] optional for compatibility with certain iOS devices, some devices /// crash with `sampleRate != device's supported sampleRate`, try 44100 if seeing - /// crashes - /// + /// crashes. Future listen( {SpeechResultListener? onResult, Duration? listenFor, @@ -489,12 +514,12 @@ class SpeechToText { _listenTimer = Timer(minDuration, _stopOnPauseOrListen); } - /// milliseconds since the last listen was started, this is used for + /// Milliseconds since the last listen was started, this is used for /// the listen for calculations int get _elapsedListenMillis => clock.now().millisecondsSinceEpoch - _listenStartedAt; - /// milliseconds since the last speech event was detected, this + /// Milliseconds since the last speech event was detected, this /// is used for the pause calculations int get _elapsedSinceSpeechEvent => clock.now().millisecondsSinceEpoch - _lastSpeechEventAt; @@ -513,7 +538,7 @@ class SpeechToText { } } - /// returns the list of speech locales available on the device or those + /// Returns the list of speech locales available on the device or those /// supported by the speech recognizer on the device. /// /// Being on this list does not guarantee that the device will be able to @@ -554,7 +579,7 @@ class SpeechToText { return filteredLocales; } - /// returns the locale that will be used if no localeId is passed + /// Returns the locale that will be used if no localeId is passed /// to the [listen] method. Future systemLocale() async { if (null == _systemLocale) { @@ -631,8 +656,8 @@ class SpeechToText { case _finalStatus: if (!_notifiedDone) return; - /// the [_finalStatus] is just to indicate that it can send the - /// [doneStatus] if [_notifiedDone] has already happened. + // the [_finalStatus] is just to indicate that it can send the + // [doneStatus] if [_notifiedDone] has already happened. status = doneStatus; break; case _doneNoResultStatus: @@ -674,11 +699,12 @@ class SpeechToText { class SpeechToTextNotInitializedException implements Exception {} /// Thrown when listen fails to properly start a speech listening session -/// on the device +/// on the device. class ListenFailedException implements Exception { final String? message; final String? details; final String? stackTrace; + ListenFailedException(this.message, [this.details, this.stackTrace]); } diff --git a/speech_to_text/lib/speech_to_text_web.dart b/speech_to_text/lib/speech_to_text_web.dart index 1efbd202..8331c0e0 100644 --- a/speech_to_text/lib/speech_to_text_web.dart +++ b/speech_to_text/lib/speech_to_text_web.dart @@ -17,7 +17,7 @@ class SpeechToTextPlugin extends SpeechToTextPlatform { bool _resultSent = false; bool _doneSent = false; - /// Registers this class as the default instance of [UrlLauncherPlatform]. + /// Registers this class as the default instance of [SpeechToTextPlatform]. static void registerWith(Registrar registrar) { SpeechToTextPlatform.instance = SpeechToTextPlugin(); } @@ -45,7 +45,7 @@ class SpeechToTextPlugin extends SpeechToTextPlatform { /// /// [debugLogging] controls whether there is detailed logging from the underlying /// plugins. It is off by default, usually only useful for troubleshooting issues - /// with a paritcular OS version or device, fairly verbose + /// with a particular OS version or device, fairly verbose @override Future initialize( {debugLogging = false, List? options}) async { diff --git a/speech_to_text_macos/lib/speech_to_text_macos.dart b/speech_to_text_macos/lib/speech_to_text_macos.dart index 1600a039..1d76a2c2 100644 --- a/speech_to_text_macos/lib/speech_to_text_macos.dart +++ b/speech_to_text_macos/lib/speech_to_text_macos.dart @@ -33,7 +33,7 @@ class SpeechToTextMacOS extends SpeechToTextPlatform { /// /// [debugLogging] controls whether there is detailed logging from the underlying /// plugins. It is off by default, usually only useful for troubleshooting issues - /// with a paritcular OS version or device, fairly verbose + /// with a particular OS version or device, fairly verbose @override Future initialize( {debugLogging = false, List? options}) async { diff --git a/speech_to_text_platform_interface/lib/speech_to_text_platform_interface.dart b/speech_to_text_platform_interface/lib/speech_to_text_platform_interface.dart index 2c8052de..db34b5a9 100644 --- a/speech_to_text_platform_interface/lib/speech_to_text_platform_interface.dart +++ b/speech_to_text_platform_interface/lib/speech_to_text_platform_interface.dart @@ -81,7 +81,7 @@ abstract class SpeechToTextPlatform extends PlatformInterface { /// /// [debugLogging] controls whether there is detailed logging from the underlying /// plugins. It is off by default, usually only useful for troubleshooting issues - /// with a paritcular OS version or device, fairly verbose + /// with a particular OS version or device, fairly verbose Future initialize( {debugLogging = false, List? options}) { throw UnimplementedError('initialize() has not been implemented.');