speech_to_text

The speech_to_text library provides a Flutter interface to access device-specific speech recognition capabilities. It is designed for recognizing commands and short phrases rather than continuous spoken conversion or always-on listening.

Supported platforms:

• Android
• iOS
• Web

This project uses a federated plugin architecture to support multiple platforms. It is split into two main components:

1. Plugin (speech_to_text): Contains the actual implementation code for native platforms (iOS, Android, and Web).
2. Platform Interface (speech_to_text_platform_interface): Defines the required behavior and API contract that each host platform must implement.

To implement this plugin for a new platform, you must implement the interface defined in speech_to_text_platform_interface.

The speech_to_text plugin is currently designed for short, intermittent use (e.g., single voice commands or responding to a specific question). It is not designed for continuous, long-form speech recognition.

Key Limitations:

• Android/iOS Constraints: Current Android and iOS speech recognition capabilities do not support a continuous mode through this plugin.
• Timeouts: Android has a very short timeout when a speaker pauses (often less than 5 seconds).
• Duration Limits: On iOS, the framework may stop tasks that last longer than one minute to save battery and network usage.

Recommended Alternatives:

• For voice assistants: Integrate with the device's existing assistant capabilities.
• For text dictation: Use the system keyboard's built-in dictation features.

The speech_to_text plugin follows a specific lifecycle to manage device resources:

1. Initialization: Call initialize() once. This sets up the platform-specific speech recognition service and registers your onStatus and onError listeners.
2. Listening: Call listen(onResult: ...) to start a recognition session. This method accepts a callback that returns SpeechRecognitionResult objects as words are recognized.
3. Stopping/Canceling: Use stop() to end the session gracefully or cancel() to abort it. Note that platforms may enforce their own timeouts.
4. State Monitoring: Use properties like isListening and isNotListening to manage your UI state (e.g., showing/hiding a microphone icon).

To recognize text from the microphone, import the package and follow the lifecycle: initialize the plugin, check for availability, and then call listen.

Note: The initialize method should only be called once per application session. Subsequent calls to initialize are ignored, and you cannot reset the onStatus or onError callbacks after the first call. It is recommended to maintain a single instance of the plugin throughout your app's lifecycle.

import 'package:speech_to_text/speech_to_text.dart' as stt;

stt.SpeechToText speech = stt.SpeechToText();
bool available = await speech.initialize(
  onStatus: statusListener, 
  onError: errorListener
);

if (available) {
  speech.listen(onResult: resultListener);
} else {
  print("The user has denied the use of speech recognition.");
}

// some time later...
speech.stop();

The repository includes two primary examples to demonstrate usage:

• Basic Usage: The main example app shows the fundamental way to interact with the plugin.
• Provider Integration: The Provider example demonstrates how to integrate the plugin using the Flutter Provider state management pattern.

Note: These examples use relative path dependencies and require the plugin source to be checked out locally to run; they are not intended to work with the version published on pub.dev.

To change the launch screen image for the iOS version of the audio_player_interaction example, you can use one of two methods:

1. Direct File Replacement: Replace the existing image files directly within the examples/audio_player_interaction/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.
2. Xcode Interface:
   • Open the iOS project in Xcode using the command: open ios/Runner.xcworkspace.
   • In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
   • Drag and drop your desired images into the asset catalog to replace the launch images.

To use speech recognition on iOS or macOS, you must add usage descriptions to your Info.plist file located at <project root>/ios/Runner/Info.plist:

• NSSpeechRecognitionUsageDescription: A description of why your app uses speech recognition.
• NSMicrophoneUsageDescription: A description of why your app needs microphone access.

macOS Specifics:

• If running via VSCode, the app may crash when requesting permissions due to a known Flutter issue. To test permissions, run the app directly from Xcode.
• When upgrading an existing macOS app, run these commands to refresh dependencies:

  flutter clean
  flutter pub get
  cd macos
  pod install

Add the following permissions to your AndroidManifest.xml located at <project root>/android/app/src/main/AndroidManifest.xml.

Standard Permissions

<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

Android SDK 30 or later

If your targetSDKVersion is 30 or higher, you must also add a <queries> block after the permissions section to allow the app to interact with the system's recognition service:

<queries>
    <intent>
        <action android:name="android.speech.RecognitionService" />
    </intent>
</queries>

To create a new platform-specific implementation (e.g., for a new OS or hardware) for the speech_to_text plugin, you must extend the SpeechToTextPlatform class. Once your implementation is ready, you must register it as the default platform by assigning it to the SpeechToTextPlatform.instance property during plugin registration.

Follow these steps:

1. Create a class that extends SpeechToTextPlatform.
2. Implement the required platform-specific behavior.
3. Register the implementation using SpeechToTextPlatform.instance = YourImplementation().

// 1. Extend the interface
class MyPlatformSpeechToText extends SpeechToTextPlatform {
  // Implement platform-specific behavior here
}

// 2. Register the implementation
void registerWith() {
  SpeechToTextPlatform.instance = MyPlatformSpeechToText();
}