唤醒

开发者可以通过唤醒会话 WakeUpSession 实现语音关键词唤醒事件的相关操作。使用时请注意需要授予程序麦克风录音和文件读写相关权限。

初始化

首先需要通过 WakeUpSession.Builder 的 build() 方法初始化 WakeUpSession

WakeUpSession wakeUpSession = new WakeUpSession.Builder(this)
                                           .build();

Builder 还有其他参数可供配置，具体可参照接口速查手册。

开始/结束监听唤醒语音

• 通过startListen(OnWakeUpListener listener)方法开始监听唤醒的关键词， wakeUpSession 会接收用户通过mic输入的语音流。 wakeUpSession.startListen(new WakeUpSession.OnWakeUpListener() { @Override public void onWakeUpSucceeded() { // 当成功匹配到唤醒词时会进入该回调 }

  	            @Override
  	            public void onWakeupAngle(int angle) { // 通过该回调通知开发者唤醒语音源和机器人的相对角度
  	            }
  
  	            @Override
  	            public void onWakeUpFailed(int errorCode) { // 通过该回调通知开发者唤醒失败事件以及相关错误码
  	            }
  	        });
          

• 停止监听唤醒关键词输入， wakeUpSession 会接收用户通过mic输入的语音流。

  	wakeUpSession.stopListen();

自定义唤醒关键词

SDK 现默认唤醒关键词是「小度小度」。如需自定义唤醒关键词，请发送邮件至robot-bd@baidu.com与我们联系。

自然语言交互

开发者可以通过自然语言理解（Natural Language Understanding）会话管理类 NLUSession来处理语音、文字形式的自然语言输入并返回结果的处理。使用时请注意需要授予程序麦克风录音和文件读写相关权限。

初始化

首先需要通过 NLUSession.Builder 的 build() 方法初始化 NLUSession

（这里需要注意的是，开发者需要通过 addActionHandler 方法添加相应的 ActionHandler 来响应。关于ActionHandler的详细介绍请参考指令响应部分）

NLUSession mNLUSession = new NLUSession.Builder(context)
            .addActionHandler(/*<在这里添加需要的ActionHandler>*/)
               .build();

语音交互

通过调用 NLUSession 实例的 startAudioListening() 方法开始监听语音输入。session会自动执行语音端点检测，并在一轮对话处理完后自动开始下一轮语音输入的监听。

mNLUSession.startAudioListening();

通过调用 NLUSession 实例的 stopAudioListening() 方法停止监听语音输入。

mNLUSession.stopAudioListening();

文字交互

通过调用 NLUSession 实例的 startTextQuery(String query) 方法发起一次语音输入。

mNLUSession.startTextQuery(suggestion);

图像识别

通过调用 NLUSession 实例的 startImageQuery(Bitmap image, RobotAPI.ImageRequestType queryType) 方法发起一次图片识别请求。

mNLUSession.startImageQuery(/*Bitmap Image Goes Here*/, /*Request Type Enum Value Goes Here*/);

指令响应

与开发一个普通的网络程序不同的是——由于自然语言输入的内容需要通过自然语言理解引擎处理后才能分析出意图。所以开发者并不能在用户输入信息后就确定该请求所对应的意图和指令响应是什么。

换句话说，当一个请求发出时，我们无法对请求的返回作出足够确切的预期，直到云端完成信息处理并给予返回时，我们才能知道用户实际输入的指令是什么。一次用户输入的处理大体来讲分为三个阶段：

1. 如果输入为语音数据流，需要先通过Baidu ASR（Automatic Speech Recognition）引擎识别出用户输入的语音流中包含的实际文字信息，这一步会同时将解析出来的文字信息通过回调接口交给机器人开发者；
2. 将文字信息或者图片信息通过网络传输到 RobotOS 云端服务，由 NLU 引擎识别出用户当前的输入中包含的实际意图，并通知NLUSession；
3. NLUSession需要根据意图的不同，来判断当前的用户请求应该作出何种方式的响应。并交由对应的事件处理器（ActionHandler）来执行该指令。

该过程时序图如下：

指令响应时序图

因此，开发者需要根据业务场景，实现以下接口来接收请求结果，并对对应指令做出行为响应。

ActionHandler接口

ActionHandler是SDK中预留给用户的一系列用于处理用户输入中包含的指令的接口。

在一次NLU对话的过程里，ActionHandler负责处理用户下达的指令。由于机器人所面临的业务场景各不相同，开发者需要根据自身的业务场景，传入满足自身业务需要的ActionHandler的实现。SDK负责调用对应的接口方法，接口方法的具体实现交由开发者自由定制。

下面介绍一下机器人所包含的ActionHandler接口：

• IActionHandler：ActionHandler的基类，所有其他的ActionHandler接口都继承自该接口。 public interface IActionHandler { enum State { START, // 表示指令执行开始 ENDED, // 表示指令执行结束 ERROR // 表示指令执行出错 }

  	    /**
  	     * 解析指令并执行
  	     * 
  	     * @param namespace 服务端下发的指令的namespace
  	     * @param name 服务端下发的指令的name
  	     * @param params 参数对象Map，根据不同的namespace和name会有不同的键值。开发者可以在控制台自行配置
  	     * @return 当指令被执行则返回ture，否则返回false，指令会继续下发给其他ActionHandler
  	     */
  	    boolean decodeCommandAndRun(String namespace, String name, Map<String, Object> params);
  
  	    /**
  	     * 设置状态监听器，监听当前ActionHandler状态
  	     * @param 要添加的OnStateChangedListener的实现
  	     */
  	    void addStateListener(OnStateChangedListener listener);
  
  	    /**
  	     * 移除状态监听器
  	     * @param 要移除的OnStateChangedListener的实现
  	     */
  	    void removeStateListener(OnStateChangedListener listener);
  
  	    /**
  	     * 释放资源
  	     */
  	    void release();
  
  	    interface OnStateChangedListener {
  	        void onStateChanged(IActionHandler actionHandler, String actionName, State currentState);
  	    }
  		}

• IMediaPlayer：多媒体播放控制接口

  		public interface IMediaPlayer extends IActionHandler {
  	
  		void setResolution(int width, int height);
  	
  		void playUrl(String contentUrl);
  	
  		void stop();
  	
  		void pause();
  	
  		void resume();
  	
  		void play_prev();
  	
  		void play_next();
  
  		}

• ISoundRenderer：二进制声音文件播报控制接口，用于渲染 Server 端回传的PCM声音数据流并播放。Demo中提供了接口的实现示例，见 com.baidu.robot.demo.actionhandler.PCMPlayer 类。

  		public interface ISoundRenderer extends IActionHandler {
  	
  		    void setup(SoundFormat format);
  	
  		    void renderSound(byte[] rawData, int offset, int len);
  	
  		    void stop();
  	
  		    void pause();
  	
  		    void resume();
  
  		}

• ICardRenderer：负责卡片类型消息（例如富文本信息）的渲染和展示接口。Demo中提供了接口的实现示例，见 com.baidu.robot.demo.actionhandler.TextCardRenderer 类。

  		public interface ICardRenderer extends IActionHandler {
  
  	    /**
  	     * 根据具体的业务需求展现卡片式内容
  	     * @param content 卡片的内容
  	     */
  	    void showCard(String content);
  
  		}

• ISuggestHinter：Suggestion类型消息的展示接口。Demo中提供了接口的实现示例，见com.baidu.robot.demo.actionhandler.TextCardRenderer类。

  		public interface ISuggestHinter extends IActionHandler {
  	
  		    /**
  		     * hint users with suggestions
  		     * @param hint
  		     * @param suggests
  		     */
  		    void showSuggests(String hint, List<String> suggests);
  		}

• ITextDisplater：普通文本的展示接口。Demo中提供了接口的实现示例，见com.baidu.robot.demo.actionhandler.TextCardRenderer类。

  		public interface ITextDisplayer extends IActionHandler {
  	
  		    /**
  		     * rendering normal text content
  		     * @param content
  		     */
  		    void showText(String content);
  		}
  	

• ITTSDevice：用于通过TTS（text-to-speech）播报相关文字返回时调用的TTS实现接口。NLU SDK中包含TTSDevice的默认实现类DefaultTTSDevice，开发者可以直接调用，也可以替换成自己业务逻辑中的TTS模块。

  		public interface ITTSDevice extends IActionHandler {
  	
  		    void setup(String pid, String key, int timbre);
  	
  		    void speak(String content, int volume, int speed, int pitch);
  	
  		    void pause();
  	
  		    void resume();
  	
  		    void stop();
  		}

• IWebViewer：用于加载并展示WebUrl链接的接口

  		public interface IWebViewer extends IActionHandler {
  	
  		    void loadUrl(String webUrl);
  
  		}

实现回调监听接口

• OnAudioEventListener：通过 NLUSession 实例的setAudioEventListener方法开始传入OnAudioEventListener回调监听器的实现.

  		mNLUSession.setAudioEventListener(new OnAudioEventListener() {
  		                @Override
  		                public void onVolumeChanged(int percent, int volume) {
  		                // 当输入音量改变时，可以通过该回调通知开发者
  		                }
  		                @Override
  		                public void onPartialResult(String content) {
  		                // 在语音输入过程中，会通过该回调实时回传语音识别中途的识别结果
  		                }
  		                @Override
  		                public void onFinalResult(String content) {
  		                // 在一轮语音输入完成后，会通过该回调回传最终的语音识别结果
  		                }
  		            });
  	            

• OnWaitingInputListener:通过 NLUSession 实例的setWaitingInputListener方法开始传入OnWaitingInputListener回调监听器的实现。

  		mNLUSession.setWaitingInputListener(new OnWaitingInputListener() {
  		            @Override
  		            public void onImageNeeded(RobotAPI.ImageRequestType imageRequestType) {
  		                // 当用户当前的输入请求中含有和图片请求相关的意图时，会触发此回调，
  		                // 通过该回调通知开发者，当前需要进行一次图片理解相关的请求
  	
  		                // 场景举例：
  		                // 当用户对机器人说出“猜猜我是谁”时
  		                // Baidu NLU 引擎将会识别出用户当前这句话含有“猜猜我是谁”的意图
  		                // 而机器人需要通过上传用户照片来完成人脸识别
  		                // 因此会触发本回调来通知开发者当前用户的请求类型
  		                //
  		                // 例如“猜猜我是谁” 则对应一次人脸识别请求
  		                // 而“你猜这是什么”会对应一次物体识别请求
  		                //
  		                // 不同的请求类型对应不同的ImageRequestType，
  		                // 需要在mNLUSession.startImageQuery方法中作为对应参数传入，来完成一次图片识别请求
  		            }
  		        });

• OnSessionStateListener：通过 NLUSession 实例的setSessionStateListener方法开始传入OnSessionStateListener回调监听器的实现。

  		mNLUSession.setSessionStateListener(new OnSessionStateListener() {
  		            @Override
  		            public void onStateChanged(State state) {
  		                // 当NLUSession当前的状态改变时，通过该回调通知开发者
  		                // State枚举变量具体取值 可以参考接口速查手册
  		            }
  		        });

• OnErrorListener：通过 NLUSession 实例的setErrorListener方法开始传入OnErrorListener回调监听器的实现。

  		mNLUSession.setErrorListener(new OnErrorListener() {
  		            @Override
  		            public void onError(ErrorCode code) {
  		                // 当NLU请求发生错误时，通过该回调通知开发者
  		                // ErrorCode枚举变量具体取值 可以参考接口速查手册
  		            }
  		        });