# 火山语音服务配置指南

本文档提供了关于火山语音服务的配置和常见问题解决方案。

## 环境变量配置

火山语音服务需要以下环境变量：

```
# 火山语音服务配置
VOLCANO_APP_ID=your_volcano_app_id_here  # 应用ID
VOLCANO_APP_KEY=your_volcano_app_key_here  # 应用密钥/Token
VOLCANO_CLUSTER=your_volcano_cluster_here  # 集群区域，例如: cn-beijing

# 语音合成配置
VOLCANO_VOICE_TYPE=zh_female_wanqudashu_moon_bigtts  # 默认语音类型 - 湾区大叔
```

请确保在 `.env` 文件中正确设置这些变量。

## 常见问题解决

### 1. TTS资源授权错误

如果遇到以下错误：

```
语音类型授权错误: 您可能没有权限使用当前选择的语音类型
```

**解决方案**：
- 尝试使用基础语音类型，如 `zh_male_qingse_common` 或 `zh_female_qingse_common`
- 确保您的火山引擎账户已开通语音合成服务
- 检查应用ID和密钥是否正确

### 2. 语音识别认证错误

如果遇到以下错误：

```
authentication signature from request: 'Authorization' header: invalid auth token
```

**解决方案**：

#### 标准语音识别SDK (API v2)
- 确保 `VOLCANO_APP_KEY` 格式正确，这是一个完整的令牌
- **必须**在Token前添加 `Bearer;` 前缀（注意使用分号而非空格）
- 检查应用ID和密钥是否匹配
- 确保您的火山引擎账户已开通语音识别服务
- 使用正确的API路径: `/api/v2/asr`

#### 大模型流式识别SDK (API v3)
- 使用正确的API路径: `/api/v3/sauc/bigmodel`
- **不要**在Token前添加Bearer前缀
- 设置正确的资源ID (`RESOURCE_ID_STRING`)
- 设置协议类型为 `PROTOCOL_TYPE_SEED`
- 确保您的火山引擎账户已开通大模型流式语音识别服务

### 3. WebSocket连接错误

如果遇到以下错误：

```
Error during WebSocket handshake: Unexpected response code: 400
```

**解决方案**：
- 确保网络连接正常，可以访问 `openspeech.bytedance.com`
- **集群区域设置非常重要**，必须设置正确的 `VOLCANO_CLUSTER` 环境变量
- 默认使用 `cn-beijing`，但您的账户可能需要使用其他区域，如 `cn-shanghai` 或 `cn-guangzhou`
- 如果使用默认区域出现错误，请尝试切换到其他区域
- 确保您的账户已开通相应的语音识别服务
- 检查请求参数格式是否正确
- 对于标准语音识别SDK (API v2)，确保Token前添加了 `Bearer;` 前缀
- 如果问题仍然存在，请联系火山引擎技术支持

### 4. 检查配置工具

我们提供了两个工具来检查火山语音服务的配置：

1. **检查TTS配置**：
   ```
   flutter run lib/tools/check_volcano_config.dart
   ```

2. **检查语音识别配置**：
   ```
   flutter run lib/tools/check_volcano_asr_config.dart
   ```

这些工具将帮助您验证环境变量、网络连接和服务授权是否正确。

## 离线TTS支持

我们的应用支持离线TTS功能，当在线TTS失败时会自动切换到离线模式。离线模式支持基础语音类型：
- `zh_male_qingse_common`（基础男声）
- `zh_female_qingse_common`（基础女声）

要使用离线TTS，您可以：
1. 在TTS测试页面选择基础语音类型
2. 当在线合成失败时，系统会自动尝试使用离线合成

## 标准语音识别SDK配置 (API v2)

标准语音识别SDK是火山语音服务的基础版本，配置相对简单。

### 关键配置点
1. **API路径**：使用 `/api/v2/asr`
2. **认证方式**：
   - 必须在Token前添加 `Bearer;` 前缀（注意使用分号而非空格）
   - 不需要设置资源ID
3. **集群区域**：确保设置正确的集群区域，如 `cn-beijing`
   - 集群区域必须与您的账户配置匹配
   - 如果遇到WebSocket握手错误，尝试切换到其他区域

### 配置示例
```kotlin
// 设置API路径
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_ASR_URI_STRING, "/api/v2/asr");

// 设置认证信息
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_APP_ID_STRING, "YOUR_APP_ID");
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_APP_TOKEN_STRING, "Bearer;YOUR_APP_KEY"); // 必须添加Bearer;前缀

// 设置集群区域
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_ASR_CLUSTER_STRING, "cn-beijing");
```

## 大模型流式识别SDK配置 (API v3)

从2024年2月26日起，火山语音服务提供了新的大模型流式识别SDK。如果您使用的是这个新版本，请注意以下配置差异：

### 版本信息
- Android: `com.bytedance.speechengine:speechengine_asr_tob:1.1.7`
- iOS: `pod 'SpeechEngineAsrToB', '1.1.7'`

### 关键配置差异
1. **API路径**：使用 `/api/v3/sauc/bigmodel` 而非旧版的 `/api/v2/asr`
2. **认证方式**：
   - 不需要在Token前添加 `Bearer` 前缀
   - 需要设置资源ID (`RESOURCE_ID_STRING`)
3. **协议类型**：需要设置为 `PROTOCOL_TYPE_SEED`
4. **集群区域**：确保设置正确的集群区域，如 `cn-beijing`
   - 集群区域必须与您的账户配置匹配
   - 如果遇到WebSocket握手错误，尝试切换到其他区域

### 配置示例
```kotlin
// 设置API路径
mSpeechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_URI_STRING, "/api/v3/sauc/bigmodel");

// 设置认证信息
mSpeechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_ID_STRING, "YOUR_APP_ID");
mSpeechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_TOKEN_STRING, "YOUR_APP_KEY"); // 不需要Bearer前缀

// 设置资源ID
mSpeechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_RESOURCE_ID_STRING, "YOUR_RESOURCE_ID");

// 设置协议类型
mSpeechEngine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_PROTOCOL_TYPE_INT, SpeechEngineDefines.PROTOCOL_TYPE_SEED);

// 设置集群区域
mSpeechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_CLUSTER_STRING, "cn-beijing");

// 设置ASR请求参数
mSpeechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_REQ_PARAMS_STRING, 
    "{"force_to_speech_time":0, "end_window_size":800}");
```

## 支持的语音类型

我们支持多种语音类型，包括：

### 趣味方言
- 湾区大叔 (`zh_female_wanqudashu_moon_bigtts`)
- 呆萌川妹 (`zh_female_daimengchuanmei_moon_bigtts`)
- 广州德哥 (`zh_male_guozhoudege_moon_bigtts`)
- 北京小爷 (`zh_male_beijingxiaoye_moon_bigtts`)
- 浩宇小哥 (`zh_male_haoyuxiaoge_moon_bigtts`)

### 通用场景
- 少年梓辛/Brayan (`zh_male_shaonianzixin_moon_bigtts`)

### 角色扮演
- 魅力女友 (`zh_female_meilinvyou_moon_bigtts`)
- 深夜播客 (`zh_male_shenyeboke_moon_bigtts`)
- 柔美女友 (`zh_female_sajiaonvyou_moon_bigtts`)
- 撒娇学妹 (`zh_female_yuanqinvyou_moon_bigtts`)

### 基础语音类型
- 基础男声 (`zh_male_qingse_common`)
- 基础女声 (`zh_female_qingse_common`)
- 高级男声 (`zh_male_M392_conversation_wvae_bigtts`)
- 高级女声 (`zh_female_F392_conversation_wvae_bigtts`)