# volcengine_speech_plugin_plus

**Repository Path**: pome/volcengine_speech_plugin_plus

## Basic Information

- **Project Name**: volcengine_speech_plugin_plus
- **Description**: volcengine_speech_plugin_plus
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# volcengine_speech_plugin

Volcengine (火山引擎) 语音识别与合成 Flutter 插件，提供 ASR 语音识别和 TTS 语音合成能力。

## 快速开始

### 1. 初始化 ASR 引擎

```dart
final asr = SpeechAsrUtils();

// 初始化引擎
bool? ok = await asr.initASREngine(showNluPun: false);
```

### 2. 配置服务参数

通过 `ServiceSpeechConfig.speechConfig` 设置 appId、token、cluster 等：

```dart
// 默认使用硬编码配置
VolcengineSpeech? config = ServiceSpeechConfig.speechConfig;
```

也可以从 JSON 动态构造 `VolcengineSpeech`：

```dart
VolcengineSpeech.fromJson({
  "appId": "your_app_id",
  "token": "Bearer;your_token",
  "asrClusterId": "volcengine_input_common",
  "ttsClusterId": "volcano_tts",
  "voiceType": "BV700_V2_streaming",
  "chatVadTime": 1500,
  "lessonVadTime": 1500,
  "lessonAsrDelay": 0,
});
```

### 3. 按住说话（开始识别）

```dart
await asr.startHoldRecognize(
  talkControl: TalkControl(
    onListen: () {
      // 开始收音，可显示录音动画
    },
    onFinish: (String? text, bool isMax) {
      // 识别完成，text 为识别结果
      print("识别结果: $text");
    },
    onError: (ASRErrorType? type, String? text, bool isInterruptBackground) {
      // 识别出错
      switch (type) {
        case ASRErrorType.microphone:
          print("麦克风权限被禁止");
          break;
        case ASRErrorType.asrError:
          print("ASR 引擎错误: $text");
          break;
        case ASRErrorType.systemCatch:
          print("系统异常: $text");
          break;
        default:
          break;
      }
    },
    onPreFinish: () {
      // 松手后识别结果为空时回调
    },
    onEngineSuccess: () {
      // 引擎启动成功
    },
  ),
);
```

### 4. 松手结束识别

```dart
// 正常结束，会等待最终识别结果
await asr.finishHoldRecognize();

// 取消识别，丢弃结果
await asr.cancelHoldRecognize();
```

### 5. 销毁引擎

```dart
await asr.unInitASREngine();
```

## 麦克风权限处理

麦克风权限通过 `permission_handler` 包处理，调用方需要提供自定义的权限说明弹窗。

### 注册权限说明弹窗

```dart
// 在应用启动时注册自定义弹窗
MicroPermissionDialog.showMicroInfoDialog = showDefaultMicroInfoDialog;
```

### 权限检查流程

`getPermissionStatus()` 会自动区分 iOS 和 Android 平台：

- **iOS**：调用系统权限请求弹窗，被拒绝后弹出自定义说明
- **Android**：直接请求权限，被永久拒绝后弹出说明并引导用户前往系统设置

```dart
bool hasPermission = await getPermissionStatus();
if (hasPermission) {
  // 有权限，可以开始语音识别
}
```

### 自定义权限说明弹窗

实现一个 `Future<void> Function()` 赋值给 `MicroPermissionDialog.showMicroInfoDialog`，例如：

```dart
MicroPermissionDialog.showMicroInfoDialog = () async {
  final completer = Completer<void>();
  showDialog(
    context: context,
    builder: (_) => AlertDialog(
      title: Text('麦克风权限说明'),
      content: Text('我们需要使用您的麦克风，以便在聊天中使用语音输入功能。'),
      actions: [
        TextButton(
          onPressed: () {
            completer.complete();
            Navigator.pop(context);
          },
          child: Text('暂不'),
        ),
        TextButton(
          onPressed: () {
            openAppSettings();
            completer.complete();
            Navigator.pop(context);
          },
          child: Text('去设置'),
        ),
      ],
    ),
  );
  await completer.future;
};
```

## TalkControl 回调说明

| 回调 | 说明 |
|------|------|
| `onListen` | 检测到有效音量，开始收音 |
| `onFinish` | 识别完成，返回文本和是否已达最大时长 |
| `onError` | 识别过程出错，包含错误类型和消息 |
| `onPreFinish` | 松手但识别结果为空 |
| `onShowStick` | 开始按住说话 |
| `onCountdown` | 倒计时回调 |
| `onEngineSuccess` | 引擎启动成功 |
| `onInterrupt` | 识别中断 |
| `onQuiet` | 静音回调 |

## ASRErrorType 错误类型

| 类型 | 说明 |
|------|------|
| `microphone` | 麦克风权限被禁止 |
| `asrError` | ASR 引擎内部错误 |
| `systemCatch` | 系统级异常 |

## SpeechInterruptType 后台中断类型

| 类型 | 说明 |
|------|------|
| `isInterruptBackground` | 识别过程中切到后台 (err_code: 5000) |
| `isInterruptInit` | 未开始识别时切到后台，初始化失败 |
| `isInterruptReceiveTimeout` | 切后台后接收超时 (err_code: 4001) |
| `unknown` | 未知中断 |

## 配置模型

### VolcengineSpeech

```dart
VolcengineSpeech({
  appId: "your_app_id",
  token: "Bearer;your_token",
  asrClusterId: "volcengine_input_common",
  ttsClusterId: "volcano_tts",
  voiceType: "BV700_V2_streaming",
  supportNetOptionMatch: true,
  chatVadTime: 1500,
  lessonVadTime: 1500,
  lessonAsrDelay: 0,
  voiceTypes: '{"female_teacher":"BV700_V2_streaming"}',
});
```

### SpeechConfigItem

聚合配置类，包含 `lessonConfig`、`volcengineSpeech`、`sparkServiceConfig` 三项，支持 JSON 序列化/反序列化。