Android SDK集成文档

# SparkChain 超拟人合成 Android SDK集成文档

## 1. 超拟人合成简介

SparkChain支持用户把一段文本送入指定的接口，获取该文本的超拟人合成音频。超拟人相比常规的合成能力，合成效果更好！同时在合成中，利用大模型生成一些拟声词，使合成的音频更加拟人化更加真实。

## 2. 兼容性说明

| 类别     | 兼容范围                                        |
| :------- | :---------------------------------------------- |
| 系统     | 支持armv7和armv8架构，兼容android 5.0及以上版本 |
| 开发环境 | 建议使用Android Studio 进行开发                 |

## 3. 授权说明

超拟人合成授权按照tokens授权方式进行授权。

tokens 授权：授权tokens总量，按照tokens 使用量计费，1 tokens 约等于1.5个中文汉字 或者 0.8个英文单词。

## 4. SDK集成包目录结构

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

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

├── ReleaseNotes.txt SDK版本日志

├── SDK SparkChain SDK

│ └── SparkChain.aar

└── SparkChain 超拟人合成 Android SDK集成文档.pdf SparkChain集成指南

## 5. SDK工程配置

### 5.1 导入SDK库

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

```java
implementation files('libs/SparkChain.aar')
```

### 5.2 配置权限

SparkChain SDK中默认配置了以下权限：

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

```java
 
<uses-permission android:name="android.permission.READ_PHONE_STATE" tools:node="remove" /> 
```

Android 10.0（API 29）及以上版本需要在application中做如下配置

```java
<application android:requestLegacyExternalStorage="true"/>
```

### 5.3 混淆配置

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

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

## 6. 接口流程调用图

![](/media/202405/超拟人合成android流程图_1714991655.png)

## 7. SDK 初始化

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

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

初始化参数说明：

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

## 8. 超拟人合成初始化

在使用超拟人合成功能前，需先通过其构造方法PersonateTTS ()方法构建其实例，然后用该实例调用相应的方法去设置合成参数。

超拟人构造方法如下：

```java
public class PersonateTTS extends TTS {    
	public PersonateTTS(String vcn) {        
		super(vcn);   
	} 
}
```

构造方法参数说明：

| 方法名       | 参数名 | 类型   | 说明                                                         |
| :----------- | :----- | :----- | :----------------------------------------------------------- |
| PersonateTTS | vcn    | String | 超拟人实例的构造方法，需传入发音人。发音人具体参见下方vcn方法说明 |

具体示例如下：

```java
PersonateTTS personateTTS = new PersonateTTS("x4_lingxiaoxuan_oral");
```

## 9. 功能参数配置

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

| 方法名 | 参数名 | 参数类型 | 说明 | 是否必填 | 默认值 |
| :-------------- | :-------------- | :------- | :----------------------------------------------------------- | :------- | :------------- |
| vcn | vcn | String | 超拟人发音人设置接口，发音人可从构造方法中设入，也可通过此方法动态修改。 x4_lingxiaoxuan_oral，聆⼩璇，⼥：中⽂ x4_lingfeizhe_oral，聆⻜哲，男：中⽂ | 否 | 由构造方法传入 |
| speed | speed | int | 语速：0对应默认语速的1/2，100对应默认语速的2倍。最⼩值:0, 最⼤值:100 | 否 | 50 |
| pitch | pitch | int | 语调：0对应默认语速的1/2，100对应默认语速的2倍。最⼩值:0, 最⼤值:100 | 否 | 50 |
| volume | volume | int | 音量：0是静音，1对应默认音量1/2，100对应默认音量的2倍。最⼩值:0, 最⼤值:100 | 否 | 50 |
| reg | reg | int | 英⽂发⾳方式。 0:⾃动判断处理，如果不确定将按照英⽂词语拼写处理（缺省）； 1:所有英⽂按字⺟发⾳； 2:⾃动判断处理，如果不确定将按照字⺟朗读。 | 否 | 0 |
| rdn | rdn | int | 合成⾳频数字发⾳⽅式。0:⾃动判断, 1:完全数值, 2:完全字符串, 3:字符串优先 | 否 | 0 |
| sampleRate | sampleRate | int | 输出音频的采样率。16000, 8000, 24000 | 否 | 16000 |
| encoding | encoding | string | ⾳频编码。lame, speex, opus, opus-wb,speex-wb,raw | 否 | raw |
| bitDepth | bitDepth | int | 位深。16, 8 | 否 | 16 |
| channels | channels | int | 声道数。1, 2 | 否 | 1 |
| frameSize | frameSize | int | 帧⼤⼩。最⼩值:0, 最⼤值:1024 | 否 | 0 |
| bgs | bgs | int | 背景⾳。0:⽆背景⾳, 1:内置背景⾳1, 2:内置背景⾳2 | 否 | 0 |
| rhy | enable | bool | 是否返回拼⾳标注。false:不返回拼⾳, true:返回拼⾳（纯⽂本格式，utf8编码） | 否 | false |
| scn | scn | int | 场景。0:⽆, 1:散⽂阅读, 2:⼩说阅读, 3:新闻, 4:⼴告, 5:交互 | 否 | 0 |
| version | enable | bool | 引擎初始化，是否返回版本信息+时间戳信息。false:不返回, true:返回版本信息+时间戳信息。如XXX.18928127 XXX表示版本号，后接秒为单位的时间戳 | 否 | false |
| l5SilLen | l5SilLen | int | 控制L5静⾳时⻓，取值范围为0~10000ms。最⼩值:0, 最⼤值:10000 | 否 | |
| paragraphSilLen | paragraphSilLen | int | 段落静⾳时⻓，取值范围为0~10000ms。最⼩值:0, 最⼤值:10000 | 否 | |
| topK | topK | int | 配置从k个候选中随机选择⼀个（⾮等概率)。取值范围1-6 | 否 | 4 |
| maxTokens | maxTokens | int | 回答的tokens的最大长度。取值范围1-8192 | 否 | 8192 |
| oralLevel | level | String | ⼝语化等级。⾼:high, 中:mid, 低:low | 否 | mid |
| sparkAssist | enable | bool | 是否通过⼤模型进⾏⼝语化。开启:true, 关闭:false | 否 | true |

具体配置示例如下：

```java
personateTTS.vcn("x4_lingxiaoxuan_oral"); 
personateTTS.speed(50); 
personateTTS.pitch(50); 
personateTTS.volume(50); 
... 
personateTTS.sparkAssist(true);
```

## 10. 注册结果监听回调

超拟人合成运行结果通过TTSCallbacks监听回调异步返回，监听回调如下：

```java
TTSCallbacks mTTSCallback = new TTSCallbacks() {         
	@Override        
	public void onResult(TTS.TTSResult result, Object usrTag) {                    
	
	}        
	@Override        
	public void onError(TTS.TTSError ttsError, Object usrTag) {         
	
	} 
};
```

TTSCallbacks数据结构说明：

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

| 参数   | 类型          | 说明               |
| :----- | :------------ | :----------------- |
| result | TTS.TTSResult | 超拟人合成结果实例 |
| usrTag | Object        | 用户自定义标识     |

- TTSResult结构说明：

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

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

- TTSError结果说明：

具体示例如下：

```java
TTSCallbacks mTTSCallback = new TTSCallbacks() {         
	@Override        
	public void onResult(TTS.TTSResult result, Object usrTag) {            
		//解析获取的交互结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。            
		byte[] data    = result.getData();//音频数据            
		int len        = result.getLen();//音频数据长度            
		int status     = result.getStatus();//数据状态            
		int seq        = result.getSeq();//数据序号            
		String ced     = result.getCed();//进度            
		String pybuf   = result.getPybuf();//拼音结果            
		String version = result.getVersion();//引擎版本号            
		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        
	} 
}; 
personateTTS.registerCallbacks(mTTSCallback);
```

## 11. 请求调用

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

```java
public class PersonateTTS extends TTS { 
	public void aRun(String text) {    	
		... 
	}        
	public void aRun(String text,Object usrTag) {    	
		... 
	} 
}
```

aRun方法结构说明：

| 参数   | 类型   | 说明           |
| :----- | :----- | :------------- |
| text   | String | 请求合成文本。 |
| usrTag | Object | 用户自定义标识 |

具体示例如下：

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

## 12. 停止合成

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

```
personateTTS.stop();
```

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

## 13. 逆初始化

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

```
SparkChain.getInst().unInit();
```

## 14. SDK API介绍

### 14.1 SparkChainConfig API

### 14.2 SparkChain API

| 返回值类型 | 方法说明 |
| :--------- | :----------------------------------------------------------- |
| SparkChain | public static SparkChain getInst() 获取SparkChain实例 |
| int | public int init(Context context, SparkChainConfig config) SDK初始化 |
| int | public int init(Context context) SDK初始化 |
| int | public int unInit() SDK逆初始化 |
| int | public int getInitCode() 获取SDK初始化结果码 |

### 14.3 PersonateTTS API

### 14.4 PersonateTTS TTSResult API

### 14.5 PersonateTTS TTSError API

## 15. 错误码

错误码包含SDK错误码和超拟人合成云端错误码。

### 15.1 SDK错误码

### 15.2 超拟人错误码