yx_speech_to_text_flutter/doc/api_reference.md

YX ASR API Reference

This document provides detailed API reference for the YX ASR Flutter plugin.

Table of Contents

• YxAsr Class
• SpeechRecognitionResult
• SpeechRecognitionError
• RecordingButton Widget
• Error Types
• Usage Examples

YxAsr Class

The main class for speech-to-text functionality.

Constructor

YxAsr()

Returns the singleton instance of YxAsr.

Methods

initialize()

Future<bool> initialize()

Initializes the speech recognition service. This method checks availability and requests permission if needed.

Returns: true if speech recognition is ready to use, false otherwise.

Example:

final speechToText = YxAsr();
bool initialized = await speechToText.initialize();

isAvailable()

Future<bool> isAvailable()

Checks if speech recognition is available on the device.

Returns: true if speech recognition is supported and available, false otherwise.

hasPermission()

Future<bool> hasPermission()

Checks if microphone permission is currently granted.

Returns: true if permission is granted, false otherwise.

requestPermission()

Future<bool> requestPermission()

Requests microphone permission from the user. On some platforms, this may show a permission dialog.

Returns: true if permission is granted, false otherwise.

startListening()

Future<void> startListening({
  String localeId = 'en-US',
  bool partialResults = true,
  bool onDevice = false,
})

Starts listening for speech input.

Parameters:

• localeId (String): The locale for speech recognition (e.g., 'en-US', 'zh-CN'). Default: 'en-US'
• partialResults (bool): Whether to return partial/interim results during recognition. Default: true
• onDevice (bool): Whether to use on-device recognition (iOS only, ignored on Android). Default: false

Throws: PlatformException if speech recognition fails to start.

stopListening()

Future<void> stopListening()

Stops listening for speech input. This will finalize the current recognition session and return the final result through the onResult stream.

cancel()

Future<void> cancel()

Cancels the current speech recognition session. This immediately stops recognition without returning a final result.

isListening

Future<bool> get isListening

Returns true if currently listening for speech, false otherwise.

Streams

onResult

Stream<SpeechRecognitionResult> get onResult

Stream of speech recognition results. This stream emits SpeechRecognitionResult objects containing recognized text, confidence level, and whether the result is final or interim.

onError

Stream<SpeechRecognitionError> get onError

Stream of speech recognition errors. This stream emits SpeechRecognitionError objects when errors occur during speech recognition.

onListeningStatusChanged

Stream<bool> get onListeningStatusChanged

Stream of listening status changes. This stream emits true when speech recognition starts listening and false when it stops listening.

SpeechRecognitionResult

Represents the result of speech recognition.

Properties

class SpeechRecognitionResult {
  final String recognizedWords;    // The recognized text
  final bool finalResult;          // Whether this is a final result or partial/interim result
  final double confidence;         // Confidence level of the recognition (0.0 to 1.0)
  final List<String> alternatives; // Alternative recognition results
}

Methods

fromMap()

factory SpeechRecognitionResult.fromMap(Map<String, dynamic> map)

Creates a SpeechRecognitionResult from a map.

toMap()

Map<String, dynamic> toMap()

Converts this result to a map.

SpeechRecognitionError

Represents an error that occurred during speech recognition.

Properties

class SpeechRecognitionError {
  final SpeechRecognitionErrorType errorType; // The type of error
  final String errorMsg;                      // Human-readable error message
  final String? errorCode;                    // Platform-specific error code (optional)
}

Methods

fromMap()

factory SpeechRecognitionError.fromMap(Map<String, dynamic> map)

Creates a SpeechRecognitionError from a map.

toMap()

Map<String, dynamic> toMap()

Converts this error to a map.

RecordingButton Widget

A customizable recording button widget for speech-to-text functionality.

Constructor

const RecordingButton({
  Key? key,
  this.onResult,
  this.onError,
  this.onListeningStatusChanged,
  this.localeId = 'en-US',
  this.partialResults = true,
  this.onDevice = false,
  this.size = 80.0,
  this.idleColor,
  this.recordingColor,
  this.disabledColor,
  this.idleIcon,
  this.recordingIcon,
  this.iconSize,
  this.decoration,
  this.enabled = true,
  this.tooltip,
})

Properties

• onResult (Function(SpeechRecognitionResult)?): Callback called when speech recognition results are received
• onError (Function(SpeechRecognitionError)?): Callback called when speech recognition errors occur
• onListeningStatusChanged (Function(bool)?): Callback called when listening status changes
• localeId (String): The locale for speech recognition. Default: 'en-US'
• partialResults (bool): Whether to return partial/interim results. Default: true
• onDevice (bool): Whether to use on-device recognition (iOS only). Default: false
• size (double): The size of the button. Default: 80.0
• idleColor (Color?): The color of the button when not recording
• recordingColor (Color?): The color of the button when recording
• disabledColor (Color?): The color of the button when disabled
• idleIcon (IconData?): The icon to show when not recording
• recordingIcon (IconData?): The icon to show when recording
• iconSize (double?): The size of the icon
• decoration (Decoration?): Custom decoration for the button
• enabled (bool): Whether the button is enabled. Default: true
• tooltip (String?): Tooltip text for the button

Error Types

enum SpeechRecognitionErrorType {
  network,           // Network error occurred during recognition
  audio,             // Audio recording error
  service,           // Speech recognition service error
  permissionDenied,  // Permission denied (microphone access)
  notAvailable,      // Speech recognition not available on device
  cancelled,         // Recognition was cancelled by user
  noSpeech,          // No speech detected
  unknown,           // Unknown error
}

Usage Examples

Basic Speech Recognition

final speechToText = YxAsr();

// Initialize
bool initialized = await speechToText.initialize();
if (!initialized) return;

// Listen for results
speechToText.onResult.listen((result) {
  print('Recognized: ${result.recognizedWords}');
  print('Final: ${result.finalResult}');
  print('Confidence: ${result.confidence}');
});

// Listen for errors
speechToText.onError.listen((error) {
  print('Error: ${error.errorMsg}');
});

// Start listening
await speechToText.startListening(
  localeId: 'en-US',
  partialResults: true,
);

// Stop listening
await speechToText.stopListening();

Using RecordingButton

RecordingButton(
  onResult: (result) {
    setState(() {
      recognizedText = result.recognizedWords;
    });
  },
  onError: (error) {
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('Error'),
        content: Text(error.errorMsg),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: Text('OK'),
          ),
        ],
      ),
    );
  },
  localeId: 'zh-CN',
  size: 100.0,
  recordingColor: Colors.red,
  idleColor: Colors.blue,
)

Error Handling

speechToText.onError.listen((error) {
  switch (error.errorType) {
    case SpeechRecognitionErrorType.permissionDenied:
      // Request permission again
      await speechToText.requestPermission();
      break;
    case SpeechRecognitionErrorType.network:
      // Show network error message
      showNetworkError();
      break;
    case SpeechRecognitionErrorType.noSpeech:
      // Prompt user to speak
      showSpeakPrompt();
      break;
    default:
      // Handle other errors
      showGenericError(error.errorMsg);
  }
});