Linux SDK集成文档

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

## 1. 超拟人合成简介

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

## 2. 兼容性说明

| 类别     | 兼容范围                                                     |
| :------- | :----------------------------------------------------------- |
| 系统     | 支持x86，x86_64，arm和arm64架构，支持交叉编译，适配常见芯片型号。 |
| 开发环境 | 建议使用 VS 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

│ └── [libSparkChain.so](http://libsparkchain.so/)

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

## 5. SDK工程配置

### 5.1 导入SDK库

将SDK/libs文件夹、头文件文件夹include存放到项目中，并在环境变量里添加库路径；

```c++
#include "../include/sparkchain.h" 
#include "../include/sc_tts.h"
```

### 5.2 配置权限

如果需要存储日志，SDK日志路径需要读写权限，缺少读写权限，日志将无法正常存储。

## 6. 接口流程调用图

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

## 7. SDK初始化

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

```c++
class SPARKCHAIN_API SparkChainConfig { 
	public:    
		static SparkChainConfig* builder();    
		virtual ~SparkChainConfig();    
		//配置appid    
		virtual SparkChainConfig* appID(const char* appid)         = 0;    
    	//配置apiKey    
    	virtual SparkChainConfig* apiKey(const char* apiKey)       = 0;    
    	//配置apiSecret    
    	virtual SparkChainConfig* apiSecret(const char* apiSecret) = 0;    
    	//配置用户自定义标识    
    	virtual SparkChainConfig* uid(const char* uid)             = 0;    
    	//配置SDK工作路径    
    	virtual SparkChainConfig* workDir(const char* workDir)     = 0;    
    	//配置日志等级    
    	virtual SparkChainConfig* logLevel(int logLevel )          = 0;    
    	//配置日志存储路径    
    	virtual SparkChainConfig* logPath(const char* logPath)     = 0; };
```

SparkChainConfig接口说明：

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

初始化具体示例如下：

```c++
SparkChainConfig* config = SparkChainConfig::builder(); 
config->appID("$appId")      
	->apiKey("$apiKey")      
	->apiSecret("$apiSecret");//从平台获取的授权appid，apikey,apisecrety 
int ret = SparkChain::init(config);
```

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

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

超拟人构造方法如下：

```c++
class SPARKCHAIN_API TTS { 
	public:    
		...    
		explicit TTS(string vcn);    
		virtual ~TTS();    
}; 
class SPARKCHAIN_API PersonateTTS : public TTS { 
	public:    
		...    
		explicit PersonateTTS(string vcn);    
		~PersonateTTS(); 
};
```

构造方法参数说明：

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

具体示例如下：

```
PersonateTTS tts("x4_lingxiaoxuan_oral");
```

## 9. 功能参数配置

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

| 方法名          | 参数名          | 参数类型 | 说明                                                         | 是否必填 | 默认值         |
| :-------------- | :-------------- | :------- | :----------------------------------------------------------- | :------- | :------------- |
| vcn             | vcn             | String   | 超拟人发音人设置接口，发音人可从构造方法中设入，也可通过此方法动态修改。 x4_lingxiaoxuan_oral，聆⼩璇，⼥：中⽂ <br />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           |

具体示例如下：

```c++
tts.vcn("x4_lingxiaoxuan_oral"); 
tts.sampleRate(24000); 
... 
tts.sparkAssist(true);
```

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

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

```c++
class PersonateCallbacks : public TTSCallbacks {    
	void onResult(TTSResult * result,void * usrTag) {    	     
	
	}     
	void onError(TTSError * error, void * usrTag) {            
	
	}     
};
```

TTSCallbacks数据结构说明：

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

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

- TTSResult结构说明：

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

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

- TTSError结果说明：

| 方法     | 说明                           |
| :------- | :----------------------------- |
| code()   | 错误码ID，具体参考错误码章节。 |
| errMsg() | 错误信息                       |
| sid()    | 本次会话的id                   |

具体示例如下：

```c++
class PersonateCallbacks : public TTSCallbacks {    
    void onResult(TTSResult * result,void * usrTag) {        
        //解析获取的交互结果，示例展示所有结果获取，开发者可根据自身需要，选择获取。        
        const char * data = result->data();//音频数据        
        int len           = result->len();//音频数据长度        
        int status        = result->status();//数据状态        
        string ced        = result->ced();//进度        
        int seq           = result->seq();//数据序号        
        string pybuf      = result->pybuf();//拼音结果        
        string version    = result->version();//引擎版本号           
        string sid        = result->sid();//sid    
    }     
    void onError(TTSError * error, void * usrTag) {        
        int errCode   = error->code();//错误码        
        string errMsg = error->errMsg();//错误信息        
        string sid    = error->sid();//sid    
    }     
}; 
PersonateCallbacks *cbs = new PersonateCallbacks(); tts.registerCallbacks(cbs);
```

## 11. 请求调用

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

```c++
virtual int arun(string text); 
virtual int arun(string text, void * usrTag);
```

arun方法结构说明：

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

具体示例如下：

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

## 12. 停止合成

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

```c++
tts.stop();
```

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

## 13. 逆初始化

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

```c++
SparkChain::unInit();
```

## 14. 错误码

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

### 14.1 SDK错误码

### 14.2 超拟人合成云端错误码