# SparkChain 在线语音合成 Android SDK集成文档

# 1. 在线语音合成简介

在线语音合成流式接口将文字信息转化为声音信息，同时提供了众多极具特色的发音人（音库）供您选择。具体发音人参考功能参数配置。

注意：在使用该能力前，需要开通相应的授权。

小语种及少数民族方言：

• 目前新增：韩语、日语、维吾尔语、藏语、法语、俄语、西班牙语、印地语、德语、越南语、巴西葡萄牙语、意大利语、葡萄牙语、泰语、乌尔都语；
• 使用小语种时上传文本编码必须使用unicode编码且设置tte=unicode（unicode即utf16小端的编码方式）或者使用UTF8的编码方式；
• 需先在控制台开启小语种发音人才可合成小语种，否则报错11200。

请注意：安卓开发者可以使用build.gradle自动依赖Maven仓库对发布的包进行管理，从而达到自动更新的目的。安卓用户具体自动更新配置如下：

在根目录的 build.gradle 添加：

allprojects {
    repositories {
        // ...
        maven { url 'https://www.jitpack.io' }
    }
}

添加依赖：

dependencies {
    implementation 'com.github.xunfyun:sparkchain:2.0.0_rc4'
}

# 2. 兼容性说明

# 3. SDK集成包目录结构

将SDK zip包解压缩，得到如下文件：

├── Demo SparkChain的使用DEMO，DEMO中已经集成了SDK，您可以参考DEMO，集成SDK。集成前，请先测通DEMO，了解调用原理。

├── ReleaseNotes.txt SDK版本日志

├── SDK SparkChain SDK

│ └── SparkChain.aar

└── SparkChain 在线语音合成 Android SDK集成文档.pdf SparkChain集成指南

# 4. SDK工程配置

# 4.1 导入SDK库

复制SparkChain.aar到项目的libs目录下，然后在主Module的build.gradle文件中，增加如下配置：

implementation files('libs/SparkChain.aar')

# 4.2 配置权限

外部使用时需要配置以下权限：

如果部分权限不需要，可通过如下配置去除，去除示例如下：

Android 10.0（API 29）及以上版本需要在application中做如下配置
<application android:requestLegacyExternalStorage="true"/>

# 4.3 混淆配置

SparkChain SDK 已做过混淆，如果您项目中也使用了混淆，请在 proguard-rules.pro文件中添加如下配置保持SparkChain SDK 不再被混淆。

-keep class com.iflytek.sparkchain.** {*;} 
-keep class com.iflytek.sparkchain.**

# 5. 接口流程调用图

# 6. SDK 初始化

在使用SDK功能前，需要先开通在线语音合成授权并获取已开通授权的应用信息（appId、apiKey、apiSecret）。SDK全局只需要初始化一次。 初始化时，开发者需要构建一个SparkChainConfig实例config，把相关的appid信息以及日志设置等传入config中，然后再通过SparkChain.getInst().init方法把config实例设置到SDK中。具体初始化示例如下：

//配置应用信息 
SparkChainConfig config =  SparkChainConfig.builder()    
    .appID("$appId")       
    .apiKey("$apiKey")    
    .apiSecret("$apiSecret"); 
int ret = SparkChain.getInst().init(getApplicationContext(), config); 

初始化参数说明：

初始化返回值：0：初始化成功，非0：初始化失败，请根据具体返回值参考错误码章节查询原因。

# 7. 在线语音合成初始化

在使用在线语音合成功能前，需先通过其构造方法OnlineTTS()方法构建其实例，然后用该实例调用相应的方法去设置转写参数。

在线语音合成构造方法如下：

public class OnlineTTS extends TTS {
    public OnlineTTS(String vcn) {        
        ...
    }
}

构造方法参数说明：

具体示例如下：

OnlineTTS tts = new OnlineTTS("xiaoyan");

# 8. 功能参数配置

SDK支持用户根据自身需求，通过构建的OnlineTTS实例访问相关方法配置合成参数。具体方法说明如下：

具体配置示例如下：

mOnlineTTS.aue("raw");
mOnlineTTS.bgs(0);//合成音频的背景音 0:无背景音（默认值） 1:有背景音
...
mOnlineTTS.speed(mTTSParams.speed);//语速
mOnlineTTS.pitch(mTTSParams.pitch);//语调
mOnlineTTS.volume(mTTSParams.volume);//音量

# 9. 注册结果监听回调

在线语音合成运行结果通过TTSCallbacks异步返回，接口定义如下：

public interface TTSCallbacks {
    void onResult(TTS.TTSResult result, Object usrTag);

    void onError(TTS.TTSError error, Object usrTag);
}

TTSCallbacks数据结构说明：

• onResult为超拟人合成音频回调方法，参数说明如下：

  参数	类型	说明
  result	TTS.TTSResult	在线合成结果实例
  usrTag	Object	用户自定义标识

• TTSResult结构说明：

  方法	返回值类型	说明
  getData()	byte[]	⾳频数据，最⼩尺⼨:0B, 最⼤尺⼨:10485760B
  getLen()	int	音频数据长度
  getStatus()	int	数据状态，0:开始, 1:开始, 2:结束
  getCed()	String	流式音频数据的进度尾端点
  getSid()	String	本次会话的id

• onError为超拟人合成错误回调，参数说明如下：

  参数	类型	说明
  error	TTS.TTSError	错误信息结果实例
  usrTag	Object	用户自定义标识

• TTSError结果说明：

  方法	返回值类型	说明
  getCode()	int	错误码ID，具体参考错误码章节。
  getErrMsg()	String	错误信息
  getSid()	String	本次会话的id

具体示例如下：

TTSCallbacks mTTSCallback = new TTSCallbacks() {         
        @Override        
        public void onResult(TTS.TTSResult result, Object usrTag) {            
            //解析获取的交互结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。        
            byte[] audio    = result.getData();//音频数据
            int len        = result.getLen();//音频数据长度
            int status     = result.getStatus();//数据状态
            String ced     = result.getCed();//进度
            String sid     = result.getSid();//sid    
        }        
        @Override        
        public void onError(TTS.TTSError ttsError, Object usrTag) {                 
            int errCode   = ttsError.getCode();//错误码            
            String errMsg = ttsError.getErrMsg();//错误信息            
            String sid    = ttsError.getSid();//sid        
        } 
}; 
mOnlineTTS.registerCallbacks(mTTSCallback);

# 10. 请求调用

开发者注册完监听回调后，可通过mOnlineTTS.aRun()方法进行请求调用。请求调用接口如下：

public class OnlineTTS extends TTS {
    public int aRun(String text) {        
        ...   
    }    
    
    public int aRun(String text, Object usrTag) {        
        ...
    }
}

aRun方法结构说明：

具体示例如下：

String text = "技术支持跑的快,全靠大佬们带,受着老板们和研发大佬熏陶,技术支持也不会掉队的。"
mOnlineTTS.aRun(text);
 
//带用户自定义标识调用方式示例：
//int usrTag = 1;
//mOnlineTTS.aRun(text,usrTag);

# 11. 停止合成

如果开发者不需要此次合成结果，可以通过调用stop()方法结束本次合成，然后重新进行下一次交互。具体调用如下：

mOnlineTTS.stop();

如果不需要继续使用SDK，需要执行逆初始化释放资源。逆初始化执行步骤参考第12节。

# 12. 逆初始化

当SDK需要完整退出时，需调用逆初始化方法释放资源，示例代码如下：

SparkChain.getInst().unInit();  //SDK逆初始化

# 13. SDK API介绍

# 13.1 SparkChainConfig API

# 13.2 SparkChain API

# 13.3 OnlineTTS API

# 13.4 TTSResult API

# 13.5 TTSError API

# 14. 错误码

错误码包含SDK错误码和云端错误码。

# 14.1 SDK错误码

# 14.2 部分云端错误码

备注：如出现下述列表中没有的错误码，可到 这里 (opens new window) 查询。