# SparkChain 语音听写 Android 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

│ └── 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. 语音听写初始化

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

语音听写构造方法如下：

public class ASR{
    public ASR(String language, String domain, String accent) {
        ...
    }
    
    public ASR() {
        
    }
}

构造方法参数说明：

具体示例如下：

ASR mAsr = new ASR();
//ASR mAsr = new ASR("zh_cn","iat","mandarin");

# 8. 功能参数配置

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

具体配置示例如下：

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

# 9. 注册结果监听回调

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

public interface AsrCallbacks {    

    void onResult(ASR.ASRResult result, Object usrTag);
        
    void onError(ASR.ASRError error, Object usrTag);
}

AsrCallbacks数据结构说明：

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

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

• ASR.ASRResult结构说明：

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

• Vad结构体说明：

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

• Transcription结构体说明：

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

• Segment结构体说明：

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

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

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

• ASR.ASRError结构说明：

  方法	返回值类型	说明
  getCode()	int	错误码
  getErrMsg()	String	错误信息
  getSid()	String	交互的Sid

具体示例如下：

AsrCallbacks mAsrCallbacks = new AsrCallbacks() {
    int begin     = asrResult.getBegin();         //识别结果所处音频的起始点
    int end       = asrResult.getEnd();           //识别结果所处音频的结束点
    int status    = asrResult.getStatus();        //结果数据状态
    String result = asrResult.getBestMatchText(); //识别结果
    String sid    = asrResult.getSid();           //sid

    List<Vad> vads = asrResult.getVads();
    for(Vad vad:vads){
        int vad_begin = vad.getBegin();           //vad起始点
        int vad_end = vad.getEnd();               //vad结束点   
    }
    List<Transcription> transcriptions = asrResult.getTranscriptions();
    for(Transcription transcription : transcriptions){
        List<Segment> segments = transcription.getSegments();
        for(Segment segment:segments){
            word = segment.getText();              //字词结果
        }
    }

}
mAsr.registerCallbacks(mAsrCallbacks);

# 10. 请求调用

# 10.1 开启会话

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

public class ASR {
    public int start(Object usrTag) {        
        ...
    }
    
    public int start(AudioAttributes attributes, Object usrTag) {        
        ...
    }
}

• start方法结构说明：

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

• AudioAttributes结构说明：

  方法名	返回值类型	参数名	参数类型	说明
  setSampleRate	void	mSampleRate	int	输入音频的采样率，支持8k和16k
  setEncoding	void	mEncoding	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

具体示例如下：

int ret = mAsr.start("12345");

//带有AudioAttributes的start示例如下，开发者根据自身需求二选一即可。
//AudioAttributes attr = new AudioAttributes();
//attr.setSampleRate(16000);
//attr.setEncoding("raw");
//attr.setChannels(1);
//attr.setBitdepth(16);
//int ret = asr.start(attr,"12345");

# 10.2 送入数据

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

public class ASR {
    public int write(byte[] data) {
        ...
    }
}

write方法参数说明：

具体示例如下：

byte[] data = new byte[1280]; 
...//省略获取音频的过程 
mAsr.write(data);

# 10.3 结束会话

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

public class ASR {
    public int stop(boolean immediate) {
        ...
    }

}

stop方法参数说明：

具体示例如下：

mRTASR.stop();      //停止

# 11. 逆初始化

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

SparkChain.getInst().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) 查询。