# SparkChain 语音听写 Linux SDK集成文档

# 1. 语音听写简介

语音听写流式接口，用于1分钟内的即时语音转文字技术，支持实时返回识别结果，达到一边上传音频一边获得识别文本的效果。

高阶功能-动态修正现在免费开放！多个小语种已上线！

动态修正：可到这里 动态修正效果 (opens new window) 在线体验

• 未开启动态修正：实时返回识别结果，每次返回的结果都是对之前结果的追加；
• 开启动态修正：实时返回识别结果，每次返回的结果有可能是对之前结果的追加，也有可能是要替换之前某次返回的结果（即修正）；
• 开启动态修正，相较于未开启，返回结果的颗粒度更小，视觉冲击效果更佳；
• 使用动态修正功能需到控制台-流式听写-高级功能处点击开通，并设置相应参数方可使用，参数设置方法详见 业务参数说明 (opens new window) ；
• 动态修正功能仅 中文 支持；
• 未开启与开启返回的结果格式不同，详见 动态修正返回结果 (opens new window) ；

小语种

• 支持的语种请到语音听写 (opens new window)页面或控制台查看；
• 使用少数民族语言和小语种时，URL和中英文URL不同，详见 接口要求 (opens new window) ；
• 小语种参数设置方法详见 业务参数说明 (opens new window) ；

该语音能力是通过Websocket API的方式给开发者提供一个通用的接口。Websocket API具备流式传输能力，适用于需要流式数据传输的AI服务场景，比如边说话边识别。相较于SDK，API具有轻量、跨语言的特点；相较于HTTP API，Websocket API协议有原生支持跨域的优势。

原WebAPI普通版本接口(http[s]: //api.xfyun.cn/v1/service/v1/iat) 不再对外开放，已经使用WebAPI普通版本的用户仍可使用，同时也欢迎体验新版流式接口并尽快完成迁移~

# 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_asr.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. 语音听写初始化

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

语音听写构造方法如下：

class SPARKCHAIN_API ASR {
public:
    ASR();
    ASR(string language, string domain, string accent);
    ~ASR();
}

构造方法参数说明：

具体示例如下：

ASR asr(language,"iat","mandarin");
//无参初始化方法
//ASR asr;//使用无参的构造方法，需要在功能参数里配置language,domain和accent三元组才能使用。

# 8. 功能参数配置

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

具体配置示例如下：

asr.language("zh_cn");//语种，zh_cn:中文，en_us:英文。其他语种参见集成文档
asr.domain("iat");//应用领域,iat:日常用语。其他领域参见集成文档
...
asr.accent("mandarin");//方言，mandarin:普通话。方言仅当language为中文时才会生效。
asr.vinfo(true);//返回子句结果对应的起始和结束的端点帧偏移值。

# 9. 注册结果监听回调

语音听写运行结果通过AsrCallbacks异步返回，接口定义如下：

class SPARKCHAIN_API ASRCallbacks {
public:
    virtual void onResult(ASRResult * result, void * usrTag) = 0;
    virtual void onError(ASRError * error,void * usrTag) = 0;
};

AsrCallbacks数据结构说明：

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

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

• ASRResult 结构说明：

  方法	返回值类型	说明
  bestMatchText()	string	识别结果返回接口，开发者可通过此方法快速获取识别结果。
  status()	int	识别结果返回进度，0：开始，1：中间，2：结束
  sid()	string	本次交互的sid
  vads()	vector<Vad *>	vad结果结构体，里面包含本次交互的vad信息。只有在功能参数里打开了vinfo才会返回
  transcriptions()	vector<Transcription *>	识别结果结构体，里面包含具体识别结果信息，一般无特殊需求，识别结果从getBestMatchText方法获取。

• Vad结构体说明：

  方法	返回值类型	说明
  begin()	int	起始的端点帧偏移值，单位：帧（1帧=10ms）
  end()	int	结束的端点帧偏移值，单位：帧（1帧=10ms）

• Transcription结构体说明：

  方法	返回值类型	说明
  index()	int	起始的端点帧偏移值，单位：帧（1帧=10ms） 注：以下两种情况下bg=0，无参考意义： 1)返回结果为标点符号或者为空； 2)本次返回结果过长。
  segments()	vector<Segment *>	中文分词结构体

• Segment结构体说明：

  方法	返回值类型	说明
  text()	string	字词
  score()	int	得分，当前未实现，保留字段

• onError为语音识别错误回调，参数说明如下：

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

• ASRError 结构说明：

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

具体示例如下：

class ASRCallbacksImpl : public ASRCallbacks {
    void onResult(ASRResult * result, void * usrTag) override {
        int begin = -1;
        int end = -1;
        string word = "";
        string asrResult = result->bestMatchText();//解析识别结果
        int status       = result->status();//解析结果返回状态
        string sid       = result->sid();//解析sid

        //以下信息需要开发者根据自身需求，如无必要，可不需要解析执行。
        vector<Vad *> vads = result->vads();//解析vad结构体
        for (Vad * v : vads) {
            begin = v->begin();//解析vad前端点
            end   = v->end();//解析vad后端点         
        }
        vector<Transcription *> transcriptions = result->transcriptions();//解析具体结果信息
        for (auto item : transcriptions) {
            vector<Segment *> segs = item->segments();//解析中文分词结构体
            for (auto seg : segs) {
                word = seg->text();//解析词语
            }
        }
    }
    void onError(ASRError * error,void * usrTag) override {
        int errCode   = error->code();//错误码
        string errMsg = error->errMsg();//错误信息
        string sid    = error->sid();//本次交互的sid
    }
};
ASRCallbacksImpl *mASRCallbacks = new ASRCallbacksImpl();
asr.registerCallbacks(mASRCallbacks);//注册监听回调

# 10. 请求调用

# 10.1 开启会话

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

class SPARKCHAIN_API ASR {
    int start(const AudioAttributes & attributes,void * usrTag = nullptr);
}

• start方法结构说明：

  参数	类型	说明
  attributes	const AudioAttributes &	输入数据格式结构体，用于描述输入数据音频格式。默认:16K,16bit,单声道的pcm音频。
  usrTag	void *	用户自定义标识

• AudioAttributes结构说明：

  方法名	返回值类型	参数名	参数类型	说明
  setSampleRate	void	sampleRate	int	输入音频的采样率，支持8k和16k
  setEncoding	void	encoding	const string &	输入音频的编码格式 raw：原生音频（支持单声道的pcm） speex：speex压缩后的音频（8k） speex-wb：speex压缩后的音频（16k） 请注意压缩前也必须是采样率16k或8k单声道的pcm。 lame：mp3格式（仅中文普通话和英文支持，方言及小语种暂不支持）
  setChannels	void	channels	int	输入音频的声道 1:单声道(默认) 2:双声道
  setBitDepth	void	bitdepth	int	位深 8:8bit 16:16bit(默认)
  setFrameSize	void	framesize	int	帧大小 最小值:0, 最大值:1024

具体示例如下：

SparkChain::AudioAttributes attr;
attr.setSampleRate(16000);  //输入音频采样率:16K:16000,8K:8000
attr.setEncoding("raw");    //输入音频的编码格式.raw:pcm原始音频格式
attr.setChannels(1);        //输入音频的声道 1:单声道(默认) 2:双声道
asr.start(attr);

# 10.2 送入数据

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

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

write方法参数说明：

具体示例如下：

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

# 10.3 结束会话

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

class SPARKCHAIN_API ASR {
    int stop(bool immediate = false);
}

stop方法参数说明：

具体示例如下：

asr.stop();      //停止

# 11. 逆初始化

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

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

# 12. SDK API介绍

# 12.1 SparkChainConfig API

# 12.2 SparkChain API

# 12.3 ASR API

# 12.4 ASRResult API

# 12.5 ASRError API

# 12.6 ASR AudioAttributes API

# 13. 错误码

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

# 13.1 SDK错误码

# 13.2 部分云端错误码

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