SDK接入

第一步：导入 SDK

1.引入并依赖SDK。
有两种方法依赖SDK:
(1).通过maven仓库依赖
(2).通过jar依赖
方法一:
(1).项目级别的build.gradle

allprojects {
    repositories {
        maven {
            ...
            url 'https://repo.singsound.com/repository/singsound_ginger_android_sdk/'
        }
    }
}

(2).程序级别的build.gradle

dependencies {
    ...
    implementation 'com.singsound.library:evaluating:2.1.9'
}

(3).将libssound.so文件放到jniLibs目录下对应的 CPU 目录中

方法二:
1.将ssound.jar放到lib文件夹下,并依赖到工程中

2.将libssound.so文件放到jniLibs目录下对应的 CPU 目录中：

安卓SDK下载链接：

https://repo.singsound.com/repository/singsound_ginger_c_sdk/stable/v3.0.1/android/ssound-android-3.0.1-20200824195819.tar.gz

(备注：编码为3的so文件是在线的，编码是71的so文件支持离线+在线混合模式，放到jniLibs目录下面的so需要统一修改名称为libssound.so)

3.将VAD功能资源文件（vad.0.1.bin）放到assets中，vad资源包请联系技术支持人员。

& 注意：使用离线引擎还需将resource.zip引入工程，放到assets中。resource.zip请联系技术支持人员。

第二步：添加用户权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

第三步：添加混淆代码

-keep class com.tt.** { *; }
-keep class com.xs.** { *; }
-keep interface com.xs.** { *; }
-keep enum com.xs.** { *; }

示例代码

1. 初始化引擎

private void initEngine() {
        new Thread() {
            @Override
            public void run() {
                try {
                    // 获取引擎实例,设置测评监听对象
                    mEngine = SingEngine.newInstance(MainActivity.this);
                    // 设置引擎测评监听器
                    mEngine.setListener(mResultListener);
                    // 设置录音器初始化错误的回调
                    mEngine.setAudioErrorCallback(mAudioErrorCallback);
                    // 设置音频格式
                    mEngine.setAudioType(AudioTypeEnum.WAV);
                    // 设置引擎类型
                    mEngine.setServerType(CoreProvideTypeEnum.AUTO);
                    // 设置log日志级别
                    mEngine.setLogLevel(4);
                    // 禁用实时音量返回
                    mEngine.disableVolume();
                    // 设置是否开启VAD功能
                    mEngine.setOpenVad(false, null);
                    // engine.setOpenVad(true, "vad.0.1.bin");
                    // 构建引擎初始化参数
                    JSONObject cfgInit = mEngine.buildInitJson(mAppkey, mSecretKey);
                    // 设置引擎初始化参数
                    mEngine.setNewCfg(cfgInit);
                    // 初始化引擎
                    mEngine.createEngine();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        }.start();
    }

& 注：对于旧版的客户，在集成时需要重新按照第一步的SDK接入下的step 3重新配置一下build.gradle文件，然后将newEngine()改为createEngine()即可。

2. 设置请求具体参数，并开始评测。

private void start() {
    try {
        JSONObject request = new JSONObject（）；
        request.put("coreType", Config.TYPE_sent)；
        request.put("refText", mCurrentSentence)；
        request.put("rank", 100);
        // 构建评测请求参数
        JSONObject startCfg =  mEngine.buildStartJson(userId，request);
        // 设置评测请求参数
        mEngine.setStartCfg(startCfg);
        // 开始测评
        mEngine.start();
    } catch (Exception e) {
        e.printStackTrace();
    }
}

3. 手动停止录音，等待评测

private void stop() {
    mEngine.stop();
}

4. 获取评测结果

通过ResultListener.onResult(JSONObject result);方法得到结果，返回的JSON返回格式请参考《语音评测引擎参考》。

SingEngine API 说明

1. 获取SDK版本号

public String getVersionName()

获取当前SDK的版本号。

2. 获取引擎实例

public static SingEngine newInstance(Context context)

参数名	说明
context	上下文

获取引擎实例。

3. 设置测评结果监听器

public void setListener(ResultListener listenner)

参数名	说明
listenner	测评监听器

& 备注: 开发者必须实现此接口，否则无法获得评测结果。

4. 设置测评结束时的回调

public void setOnEndCallback(OnEndCallback callback)

参数名	说明
callback	测评结束时的回调

5. 获得开始评测时的requestId

public void setEvalReturnRequestIdCallback(EvalReturnRequestIdCallback callback)

参数名	说明
callback	获取requestId的回调

& 备注: 测评结束时的回调

6. warrantId需要更新的回调

public void setWarrantIdNeedUpdateCallback(WarrantIdNeedUpdateCallback callback)

参数名	说明
callback	warrantid过期的回调

& 备注: 鉴权时间在过期前的15分钟开始触发

7. 设置录音器初始化错误的回调

public void setAudioErrorCallback(AudioErrorCallback callback)

参数名	说明
callback	录音器初始化错误监听器

8. 设置压缩音频流的监听器

public void setOnCompressAudioStreamback(OnCompressAudioStreamCallback callback)

参数名	说明
callback	压缩音频流的监听器

9. 设置引擎类型

public void setServerType(CoreProvideTypeEnum type)

引擎类型（在线CLOUD、离线NATIVE、混合AUTO），默认使用在线引擎。

参数名	说明
type	CLOUD, NATIVE, AUTO

10. 设置评测语言（针对离线评测）

public void setOffLineSource(OffLineSourceEnum offLineEnum)

评测语言（英文SOURCE_EN、中文SOURCE_CH、中英文SOURCE_BOTN），默认使用英文。

参数名	说明
offLineEnum	SOURCE_EN, SOURCE_CH, SOURCE_BOTN

11. 设置离线资源名称

public void setNativeZip(String resourceName)

改变离线压缩包名称后需设置，默认不需要设置。

12. 设置解压后的离线资源路径

public void setUserNativeUnZipPath(String nativeUnZipPath)

需要调用本地离线资源文件时设置，路径指定到eval的上一层文件夹，默认不需要设置。

13. 设置自定义的离线资源zip路径

public void setUserNativeZipPath(String nativeZipPath)

离线资源zip默认放到assets目录，也可以通过改方法自定义存放路径，默认不需要设置。

14. 设置采样率

public void setSampleRate(long sampleRate)

& 备注: 开始评测时设置音频的设置采样率

15. 设置采样字节数

public void setSampleBytes(int sampleBytes)

& 备注: 开始评测时设置音频采样字节数

16. 设置声道

public void setChannel(int channel)

& 备注: 开始评测时设置音频的声道

17. 设置是否开启压缩音频流回调 0：不支持 1：支持

public void setSaveAudio(int saveAudio)

18. 设置压缩格式

public void setCompress(String compress)

19. 设置在线服务器地址

public void setServerAPI(String serverAPI)

20. 设置测试服务器地址

public void setTestServerAPI(String testServerAPI)

默认不需要设置，会使用内置地址。

21. 启动实时评测配置

public void enableRealTimeMode()

& 备注: 在开始评测之前调用

22. 取消实时评测配置

public void disableRealTimeMode()

& 备注: 在开始评测之前调用(默认情况)

23. 启用实时音量返回

public void enableVolume()

& 备注: 默认时开启状态

24. 禁用实时音量返回

public void disableVolume()

25. 设置评分超时时间

public void setServerTimeout(long serverTimeout)

单位秒，默认60秒。

26. 设置引擎连接超时时间

public void setConnectTimeout(long connectTimeout)

单位秒，默认20秒.不可低于5s。

27. 是否开启异步测评

public void setEnableAsync(int enableAsync)

默认关闭

参数名	说明
enableAsync	0 为不开启，1 为开启

28. 在线失败后,是否自动转离线

public void setEnableContonative(int enableContonative)

默认关闭

参数名	说明
enableContonative	0 为不开启，1 为开启

& 备注：前提是离线资源必须是已经加载状态

29. 是否启用ws服务器, 默认用wss

public void setEnableWS(boolean isEnableWS)

默认使用wss

参数名	说明
isEnableWS	true 为开启ws ，false为开启wss

30. 设置鉴权信息

public void setAuthInfo(String warrantId, long authTimeout)

参数名	说明
warrantId	鉴权信息
authTimeout	鉴权信息的过期时间

31. 切换log的保存状态

public void switchLog(boolean androidLogOn, boolean localLogOn)

参数名	说明
androidLogOn	studio是否打印log
localLogOn	是否给本地打印日志

默认androidLogOn：true, localLogOn：false

32. 设置是否要在IDE上打印日志,默认打开

public void setOutputLog(boolean isOutputLog)

true为打开，false为关闭，默认启用。

33. 设置 Log 级别

public void setLogLevel(long logLevel)

默认为3，只输出报错日志。

34. 开始测评时,是否启用vad

public void setVadEnable(int vadEnable)

默认开启

参数名	说明
vadEnable	0 为不开启，1 为开启

35. 设置是否开启 VAD 功能

public void setOpenVad(boolean vad，String vadResourceName )

引擎默认关闭 VAD 功能。

参数名	说明
vad	true 为开启，false 为关闭
vadResourceName	关闭时，可设置为 null；开启时，设置为 vad 功能资源文件名

& 功能说明：开启后，录音一段时间后不说话自动调用引擎stop()，结束录音并返回评测结果。

36. 开启错误日志保存到本地

public void setOpenWriteLog(boolean mIsWriteLog)

默认是不开启状态。

参数名	说明
mIsWriteLog	true 为开启，false 为关闭

& 功能说明：开启后，发生错误时文件中会保存到android/data/包名/files/SSError.txt中,一次记录会占用空间2.44k,请及时清理。

37. 设置录音时,是否增强测评稳定性

public void setOpenEvalStability(boolean evalStability)

默认是不开启状态。

参数名	说明
evalStability	true 为开启，false 为关闭

38. 设置离线授权的地址

public void setAuthenServer(String authenServer)

参数名	说明
authenServer	离线证书的地址

39. 设置 VAD 前置超时时间

public void setFrontVadTime(long frontVadTime)

设置前置 vad 时间，时间超时后会触发onFrontVadTimeOut回调。（即：前置超时的意思是，在开始录音时（也就是调用start方法后）在设置的时间内没有声音录入就会触发前置超时。）

& 引擎默认前置 vad 超时时间为 2s
& 单位为毫秒，需乘1.5。例如：想设为 2s，需设置为 3000(2000 * 1.5)

40. 设置 VAD 后置超时时间

public void setBackVadTime(long backVadTime)

设置后置vad时间，时间超时后会触发onBackVadTimeOut并自动测评，返回结果。（即：后置超时的意思是，在录音过程中，如果在设置的时间内没有声音录入了，就会触发后置超时，并且sdk会自动调用stop方法，返回结果。）

& 引擎默认后置 vad 超时时间为 2s
& 单位为毫秒，需乘2.5。例如：想设为 2s，需设置为 5000(2000 * 2.5)

41. 设置录音音频路径

public void setWavPath(String wavPath)

路径为包含音频存储文件夹路径或者包含音频名称的全路径。

42. 设置录音音频格式

public void setAudioType(AudioTypeEnum audioType)

参数名	说明
audioType	PCM, WAV

& 备注：默认不需要设置，默认是 WAV。

43. 设置评测时的音频格式

public void setAudioTypeForEva(AudioTypeForEvaEnum audioTypeForEva)

参数名	说明
audioTypeForEva	PCM, WAV, MP3

& 备注：默认不需要设置，默认是 WAV。

44. 设置本地文件评测feed数据时的间隔时间

public void setLocalEvaluationBlankSleepTime(long sleepTime)

单位毫秒，默认10毫秒。

45. 上传crash日志

public static void uploadLog(Context context, String AppKey, String uid, UploadLogListener callback)

参数名	说明
context	上下文对象
AppKey	商户的AppKey
uid	用户唯一标识
callback	上传日志的回调

& 备注：该方法不依赖于引擎对象,是静态方法
& 状态码：callback回调中的状态码说明

状态吗	说明
0	上传成功
1	正在上传
2	文件不存在
3	文件中没数据
4	上传失败
5	无网络

46. 清理默认路径下的音频

public static boolean clearWavWithDefaultPath(Context context)

备注：该方法只会清理掉android/data/包名/files/record/文件下的音频，注意：record目录也会删掉。

47. 构建引擎初始化参数

public JSONObject buildInitJson( String appKey， String secretKey)

替换为your app的appKey，secretKey备注：请生成appKey，secretKey并替换。

48. 设置引擎初始化参数

public void setNewCfg(JSONObject cfg)

cfg为构建的引擎参数。

49. 引擎初始化

public void createEngine()

创建引擎对象，成功后回调ResultListener.onReady()方法。
& 此方法动态获取当前可用的评测服务器地址，从而达到减少连接服务器错误的产生，当有和网络相关的评测失败回调时，会自动重新初始化，获取当前可用的评测服务器地址，需要等待引擎初始化成功回调时，再进行下一次评测

50. 构建评测请求参数

public JSONObject buildStartJson(String UserId， JSONObject request)

构建默认评测请求参数JSON，根据不同题型传入相对应的参数。

& UserId 为用户的 UserId，若没有可设置为 “guest”

51. 设置评测请求参数

public void setStartCfg(JSONObject cfg)

设置评测参数，cfg 为评测请求参数。

52. 开始评测

public void start()

启动引擎开始评测，开始进行录音。如果启动失败，会回调ResultListener.onEnd()，通知启动评测引擎失败。

53. 开始评测(本地音频文件)

public void startWithPCM(String filePath)

启动引擎开始本地音频文件评测。

54. 开始评测(用于使用第三方录音机开始评测)

public void startWithCustomAudio()

& 备注:
商户要使用第三方的录音机进行评测
使用场景:商户要使用第三方的录音机进行实时评测

& 使用说明:
1.开始评测时要调用startWithCustomAudio()方法
2.数据流通过ssoundFeedWithCustomAudio(byte[] data, int size)方法实时的向引擎中传递数据
3.停止录音时,调用stopWithCustomAudio()方法,数据会通过onResult()回调给上层用户
4.取消引擎,调用cancelWithCustomAudio()方法
5.删除引擎,调用delete()方法

& 注意:
1.在用第三方录音机测评时,在停止、取消、删除引擎前,请先关闭第三方录音机,避免出现引擎已经停止工作,但数据还在向引擎中传递的情况
2.在使用vad功能时,当检测到后置超时的时候,请在后置超时的回调里关闭第三方录音机,再关闭引擎.
3.在进行第三方录音实时评测时,onPlayCompeleted()回调方法是不会执行的

55. 用户使用第三方录音机实时的向引擎中传递数据

public void ssoundFeedWithCustomAudio(byte[] data, int size)

商户要使用第三方的录音机进行评测

56. 用于使用第三方录音机评测时,停止引擎

public void stopWithCustomAudio()

商户要使用第三方的录音机进行评测

57. 停止评测

public void stop()

停止录音，等待评测结果，通过回调ResultListener.onResult()返回测评结果。如果失败，会回调ResultListener.onEnd()，通知停止评测引擎失败。

58. 取消评测

public void cancel()

取消引擎，用于出现异常情况下，用户可以取消引擎，取消后不再回调接口函数。
& 备注：建议使用该方法取消测评

59. 取消评测

public void cancelQuiet()

取消引擎，用于出现异常情况下，用户可以取消引擎，取消后不再回调接口函数。

60. 用于使用第三方录音机评测时,取消引擎

public void cancelWithCustomAudio()

商户要使用第三方的录音机进行评测

61. 销毁引擎

public void delete()

销毁当前引擎。

62. 关闭录音,再销毁引擎

public void deleteSafe()

先关闭录音机，然后再销毁当前引擎。

63. 获取音频路径

public String getWavPath()

获取用户录音存放的路径。

64. 录音回放（指定路径）

public void playback(String path)

根据用户的文件路径回放用户的录音。

65. 录音回放

public void playback()

回放用户的最近一次录音。

66. 结束录音回放

public void stopPlayBack()

根据用户的文件路径回放用户的录音。

67. 网络异常重传

public void setEnableRetry(int enableRetry)

SDK收到特定的网络错误时，会自动重新评测一次（不论成功或者失败，都会以回调形式通知上层应用）。

Result API 说明

注意：用户实现该接口后，需要在UI线程更改UI或子线程耗时操作。

通过SingEngine的setListener方法来设置ResultListener，监听评测引擎返回的各种状态。

1. 引擎初始化成功回调

void onReady();

用来接收引擎初始化成功的消息

2. 录音开始回调

void onBegin();

提示用户开始录音

3. 录音音量回调

void onUpdateVolume(int volume);

实时返回用户录音的音量大小录音过程中会不断的回调此方法，实时返回音量大小，volume取值范围为0\~100。用户可以根据volume的大小来实现用户录音音量大小的动画效果。

4. 录音数据回调

void onRecordingBuffer(Byte[] data);

返回用户录音的数据录音过程中会重复调用此方法，数据保存在data中。

5. VAD 后置超时回调

void onBackVadTimeOut();

录音一段时间后不说话，后置超时，引擎自动调用stop()，结束录音并返回结果。
& 用户可监听此方法用于更新录音的UI界面

6. VAD 前置超时回调

void onFrontVadTimeOut();

开启录音后,一直没有声音输入，前置超时（检测到没有录音），会调用此方法用户可自己决定操作stop()或者cancel()。

7. 评测结果回调

void onResult(JSONObject result);

返回评测结果，评测结果为JSON格式，结果详情见《语音评测引擎参考》。

8. 实时反馈回调

void onRealTimeEval(JSONObject result);

实时的返回数据，数据为JSON格式，结果详情见《语音评测引擎参考》。

9. 评测错误码回调

void onEnd(ResultBody resultBody);

返回评测或初始化引擎失败原因，resultBody.getCode() 等于 0 为正确返回，其他错误码见下错误码说明。

10. 评测录音长度超时回调

void onRecordLengthOut();

开发者可在该回调里调用stop()方法等待返回测评结果，或不做任何处理等待录音超时的错误码。通过超时错误码提示产品的用户。每个题型的录音时长限制如下：

11. 播放录音完成回调

void onPlayCompeleted();

客户可在该回调里做一些更新UI的操作。

12. 当录音停止并写入成功后回调

void onRecordStop();