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](#yxasr-class)
- [SpeechRecognitionResult](#speechrecognitionresult)
- [SpeechRecognitionError](#speechrecognitionerror)
- [RecordingButton Widget](#recordingbutton-widget)
- [Error Types](#error-types)
- [Usage Examples](#usage-examples)

## YxAsr Class

The main class for speech-to-text functionality.

### Constructor

```dart
YxAsr()
```

Returns the singleton instance of YxAsr.

### Methods

#### initialize()

```dart
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:**
```dart
final speechToText = YxAsr();
bool initialized = await speechToText.initialize();
```

#### isAvailable()

```dart
Future<bool> isAvailable()
```

Checks if speech recognition is available on the device.

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

#### hasPermission()

```dart
Future<bool> hasPermission()
```

Checks if microphone permission is currently granted.

**Returns:** `true` if permission is granted, `false` otherwise.

#### requestPermission()

```dart
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()

```dart
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()

```dart
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()

```dart
Future<void> cancel()
```

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

#### isListening

```dart
Future<bool> get isListening
```

Returns `true` if currently listening for speech, `false` otherwise.

### Streams

#### onResult

```dart
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

```dart
Stream<SpeechRecognitionError> get onError
```

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

#### onListeningStatusChanged

```dart
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

```dart
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()

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

Creates a `SpeechRecognitionResult` from a map.

#### toMap()

```dart
Map<String, dynamic> toMap()
```

Converts this result to a map.

## SpeechRecognitionError

Represents an error that occurred during speech recognition.

### Properties

```dart
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()

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

Creates a `SpeechRecognitionError` from a map.

#### toMap()

```dart
Map<String, dynamic> toMap()
```

Converts this error to a map.

## RecordingButton Widget

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

### Constructor

```dart
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

```dart
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

```dart
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

```dart
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

```dart
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);
  }
});
```