1.1. 修订记录

1.2. 概述

本文档说明如何通过开放SDK对接背景音乐主机的语音能力，该对接方式是提供给安装在屏上的应用使用，包含以下功能：

1. 语音合成（TTS 播报）
2. 拦截语义自行处理（唤醒后的语控指令可以以文本形式获取，自行处理）
3. 语音设置（语速、音量、唤醒开关、唤醒词、唤醒回复方式、识别停顿时间等）
4. 主动唤醒、主动结束对话、暂停播报
5. 热词添加（按设备/场景/楼层/房间四类词库上传）
6. 本地语法开关

音乐播控、本地/推荐歌单、485数据收发、模式切换、分区设置等功能请查看 JdPlayOpenSdk。

1.3. 公共接入配置

1.3.1. 下载demo

百度网盘下载链接: 链接: https://pan.baidu.com/s/179xcJ6HirWoDVofAcsJN5A 密码: 3vix

路径：JdRelease/jd_music_and_voice_open_sdk

demo需安装并运行于背景音乐主机中，安装完成后重启机器。

1.3.2. 导入核心包

将demo内部两个核心包导入：jdbase-release.aar 和 jdmusic-release-X.X.XX.aar 导入项目

repositories{
    flatDir{
        dirs'libs'
    }
}
dependencies {
    compile fileTree(include: ['*.jar'], dir: 'libs')
    compile(name: 'jdbase-release', ext: 'aar')
    compile(name: 'jdmusic-release-X.X.XX', ext: 'aar')
}

1.3.3. 添加权限

在AndroidManifest.xml中添加如下权限

1.3.4. 初始化

public class App extends Application{
    @Override
    public void onCreate() {
        super.onCreate();
        JdPlayPresenter.getInstance().init(this);
    }
}

1.4. 语音相关关键类

1.5. 接口使用说明

1.5.1. TTS

public class TTS {
    //不操作
    public static final int TYPE_NONE = 0;
    //进入识别
    public static final int TYPE_ASR = 1;
    //进入唤醒
    public static final int TYPE_WAKE_UP = 2;
    //TTS 内容
    private String tts;
    //是否打断当前播放的
    private boolean canInterrupt;
    //TTS类型
    private int ttsType;
}

1.5.2. JdVoicePresenter

回调函数

public interface IVoiceCallBack {
    boolean onAsrResult(String var1, VoiceExeBack var2);
    void onVoiceState(int var1);
    interface VoiceExeBack{
        @Deprecated
        void onSuccess(String var1);
        @Deprecated
        void onFail(String var1);
        void onSuccess(TTS var1);
        void onFail(TTS var1);
    }
}

boolean onAsrResult(String var1, VoiceExeBack var2)
参数
* var1 识别内容
* var2 拦截语义处理成功或者失败后回调 (处理完成后通过 VoiceExeBack 的onSuccess(TTS tts) 或者 onFail(TTS tts) 返回自行处理需要播放的TTS)
返回值
* true 拦截语义自己处理 
* false 不拦截交给主机处理
注意，有两种情况下背景音乐会处理语义
1. onAsrResult返回false时
2. onAsrResult返回true时， VoiceExeBack最终回调是onFail(TTS tts)

void onVoiceState(int var1)
参数
* var1 voice_state 状态回调 状态对应如下：
    //语音对话开始
    public static final int VOICE_STATE_SESSION_START = 10001;
    //识别开始录音
    public static final int VOICE_STATE_ASR_START_SPEECH = 10003;
    //识别录音结束
    public static final int VOICE_STATE_ASR_END_SPEECH = 10004;
    //开始语义识别
    public static final int VOICE_STATE_ASR_RECOGNITION = 10005;
    //语音对话结束
    public static final int VOICE_STATE_SESSION_END = 10008;
    //TTS 播放开始
    public static final int VOICE_STATE_TTS_START = 10006;
    //TTS 播放结束
    public static final int VOICE_STATE_TTS_FINISH = 10007;

主要方法

void setIVoiceCallBack(IVoiceCallBack callBack)
设置语音处理回调
参数
* callBack 回调方法

热词添加

拦截语音获取语义时，某些不好识别的设备名或场景名，可以设置热词，防止语控时识别不到。

//该方法属于 JdPlayPresenter，不是 JdVoicePresenter
void updateVocab(String var1, HashSet var2)
上传关键字到服务器，提高识别精度
参数
* var1 词库类型，取 JdVoiceConstants 中的常量
* var2 热词集合，不能为空且至少包含一个词

词库类型由 JdVoiceConstants 提供，需要分别调用：

import com.judian.jdmusicsdk.entity.JdVoiceConstants;

private void uploadHotWord(){
    HashSet devHashSet = new HashSet<>();
    HashSet sceneHashSet = new HashSet<>();
    devHashSet.add("星星");
    devHashSet.add("月亮");
    sceneHashSet.add("欢迎光临");
    sceneHashSet.add("工作模式");
    //设备词库
    mPresenter.updateVocab(JdVoiceConstants.VOCAB_NAME_DEVICE, devHashSet);
    //场景词库
    mPresenter.updateVocab(JdVoiceConstants.VOCAB_NAME_SCENE, sceneHashSet);

}

具体添加可以查看demo中JdVoiceFragment 注意修改完编译安装到背景主机上时，需要重启下主机

1.5.3. JdPlayPresenter 语音相关方法

TTS 播报

void playTTS(String var1, boolean var2)  此方法已过时
播放TTS 
参数
* var1 播放文本
* var2 是否打断当前播放的TTS

void playTTS(String var1) 此方法已过时
播放TTS 
参数
* var1 播放文本

void playTTS(TTS var1)
播放TTS
参数
* var1 播放TTS 类型数据

void setSpeed(String speed)
设置TTS播报语速
* speed 取值0.5-2.0，0.5语速最快，2.0语速最慢

void shutUp()
暂停播报

语义与语法

void enableSmartDeviceGrammar(boolean var1)  
禁用本地语法
参数
* var1 是否启用本地智能设备控制语法，SDK 内部默认值为 true
说明：需要自行拦截语义处理时，demo 中会在设置回调后显式传入 false 关闭本地语法



#### 唤醒与对话

``` java
void wakeUp(String wakeUpTip)
主动唤醒，不会弹出唤醒页，屏主机会处于唤醒状态，可以直接进行语控。
* wakeUpTip 传入播报文本，调用后会先播报，在处于唤醒状态

void wakeUpWithUi(String wakeUpTip)
主动唤醒，弹出唤醒页（这里是和wakeUp的区别），可以直接进行语控。
* wakeUpTip 传入播报文本，调用后会先播报，在处于唤醒状态

void stopChat()
主动结束对话

void voiceReply(String reply)
选择唤醒回复方式，reply传入的值如下
* "silent"  静音
* "tone"  提示音
* "voiceReply"  语音回复

唤醒开关与唤醒词

void voiceSwitch(boolean open)
语音唤醒开关
* open   true / false 表示开启还是关闭唤醒
需要获取语控唤醒开关初始状态的话，可以查询属性值获取：
可以通过集成jdsmart-common包调用获取，[点击下载jdsmart-common](http://upyun.aispeaker.com/externalDocFiles/jdsmart-common.aar)
String status=JdSystemProperty.getString("persist.sys.jd.voice.switch", "0");
status 1是打开，0是关闭

void voiceWakeupWord(String word, String threshold)
修改唤醒词
*  word  唤醒词 建议 3-6 个字符，唤醒词在"你好小*"时 唤醒率最高. 传""时，默认"你好 小可"
*  threshold  阈值  范围：" 0.1 - 1.0 "，可以传空值.
*  阈值越低，唤醒越灵敏
*  阈值默认 2MIC -- 0.18
*          4MIC -- 0.25 （X8 默认 0.18）
*  建议在默认值上下调节 0.1 - 0.3
生效方式（因机型而异）：
*  S10、X8  实时更新，不需要重启
*  C7  3秒后重启语音，可以给用户一个提示（后续可以实时更新）

void getDeviceMic(JdbaseCallback jdbaseCallback)
获取设备MIC值,表示是几麦的机器（目前大部分是2MIC和4MIC），配合voiceWakeupWord使用
回调
* JdbaseCallback.onResult(int code, String data1, String data2)
  MIC值取 data1 参数

mJdPlayPresenter.getDeviceMic(new JdbaseCallback() {
    @Override
    public void onResult(int code, String data1, String data2) {
        Log.d(TAG, "get_mic = " + data1);
    }
});

音量控制

setVolume(String vol)
控制音量
* vol 音量大小，取值1-100

注意：以上方法部分机型不适用

1.6. 完整接入示例

以下为demo中 JdVoiceFragment 的语音拦截对接流程，实现 IVoiceCallBack 接口即可：

public class JdVoiceFragment extends BaseFragment implements IVoiceCallBack {

    private JdVoicePresenter mJdVoicePresenter;
    private JdPlayPresenter mPresenter = JdPlayPresenter.getInstance();

    @Override
    public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
        //1. 注册语音回调
        mJdVoicePresenter = JdVoicePresenter.getInstance();
        mJdVoicePresenter.setIVoiceCallBack(this);
        //2. 禁用本地智能设备控制语法，改由自己处理语义
        mPresenter.enableSmartDeviceGrammar(false);
        //3. 上传热词，提高设备名/场景名识别率
        uploadHotWord();
        return mRootView;
    }

    @Override
    public void onDestroyView() {
        super.onDestroyView();
        //4. 页面销毁时反注册，避免回调泄漏
        mJdVoicePresenter.setIVoiceCallBack(null);
    }

    @Override
    public boolean onAsrResult(final String result, final VoiceExeBack voiceExeBack) {
        //回调不保证在主线程，更新UI需切回主线程
        getActivity().runOnUiThread(new Runnable() {
            @Override
            public void run() {
                mAsrResut.setText(result);
            }
        });

        //模拟处理语音结果，耗时操作自行起线程
        new Thread(new Runnable() {
            @Override
            public void run() {
                try {
                    Thread.sleep(1500);
                } catch (InterruptedException e) {
                    e.printStackTrace();
                }
                //处理完成，返回需要播报的TTS内容
                TTS tts = new TTS();
                tts.setTts(result);
                tts.setCanInterrupt(false);
                tts.setTtsType(TTS.TYPE_ASR);
                voiceExeBack.onSuccess(tts);

                //处理失败则返回原始识别内容，交由主机处理
                //voiceExeBack.onFail(result);
            }
        }).start();

        //返回 true 表示拦截语义自己处理，返回 false 表示不拦截交给主机处理
        return true;
    }

    @Override
    public void onVoiceState(int state) {
        Log.d(TAG, "onVoiceState state:" + state);
    }
}

对接注意事项：

• onAsrResult 回调不保证在主线程，更新UI需要用 runOnUiThread 切回主线程。demo演示时需要处于JdVoiceFragment页面
• 返回 true 后，必须最终调用 voiceExeBack.onSuccess(TTS) 或 onFail(TTS)。若一直不回调，主机不会接管该语义，用户会感觉"没反应"。
• onSuccess(String) 和 onFail(String) 两个重载已废弃，请统一使用 TTS 参数版本。
• 页面销毁时调用 setIVoiceCallBack(null) 反注册。
• enableSmartDeviceGrammar(false) 与注册回调需要配合使用，否则本地语法仍会消费部分指令。

1.7. 相关文档

• JdPlayOpenSdk —— 开放SDK完整接入说明（音乐播控、485、分区等）