# SparkChain 实时语音转写 Linux SDK集成文档

# 1. 实时语音转写简介

实时语音转写（Real-time ASR）基于深度全序列卷积神经网络框架，通过 WebSocket 协议，建立应用与语言转写核心引擎的长连接，开发者可实现将连续的音频流内容，实时识别返回对应的文字流内容。 支持的音频格式： 采样率为16K，采样深度为16bit，单声道的pcm音频

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

# 2. 兼容性说明

# 3. SDK集成包目录结构

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

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

├── ReleaseNotes.txt SDK版本日志

├── SDK SparkChain SDK

│ └── libSparkChain.so (opens new window)

└── SparkChain 实时语音转写 Linux SDK集成文档.pdf SparkChain集成指南

# 4. SDK工程配置

# 4.1 导入SDK库

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

#include "../../include/sparkchain.h"
#include "../../include/sc_rtAsr.h"

# 4.2 配置权限

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

# 5. 接口流程调用图

# 6. SDK 初始化

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

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; 
};

初始化参数说明：

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

具体示例如下：

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

# 7. 实时语音转写初始化

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

实时语音转写构造方法如下：

class SPARKCHAIN_API RTASR {
public:
    RTASR(const string apiKey);
}

构造方法参数说明：

具体示例如下：

RTASR rtasr(RTAsrAPIKey);//RTASR 初始化

# 8. 功能参数配置

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

具体配置示例如下：

rtasr.transType("normal");
rtasr.transStrategy(2);
...
rtasr.lang("cn");
rtasr.targetLang("en");

# 9. 注册结果监听回调

实时语音转写运行结果通过RTASRCallbacks异步返回，接口定义如下：

class SPARKCHAIN_API RtAsrCallbacks {
public:
	virtual void onResult(RtAsrResult* result, void* usrTag) = 0;
    virtual void onError(RtAsrError* error, void* usrTag) = 0;
};

RtAsrCallbacks数据结构说明：

• onResult为实时语音转写结果回调方法，参数说明如下：

  参数	类型	说明
  result	RtAsrResult*	实时语音转写结果实例
  usrTag	void*	用户自定义标识

• RtAsrResult结构说明：

  方法	返回值类型	说明
  data()	string	转写结果
  rawResult()	string	云端下发的原始json结果
  status()	int	数据状态： 0：此次返回翻译结果。(此时仅翻译有结果，data无结果) 1：流式识别结果 2：子句plain结果 3：end
  sid()	string	本次交互的sid
  transResult().src()	String	翻译的源文本
  transResult().dst()	String	翻译结果
  transResult().status()	int	翻译状态： 2：翻译的plain结果

• onError为实时语音转写错误回调，参数说明如下：

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

• RtAsrError结构说明：

  方法	返回值类型	说明
  code()	int	错误码
  errMsg()	string	错误信息
  sid()	string	交互的Sid

具体示例如下：

class RtAsrCallbacksImpl :public RtAsrCallbacks{
    void onResult(RtAsrResult* result, void* usrTag){
        int status       = result->status();//数据状态。0:此次返回翻译结果;1:流式结果;2:子句plain结果;3:end结束
        string sid       = result->sid();//本次交互的sid
        string rawResult = result->rawResult();//云端下发的原始json结果
        string data      = result->data();//转写结果
        string src       = result->transResult()->src();//翻译源文本
        string dst       = result->transResult()->dst();//翻译结果
    }
    void onError(RtAsrError* error, void* usrTag){
        string sid    = error->sid();//本次交互的sid
        int code      = error->code();//错误码
        string errMsg = error->errMsg();//错误信息
    }
};
RtAsrCallbacksImpl *mRTASRCallbacks = new RtAsrCallbacksImpl();  
rtasr.registerCallbacks(mRTASRCallbacks);

# 10. 请求调用

# 10.1 开启会话

开发者注册完监听回调后，可通过mRTASR.start()方法开启会话。请求调用接口如下：

class SPARKCHAIN_API RTASR {
public:
    int start(void* usrTag = nullptr);
}

start方法结构说明：

具体示例如下：

rtasr.start();

# 10.2 送入数据

启动会话后，开发者可通过rtasr.write()方法送入要识别的音频，然后异步从监听回调中获取识别结果。write方法调用接口如下：

class SPARKCHAIN_API RTASR {
public:
    int write(const char* data, size_t len);
}

write方法参数说明：

具体示例如下：

char * data = new char[1280];
...//省略获取音频的过程 
rtasr.write(data,1280);

# 10.3 结束会话

当开发者送完数据后，需要调用rtasr.stop()方法通知SDK层以及云端数据已传完。之后云端则会下发最终的识别结果，然后结束本轮交互。stop方法调用接口如下：

class SPARKCHAIN_API RTASR {
public:
    int stop();
}

具体示例如下：

rtasr.stop();      //停止

# 11. 逆初始化

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

SparkChain::unInit();  //SDK逆初始化

# 12. SDK API介绍

# 12.1 SparkChainConfig API

# 12.2 SparkChain API

# 12.3 RTASR API

# 12.4 RTASRResult API

# 12.5 RTASRError API

# 12.6 RTASRTransResult API

# 13. 错误码

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

# 13.1 SDK错误码

# 13.2 部分云端错误码

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