语音服务
语音服务提供 API 调用设备“说话”、“听出”和“听懂”用户话语等语音相关的能力。作为语音服务访问代理的 SpeechManager 对象，提供了语音服务的主要 API，可通过 RobotContext 对象获取到。
SpeechManager speechManager = aRobotContext.getSystemService(SpeechManager.SERVICE);
在语音领域，存在 KWS（Keyword Spotting）、TTS（Text to Speech）、ASR（Automatic Speech Recognition）、NLU（Natural Language Understanding）与 NLP（Natural Language Processing）等术语，这些术语分别指代了语音领域内语音唤醒、语音合成、语音识别、自然语言理解与处理等细分的技术。语音服务用这些技术来实现，调用 SpeechManager API 实际上是对这些技术能力的调用。以下章节将逐项来介绍。
语音唤醒
当用户向设备说出唤醒词时，利用语音唤醒技术，设备可感知到用户在“叫自己”，随后可开启与用户的交互。这个过程称为“语音唤醒”。如果需要感知到语音唤醒，通过以下代码来实现。
WakeUpListener wakeUpListener = new WakeUpListener() { @Override public void onWakingUp(WakeUp wakeUp /* [1] */) { // 感知到用户朝设备说出唤醒词后将运行至此 } }; speechManager.registerWakeUpListener(wakeUpListener);
[1] WakeUp 对象描述了语音唤醒时刻的环境信息，具体包括：
| 属性 getter | 说明 |
|---|---|
| WakeUp.when | 唤醒时刻的时间戳，单位 ms。 |
| WakeUp.voiceDirection | 唤醒时刻的声音来源 |
如果不再需要感知语音唤醒，通过以下代码来实现。
speechManager.unregisterWakeUpListener(wakeUpListener);
语音合成
当需要设备像人类一样说话时，利用语音合成技术，可以将文本句子合成为人声并播放出来。该过程通过以下代码来实现。
promise /* [2] */ = speechManager.synthesize("你好，有什么可以为您服务？" /* [1] */) .progress(new ProgressCallback<SynthesisProgress>() { @Override public void onProgress(SynthesisProgress progress /* [3] */) { // 合成过程会多次运行至此 } }).done(new DoneCallback<Void>() { @Override public void onDone(Void aVoid) { // “你好，有什么可以为您服务？”“说”（播放）完之后运行至此 } }).fail(new FailCallback<SynthesisException>() { @Override public void onFail(SynthesisException e) { // 合成出错时运行至此 } });
[1] 输入待合成的文本句子，支持多句、携带标点。
[2] 返回等待合成进度与结果的异步对象，通过该对象可等待或监听进度与结果以及取消合成过程。具体用法参考 Promise。
[3] 异步回调的 SynthesisProgress 对象描述了语音合成的进度信息，具体包括：
| 属性 getter | 说明 |
|---|---|
| SynthesisProgress.remainingTimeMillis | 剩余播放时长 |
| SynthesisProgress.playProgress | 播放进度 |
| SynthesisProgress.audioBytes | 播放资源，有些平台可能不提供该资源 |
通过指定选项，可调整语音合成的行为。
SynthesisOption /*[1]*/ option = new SynthesisOption.Builder("你好，有什么可以为您服务？").build(); promise = speechManager.synthesize(option);
[1] SynthesisOption 对象通过 SynthesisOption.Builder 构建，使用说明如下：
| 方法 | 说明 | 默认值 |
|---|---|---|
| Builder.constructor(inputText) | 构造时必须传入合成的文本，不允许传入 NULL 对象或长度为 0 的字符串 | |
| Builder.setSpeakingSpeed(speakingSpeed) | 设置语速 | 0 |
| Builder.setSpeakingVolume(speakingVolume) | 设置音量大小 | 0 |
| Builder.setSpeakingVoiceId(speakingVoiceId) | 设置发言人，想了解系统都有哪些发言人，请参考语音设置 | 长度为 0 的字符串 |
| 常量 | 说明 |
|---|---|
| SynthesisOption.SPEAKING_VOLUME_MAX | 最大可设置音量 |
| SynthesisOption.SPEAKING_VOLUME_MIN | 最小可设置音量 |
| SynthesisOption.SPEAKING_SPEED_FAST | 较快语速 |
| SynthesisOption.SPEAKING_SPEED_NORMAL | 正常语速 |
| SynthesisOption.SPEAKING_SPEED_SLOW | 较慢语速 |
如果想知道当前的合成状态，通过以下代码实现。
boolean isSynthesizing = speechManager.isSynthesizing();
返回 true 表示正在合成。
语音识别
当用户朝设备说话时，利用语音识别技术，可以将语音转换成文本或指令。该过程通过如下代码来实现。
RecognitionOption /* [1] */ option = new RecognitionOption.Builder( RecognitionOption.MODE_SINGLE).build(); promise /* [2] */ = speechManager.recognize(option) .progress(new ProgressCallback<RecognitionProgress>() { @Override public void onProgress(RecognitionProgress recognitionProgress /* [3] */) { // 识别过程会多次运行至此 } }).done(new DoneCallback<RecognitionResult>() { @Override public void onDone(RecognitionResult recognitionResult /* [4] */) { // 识别过程完毕会运行至此，返回最终识别结果 } }).fail(new FailCallback<RecognitionException>() { @Override public void onFail(RecognitionException e) { // 识别出错时运行至此 } });
[1] 语音识别选项，可调整语音识别行为。通过 RecognitionOption.Builder 构建，使用说明如下：
| 方法 | 说明 | 默认值 |
|---|---|---|
| Builder.constructor(mode) | 构造时必须指定识别模式 | |
| Builder.setDistanceRange(distanceRange) | 识别场景 | 1: 近场识别 |
| Builder.setTimeoutMillis(timeoutMillis) | 识别超时时长 | 0: 不超时 |
| Builder.setUnderstandingOption(understandingOption) | 自然语言处理选项 | NULL |
| Builder.setExtension(extension) | 自定义的字段 | NULL |
| 常量 | 说明 |
|---|---|
| RecognitionOption.MODE_SINGLE | 单次识别：一般用于唤醒之后启动一次语音识别，得到结果后停止识别，等待下一次唤醒 |
| RecognitionOption.MODE_CONTINUOUS | 持续识别：启动唤醒之后不间断识别，识别到结果后返回数据，继续下一次识别 |
| RecognitionOption.DISTANCE_RANGE_NEAR_FIELD | 近场识别 |
| RecognitionOption.DISTANCE_RANGE_FAR_FIELD | 远场识别 |
| RecognitionOption.DISTANCE_RANGE_CLOSE_TALK | 超近场识别 |
[2] 返回等待识别进度与结果的异步对象，通过该对象可等待或监听进度与结果以及取消合成过程。具体用法参考 Promise。
[3] 异步回调的 RecognitionProgress 对象描述了语音识别的进度信息，具体包括：
| 属性 getter | 说明 |
|---|---|
| RecognitionProgress.decibel | 识别到的分贝 |
| RecognitionProgress.textResult | 识别到的语音转换成的文本 |
| RecognitionProgress.understandingResult | 识别到的语音经过自然语言处理的结果，详情请见 自然语言处理 |
| RecognitionProgress.progress | 识别进度 |
| 常量 | 说明 |
|---|---|
| RecognitionResult.began | 识别开始 |
| RecognitionResult.ended | 识别结束 |
| RecognitionProgress.PROGRESS_RECOGNIZING | 识别中 |
| RecognitionProgress.PROGRESS_RECOGNITION_TEXT_RESULT | 识别到文本 |
| RecognitionProgress.PROGRESS_UNDERSTANDING_RESULT | 自然语言处理过程中 |
[4] 异步回调的 RecognitionResult 对象描述了语音识别的最终结果，具体包括：
| 属性 getter | 说明 |
|---|---|
| RecognitionResult.text | 识别出的文本 |
| RecognitionResult.withUnderstandingResult | true: 识别结果经过自然语言处理 |
| RecognitionResult.understandingResult | 自然语言处理结果 |
单次识别，不想构建识别选项，也可以使用无参接口，具体使用过程如下：
promise = speechManager.recognize();
如果想知道当前的识别状态，通过以下代码实现。
boolean isRecognizing = speechManager.isRecognizing();
返回 true 表示正在识别。
自然语言处理
当需要设备像人类一样具有“听”的能力，利用自然语言处理技术，设备可以感知用户在和自己对话，随后开启与用户交互。该过程通过如下代码实现。
promise /* [2] */ = speechManager.understand("今天天气怎么样？" /* [1] */) .done(new DoneCallback<UnderstandingResult>() { @Override public void onDone(UnderstandingResult understandingResult /* [3] */) { // 自然语言处理完毕后将返回至此，此时可以调用语音合成接口与用户进行对话 } }).fail(new FailCallback<UnderstandingException>() { @Override public void onFail(UnderstandingException e) { // 自然语言处理出错时运行至此 } });
[1] 输入待进行自然语言处理的文本句子，支持多句、携带标点。
[2] 返回自然语言处理结果的异步对象，通过该对象获取结果以及取消处理过程。具体用法参考 Promise。
[3] 返回自然语言处理结果，具体包括：
| 属性 getter | 说明 |
|---|---|
| UnderstandingResult.sessionId | 会话 id，多轮对话时保持不变 |
| UnderstandingResult.source | 自然语言处理服务厂商 |
| UnderstandingResult.inputText | 需要理解的文本 |
| UnderstandingResult.language | 系统语言 |
| UnderstandingResult.version | 自然语言处理服务厂商库的版本 |
| UnderstandingResult.sessionIncomplete | false：会话完成 |
| UnderstandingResult.contextList | 上下文参数 |
| UnderstandingResult.intent | 意图，详情请见 SpeechIntent |
| SpeechIntent.action | 意图 |
| SpeechIntent.parameters | 词槽 |
| SpeechIntent.score | 匹配度 |
| UnderstandingResult.speechFulfillment | 自然语言处理后的播报信息，详情请见 SpeechFulfillment |
| SpeechFulfillment.type | 识别结果来源 |
| SpeechFulfillment.text | type = TYPE_TEXT |
| SpeechFulfillment.uri | type = TYPE_URI |
| SpeechFulfillment.audio | type = TYPE_AUDIO |
| SpeechFulfillment.audioType | 音频格式 |
| UnderstandingResult.fulfillmentList | 自然语言处理详细结果 |
通过指定选项，可调整自然语言处理的行为。
UnderstandingOption /* [1] */ option = new UnderstandingOption.Builder( "今天天气怎么样？").build(); promise = speechManager.understand(option);
[1] UnderstandingOption 对象通过 UnderstandingOption.Builder 构建，使用说明如下：
| 方法 | 说明 | 默认值 |
|---|---|---|
| Builder.constructor() | 无参构造 | 自然语言处理文本为长度为 0 的字符串 |
| Builder.constructor(inputText) | 构造时必须指定要执行自然语言处理的文本信息 | |
| Builder.setSessionId(sessionId) | 会话 id | 长度为 0 的字符串 |
| Builder.setVersion(version) | 自然语言处理服务厂商库的版本 | 长度为 0 的字符串 |
| Builder.setParameters(parameters) | 自定义参数 | JsonObjectString.EMPTY_OBJECT |
| Builder.setContextList(contextList) | 上下文参数 | JsonArrayString.EMPTY_ARRAY |
| Builder.setTimeoutMillis(timeoutMillis) | 理解超时时长 | 0 : 不超时 |
语音设置
需要获取或设置设备语音配置信息，可通过 SpeechSettings对象实现。
SpeechSettings speechSettings = speechManager.speechSettings();
| 方法 | 说明 |
|---|---|
| SpeechSettings.getConfiguration() | 获取语言配置信息 |
| SpeechSettings.setConfiguration(configutation) | 设置语言配置信息 |
| SpeechSettings.registerListener(listener) | 注册语音配置变更监听 |
| SpeechSettings.unregisterListener(listener) | 注销语音配置变更监听 |
设置语音相关的配置信息，可通过如下代码实现。
SpeechConfiguration /* [1] */ configutation = new SpeechConfiguration.Builder().build(); speechSettings.setConfiguration(configutation);
[1] 语音配置信息，通过 SpeechConfiguration.Builder 构建，使用说明如下：
| 方法 | 说明 | 默认值 |
|---|---|---|
| Builder.constructor() | 无参构造，不指定识别模式 | |
| Builder.setRecognitionMode(recognitionMode) | 识别模式 | 0：不知道的识别模式 |
| Builder.setSpeakingVoiceId(speakingVoiceId) | 发言人 | NULL |
| Builder.setSpeakingSpeed(speakingSpeed) | 语速 | 0 |
| Builder.setSpeakingVolume(speakingVolume) | 音量 | 0 |
| 常量 | 说明 |
|---|---|
| SpeechConfiguration.RECOGNITION_MODE_UNKNOWN | 不知道的识别模式 |
| SpeechConfiguration.RECOGNITION_MODE_SINGLE | 单次识别模式 |
| SpeechConfiguration.RECOGNITION_MODE_CONTINUOUS | 持续识别模式 |
| SpeechConfiguration.SPEAKING_VOLUME_MAX | 可设置的最大音量 |
| SpeechConfiguration.SPEAKING_VOLUME_MIN | 可设置的最小音量 |
| SpeechConfiguration.SPEAKING_SPEED_FAST | 较快语速 |
| SpeechConfiguration.SPEAKING_SPEED_NORMAL | 正常语速 |
| SpeechConfiguration.SPEAKING_SPEED_SLOW | 较慢语速 |
获取语音配置信息，可通过如下代码实现：
SpeechConfiguration configutation = speechSettings.getConfiguration();
需要感知语音配置变更，可通过如下代码实现：
SpeechConfigurationListener listener = new SpeechConfigurationListener() { @Override public void onConfigurationChanged(SpeechConfiguration speechConfiguration) { // 设备语音配置改变时将运行至此 } }; speechSettings.registerListener(listener);
不在需要感知语音配置变更，可通过如下代码实现：
speechSettings.unregisterListener(listener);