# SparkChain 语音转写 Android SDK集成文档

# 1. 语音转写简介

语音转写（Long Form ASR）基于深度全序列卷积神经网络，将长段音频（5小时以内）数据转换成文本数据，为信息处理和数据挖掘提供基础。 转写的是已录制音频（非实时），音频文件上传成功后进入等待队列，待转写成功后用户即可获取结果，返回结果时间受音频时长以及排队任务量的影响。 如遇转写耗时比平时延长，大概率表示当前时间段出现转写高峰，请耐心等待即可，我们承诺有效任务耗时最大不超过5小时，详情请参考SLA协议 (opens new window)。 另外，为使转写服务更加通畅，请尽量转写5分钟以上的音频文件，上传大量的短音频易引起网络和服务器资源紧张，从而导致任务排队积压。 音频时长与理论返回时间可以参考下表（请注意，实际返回时长受上传的音频时长和任务总量影响，忙时会出现任务排队情况）：

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

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

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

public class RAASR {
    public RAASR(String apiKey) {
        ...
    }
}

构造方法参数说明：

具体示例如下：

RAASR mRAASR = new RAASR(raAsrApiKey);//rtAsrApiKey参见应用中实时转写栏里的apikey

# 8. 功能参数配置

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

具体配置示例如下：

mRAASR.transLanguage("en");//翻译目标语种
mRAASR.language("cn");//识别语种
...
mRAASR.roleType(0);//是否开启角色分离,0:关闭，1:打开

# 9. 注册结果监听回调

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

public interface RAASRCallbacks {    

   void onResult(RAASR.RaAsrResult result, Object usrTag);
   
   void onError(RAASR.RaAsrError error, Object usrTag);
}

RAASRCallbacks 数据结构说明：

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

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

• RTASR.RtAsrResult结构说明：

  方法	返回值类型	说明
  getStatus()	int	订单流程状态 0：订单已创建 3：订单处理中 4：订单已完成 -1：订单失败
  getOrderResult()	String	转写结果
  getTransResult()	RAASR.RaAsrTransResult[]	翻译结果实例
  getOrderId()	String	转写订单ID
  getFailType()	int	订单异常状态 0：音频正常执行 1：音频上传失败 2：音频转码失败 3：音频识别失败 4：音频时长超限（最大音频时长为 5 小时） 5：音频校验失败（duration 对应的值与真实音频时长不符合要求） 6：静音文件 7：翻译失败 8：账号无翻译权限 9：转写质检失败 10：转写质检未匹配出关键词 11：upload接口创建任务时，未开启质检或者翻译能力； 备注： resultType=translate，未开启翻译能力； resultType=predict，未开启质检能力； 99：其他
  getOriginalDuration()	long	原始音频时长，单位毫秒
  getRealDuration()	long	真实音频时长，单位毫秒
  getTaskEstimateTime()	int	订单预估耗时，单位毫秒

• RAASR.RaAsrTransResult结构说明：

  方法	返回值类型	说明
  getSegId()	String	段落序号
  getDst()	String	翻译结果
  getBg()	int	开始时间
  getEd()	int	结束时间
  getTags()	List	标签
  getRoles()	List	角色

• 通过getOrderResult()方法获取到的转写结果为云端下发的原始结果，SDK本身不解析此结果。开发者需自行解析原始结果(可参考demo中的解析步骤)。云端下发的json结果各字段含义如下：

1. orderResult结果字段：

   参数名	类型	描述
   lattice	List	做顺滑功能的识别结果
   lattice2	List	未做顺滑功能的识别结果
   label	Object	转写结果标签信息，用于补充转写结果相关信息，目前开启双通道转写时该对象会返回，标记转写结果角色和声道的对应关系

2. Lattice 字段：

   参数名	类型	描述
   json_1best	String	单个 vad 的结果的 json 内容

3. json_1best 字段：

   参数名	类型	描述
   st	Object	单个句子的结果对象

4. st 字段：

   参数名	类型	描述
   bg	String	单个句子的开始时间，单位毫秒
   ed	String	单个句子的结束时间，单位毫秒
   rl	String	分离的角色编号，取值正整数，需开启角色分离的功能才返回对应的分离角色编号
   rt	List	输出词语识别结果集合

5. ws 字段（词语候选识别结果）：

   参数名	类型	描述
   wb	Long	词语开始的帧数（注一帧 10ms），位置是相对 bg，仅支持中、英文语种
   we	Long	词语结束的帧数（注一帧 10ms），位置是相对 bg，仅支持中、英文语种
   cw	List	词语候选识别结果集合

6. cw 字段：

   参数名	类型	描述
   w	String	识别结果
   wp	String	词语的属性 n：正常词 s：顺滑 p：标点 g：分段（按此标识进行分段）

7. label 字段：

   参数名	类型	描述
   rl_track	List	双通道模式转写结果中角色和音频轨道对应信息，开启分轨模式该字段会返回

8. rl_track 字段：

   参数名	类型	描述
   rl	String	分离的角色编号，取值正整数
   track	String	音频轨道信息 L：左声道，R：右声道

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

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

• RAASR.RaAsrError结构说明：

  方法	返回值类型	说明
  getCode()	int	错误码
  getErrMsg()	String	错误信息
  getOrderId()	String	转写订单ID
  getFailType()	int	订单异常状态

具体示例如下：

RAASRCallbacks mRAASRCallbacks = new RAASRCallbacks() {
    @Override
    public void onResult(RAASR.RaAsrResult result, Object o) {
        int status                            = result.getStatus();//订单流程状态
        String orderResult                    = result.getOrderResult();//转写结果
        RAASR.RaAsrTransResult[] transResults = result.getTransResult();//翻译结果实例
        String orderId                        = result.getOrderId();//转写订单ID
        int failType                          = result.getFailType();//订单异常状态
        long originalDuration                 = result.getOriginalDuration();//原始音频时长，单位毫秒
        long realDuration                     = result.getRealDuration();//真实音频时长，单位毫秒
        int taskEstimateTime                  = result.getTaskEstimateTime();//订单预估耗时，单位毫秒
    }

    @Override
    public void onError(RAASR.RaAsrError raAsrError, Object o) {
        String errMsg  = raAsrError.getErrMsg();//错误信息
        int errCode    = raAsrError.getCode();//错误码
        String orderId = raAsrError.getOrderId();//转写订单ID
        int failType   = raAsrError.getFailType();//订单异常状态
    }
};
mRAASR.registerCallbacks(mRAASRCallbacks);

# 10. 请求调用

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

public class RAASR {
    public int aRun(String fileName,String resultType,Object usrTag) {        
        ...
    }
}

aRun方法结构说明：

具体示例如下：

String filePath = "/sdcard/iflytek/asr/cn_test.pcm";
String resultType = "transfer";
mRAASR.aRun(filePath,resultType,"12345");

# 11. 结果查询

开发者调用arun方法后，SDK会每隔5秒自动请求服务去查询转写结果。当SDK查询到结果后，会把结果通过onResult方法返回。开发者可通过该方法获取本次转写的orderId，然后根据orderId进行结果查询。查询方法结构如下：

public class RAASR {
    public int aGetResult(String orderId,String resultType,Object usrTag) {        
        ...
    }
}

aGetResult方法结构说明：

具体示例如下：

String resultType = "transfer";
mRAASR.aGetResult(orderId,resultType,"12345");

# 12. 转写语种支持

# 13. 逆初始化

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

SparkChain.getInst().unInit();  //SDK逆初始化

# 14. SDK API介绍

# 14.1 SparkChainConfig API

# 14.2 SparkChain API

# 14.3 RAASR API

# 14.4 RTASRResult API

# 14.5 RTASRError API

# 14.6 RAASRTransResult API

# 15. 错误码

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

# 15.1 SDK错误码

# 15.2 部分云端错误码