deepvoice_client/VOLCANO_VOICE_README.md

火山语音服务配置指南

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

环境变量配置

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

# 火山语音服务配置
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握手错误，尝试切换到其他区域

配置示例

// 设置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握手错误，尝试切换到其他区域

配置示例

// 设置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)