# Android 语音唤醒(Wakeuper)

这里介绍的是Android API关于语音唤醒(Wakeuper)的相关说明，点击右侧目录可快速找到相应文件。

# 类VoiceWakeuper

java.lang.Object
com.iflytek.cloud.msc.module.SpeechInterface
com.iflytek.cloud.VoiceWakeuper

public class VoiceWakeuper extends com.iflytek.cloud.msc.module.SpeechInterface

# 语音唤醒类

唤醒包括：单唤醒，多唤醒，特定人唤醒，唤醒识别。见SpeechConstant.IVW_SST。 其中，特定人唤醒暂不支持。

1、单唤醒：说出唤醒词，返回唤醒消息，其它情况无消息返回。

2、多唤醒：用户说出预定的几个唤醒词中任意一个，给用户反馈唤醒，并区分由什么词唤醒。

在唤醒时，单唤醒、多唤醒使用基本一致，只需要通过setParameter(java.lang.String, java.lang.String) 设置资源路径 SpeechConstant.IVW_RES_PATH等参数后， 开始唤醒即可。

3、唤醒识别：说出预定义的唤醒词接着识别词，引擎给出唤醒识别结果。 例如，“打电话给XXX”；其中“打电话给”是固定的，用唤醒引擎检测，是唤醒词； “XXX”是人名，不固定，用识别引擎检测；当用户说出“打电话给XXX”时，引擎返 回唤醒识别结果。唤醒识别在开始识别前，需要设置本地语法（目前不支持云端语法）。

由于唤醒开始后，会一直占用MIC（音频源为MIC时）， 开发安卓手机的唤醒应用时，应该通过实现BroadcastReceiver.onReceive(android.content.Context, android.content.Intent), 监听系统广播Intent.ACTION_SCREEN_ON， 在屏幕点亮时，通过cancel()取消会话；监听系统广播 Intent.ACTION_SCREEN_OFF，在屏幕锁住时，通过startListening(com.iflytek.cloud.WakeuperListener) 开启唤醒会话。这样在屏幕点亮时，使用其他应用就不会出现由于唤醒在占用MIC，而无法使用MIC的问题。

另外，由于唤醒一般在幕屏息灭时起作用，就要求集成唤醒功能时，应该作为服务Service， 运行在后台，避免由于系统清理应用，而导致唤醒不起作用的问题。

本类使用单例，调用者使用本类的对象，只需要通过createWakeuper(android.content.Context, com.iflytek.cloud.InitListener)创建 一次对象后，便可一直使用该对象，直到通过调用destroy()进行单例对象销毁。调 用者可通过getWakeuper()获取当前已经创建的单例。在销毁本类的单例对象后， 需要先通过createWakeuper(android.content.Context, com.iflytek.cloud.InitListener)再次创建单例对象，方可再使用。

在当前应用生命周期第一次使用本类的任何函数前，须先调用SpeechUtility.createUtility(android.content.Context, java.lang.String)进行SDK初始化。

另请参阅:
SpeechUtility.createUtility(android.content.Context, java.lang.String)

# 嵌套类概要

# 方法概要

# 所有方法

# 方法详细资料

# createWakeuper

public static VoiceWakeuper createWakeuper(android.content.Context context,
                                           InitListener listener)

创建单例对象 使用此函数创建一个本类单例对象。当成功创建一次单例对象后，可一直使用此对象， 直到调用destroy()销毁已创建的单例对象为止。若在当前应用生命周期内调用destroy()前再次调用本函数，则直接返回已创建的单例对象。可通过getWakeuper()获取已创建的单例对象。

返回:
唤醒对象

另请参阅:
destroy(), getWakeuper()

# getWakeuper

public static VoiceWakeuper getWakeuper()

获取单例对象
通过函数获取已创建的单例对象。当单例对象未创建时，将返回null，此时应先通过createWakeuper(android.content.Context, com.iflytek.cloud.InitListener)创建单例对象。

返回:
唤醒对象

另请参阅:
createWakeuper(android.content.Context, com.iflytek.cloud.InitListener), destroy()

# queryResource

public int queryResource(java.lang.String resourcePath, RequestListener listener) 查询唤醒词资源
调用此函数，查询唤醒词优化资源，能够查询的前提是应用开启唤醒闭环优化， 并且云端成功训练出唤醒词优化资源，调用此函数发送查询请求，若有优化的模型 资源，会返回开发者相应的资源下载链接，如果开发者未开启唤醒闭环优化功能， 此函数会通过回调监听返回相应错误码

调用此函数仅仅模型查询，下载模型资源请参考downloadResource(java.lang.String, java.lang.String, java.lang.String, com.iflytek.cloud.util.FileDownloadListener) 注：该接口仅加强型支持，基础性暂无优化功能

参数:
resourcePath - 唤醒资源路径
listener - 查询回调监听

返回:
是否启动查询成功，ErrorCode.SUCCESS表示成功，其他值表示有错误， 具体错误码，请参考ErrorCode。

另请参阅:
downloadResource(java.lang.String, java.lang.String, java.lang.String, com.iflytek.cloud.util.FileDownloadListener)

# downloadResource

public int downloadResource(java.lang.String downloadUrl,
                            java.lang.String filePath,
                            java.lang.String fileMd5,
                            FileDownloadListener listener)

下载唤醒词资源
调用此函数，通过参数传入下载url和文件保存路径，可下载资源至相应路径目录下。 并通过回调监听返回当前资源的下载状态

调用此函数仅支持下载，查询模型资源请参考queryResource(java.lang.String, com.iflytek.cloud.RequestListener) 注：该接口仅加强型支持，基础性暂无优化功能

参数:
downloadUrl - 资源下载链接
filePath - 下载文件保存路径
fileMd5 - 资源md5值，用于检验
listener - 文件下载回调监听

返回:
是否启动下载成功，ErrorCode.SUCCESS表示成功，其他值表示有错误， 具体错误码，请参考ErrorCode。

另请参阅:
queryResource(java.lang.String, com.iflytek.cloud.RequestListener)

# startListening

public int startListening(WakeuperListener listener)

开始录音
调用此函数，开始唤醒和注册会话。

目前SDK不支持多线程，所以在调用本函数开始一次会话后，直到结束前(结果返回 完毕，或出现错误)，不能再调用本函数开始新的会话（否则当前会话将自动结束）。 一次会话，即从会话开始，到结束为止。

在调用本函数开始会话前，通过 设置相应的参数。包括 唤醒资源路径， 唤醒业务类型等，参考setParameter(java.lang.String, java.lang.String)。

调用本函数开始会话后，通过SDK的录音机录取用户通过麦克风读入的音频（当 SpeechConstant.AUDIO_SOURCE 值>=0时），或由应用层调用writeAudio(byte[], int, int)写入音频流，获取用于唤醒或注册的音频。在完成音频 录入（包括麦克风或写音频流方式）后，通过调用stopListening()告知SDK已完 成音频录入。

在开始会话后，如果通过SDK的录音机录取用户通过麦克风读入的音频（当 SpeechConstant.AUDIO_SOURCE 值>=0时），直到用户读到唤醒词而 唤醒成功(非持续唤醒时)， 或取消会话，或出现出错WakeuperListener.onError(com.iflytek.cloud.SpeechError)为止，录音将一直持续。

可通过cancel()取消当前的会话。

唤醒默认启动不抢占音频焦点SpeechConstant.KEY_REQUEST_FOCUS, 开发者如需请通过setParameter(java.lang.String, java.lang.String)设置为抢占焦点

另请参阅: createWakeuper(android.content.Context, com.iflytek.cloud.InitListener), getWakeuper(), stopListening(), setParameter(java.lang.String, java.lang.String), cancel()

# writeAudio

public int writeAudio(byte[] buffer,
                      int offset,
                      int length)

写入录音数据
通过调用此函数，把音频数据传给SDK。

仅在SpeechConstant.AUDIO_SOURCE值为-1时，需要通过调用本函数，把 音频数据传给SDK。在写入音频数据前，应先通过startListening(com.iflytek.cloud.WakeuperListener) 开启会话。在结束录音数据写入后，调用startListening(com.iflytek.cloud.WakeuperListener)告知应用层，当前会话 音频数据已全部写入。

非持续唤醒下，当SDK回调 WakeuperListener.onResult(com.iflytek.cloud.WakeuperResult)返回完结果，或任意模式下，回调WakeuperListener.onError(com.iflytek.cloud.SpeechError)返回错误时，会话结束，应该停止当次会话的音频写入。

支持的音频格式，请参考setParameter(java.lang.String, java.lang.String)的参数说明。

参数:
buffer - 要写入的录音数据缓存
offset - 实际音频在传入缓存的起始点
length - 音频数据长度

返回:
是否成功写入数据，ErrorCode.SUCCESS表示成功，其他值表示有错误， 具体错误码，请参考ErrorCode。

另请参阅:
startListening(com.iflytek.cloud.WakeuperListener), stopListening(), WakeuperListener

# stopListening

public void stopListening()

停止录音
调用本函数告知SDK，当前会话音频已全部录入。

在识别唤醒时，调用本函数后，已录入的音频还在继续识别，结果不会马上就返回，当前会 话还在继续，直到结果返回完毕，或出现错误。

在单次或持续唤醒时，本函数与cancel()相当，即调用本函数后，会话自动结束，不会再有结果返回。

要取消会话，请参考cancel()](#cancel)函数。

另请参阅: startListening(com.iflytek.cloud.WakeuperListener), writeAudio(byte[], int, int), WakeuperListener, cancel()

# isListening

public boolean isListening()

是否在会话中
通过此函数，获取当前SDK是否正在进行会话。应用层可通过此函数，查询能否 开始一路新的会话等。

调用了stopListening()停止录音后，如果会话未出现错误或返回最后的结果， 当前状态依然处于会话中，即本函数会返回true。如果调用cancel()](#cancel)取消了会话， 则当前状态处于不在会话中。

返回:
会话状态，true：正在会话中；false：不在会话中。

另请参阅:
startListening(com.iflytek.cloud.WakeuperListener), stopListening(), cancel()

# cancel

public void cancel()

取消会话
通过此函数取消当前的会话。

在会话被取消后，当前唤醒会话结束，未返回的结果将不再返回。

另请参阅: startListening(com.iflytek.cloud.WakeuperListener), stopListening()

# setParameter

public boolean setParameter(java.lang.String key,
                            java.lang.String value)

参数设置
可设置的参数有：
SpeechConstant.IVW_SST：唤醒类务类型，必须；
SpeechConstant.IVW_THRESHOLD：唤醒门限值；
SpeechConstant.KEEP_ALIVE：持续唤醒；
SpeechConstant.IVW_RES_PATH：唤醒资源路径，必须；
SpeechConstant.ENGINE_TYPE：引擎类型；（在唤醒里，引擎类型 仅作用于唤醒识别时的识别部分，而唤醒部分始终在离线模式。）
SpeechConstant.IVW_NET_MODE：唤醒闭环优化模式；
SpeechConstant.SAMPLE_RATE：唤醒音频采样率；
SpeechConstant.LOCAL_GRAMMAR：本地语法ID；
SpeechConstant.AUDIO_SOURCE：音频源，使用 AIMIC 时必须；
SpeechConstant.BLUETOOTH: 蓝牙录音
SpeechConstant.RESULT_TYPE：识别结果类型；
SpeechConstant.KEY_REQUEST_FOCUS：音频焦点；
SpeechConstant.IVW_CHANNEL_NUM: 唤醒音频路数，使用 AIMIC 时必须；
SpeechConstant.IVW_AUDIO_PATH: 唤醒音频保存路径；
SpeechConstant.IVW_ALSA_CARD: ALSA 录音卡号；
SpeechConstant.IVW_ALSA_RATE: ALSA 录音采样率；
目前唤醒仅支持未压缩的16位，单声道，采样率为16000，字节顺序为 Little-Endian的Windows PCM音频。另参考SpeechConstant.IVW_ALSA_RATE说明。
唤醒识别若使用本地识别时，需要有相应的资源文件才支持对应的采样率的音频识别。

覆盖:
setParameter 在类中 com.iflytek.cloud.msc.module.SpeechInterface

参数:
key - 参数名称
value - 参数值

返回:
true 设置成功，否则设置失败

另请参阅:
startListening(com.iflytek.cloud.WakeuperListener), getParameter(java.lang.String)

# getParameter

public java.lang.String getParameter(java.lang.String key)

获取参数
获取指定的参数的当前值。

某些有默认的值的参数，如SpeechConstant.SAMPLE_RATE，在应用层未 调用setParameter(String, String)来设置参数值前，可能获取到的是null值， 但在实际会话会始时，SDK会使用默认值传给服务器。

覆盖:
getParameter 在类中 com.iflytek.cloud.msc.module.SpeechInterface

参数:
key - 参数名称，所有支持参数，参考setParameter(String, String)

返回:
参数值，值意义，参考SpeechConstant对各参数的说明。

另请参阅:
setParameter(String, String)

# destroy

public boolean destroy()

销毁单例对象
通过本函数，销毁由createWakeuper(android.content.Context, com.iflytek.cloud.InitListener)创建的单例对象。

在调用本函数进行销毁前，应先保证当前不在会话中，否则，本函数将尝试取消当前 会话，并返回false，此时销毁失败。关于当前是否在会话中，请参考函数isListening()。若销毁失败，请在取消当前会话后，再次调用本函数重试。

当本函数返回true时，销毁成功。此时，之前创建的单例对象已不能再使用，否则， 将会报错。此时需要再使用，应先通过createWakeuper(android.content.Context, com.iflytek.cloud.InitListener)创建一个新的单例 对象。

覆盖:
destroy 在类中 com.iflytek.cloud.msc.module.SpeechInterface

返回:
销毁成功：true；销毁失败：false。

另请参阅:
createWakeuper(android.content.Context, com.iflytek.cloud.InitListener), cancel()

# 类WakeuperResult

java.lang.Object
com.iflytek.cloud.WakeuperResult

所有已实现的接口:
android.os.Parcelable

public class WakeuperResult
extends java.lang.Object
implements android.os.Parcelable

# 唤醒结果类

唤醒结果：以json格式的字符串返回，其中各键值说明如下： sst: 业务类型，包括wakeup（唤醒）, enroll（注册）;参考SpeechConstant.IVW_SST id: 唤醒词id； score: 得分；参考SpeechConstant.IVW_THRESHOLD bos: 唤醒音频的前端点； eos: 唤醒音频的后端点； angle: 唤醒角度（仅在SpeechConstant.IVW_CHANNEL_NUM大于0时出现）；

唤醒注册结果：暂不支持。

另请参阅: WakeuperListener

# 嵌套类概要

# 字段概要

字段

# 构造器概要

构造器

# 方法概要

所有方法

# 字段详细资料

# CREATOR

public static final android.os.Parcelable.Creator<WakeuperResult> CREATOR

# 构造器详细资料

# WakeuperResult

public WakeuperResult(java.lang.String result,
                      byte[] buffer)

# WakeuperResult

public WakeuperResult(android.os.Parcel in)

# WakeuperResult

public WakeuperResult(java.lang.String result)

构造函数
应用层只通过WakeuperListener.onResult(com.iflytek.cloud.WakeuperResult)得到结果，可忽略此类的构造函数。

参数:
result - json格式的结果

# 方法详细资料

# describeContents

public int describeContents()

指定者:
describeContents 在接口中 android.os.Parcelable

# getResultString

public java.lang.String getResultString()

获取唤醒结果
结果各参数请参考类说明。

返回:
唤醒结果

# getBuffer

public byte[] getBuffer()

获取唤醒音频
唤醒音频，仅在SpeechConstant.IVW_CHANNEL_NUM大于0时， 有意义，其他时侯为null。

返回:
唤醒音频

# writeToParcel

public void writeToParcel(android.os.Parcel dest,
                          int flags)

指定者:
writeToParcel 在接口中 android.os.Parcelable

# 接口WakeuperListener

public interface WakeuperListener

唤醒回调接口
通过实现此接口，获取唤醒的状态和结果。

另请参阅: VoiceWakeuper

# 方法概要

所有方法

# 方法详细资料

# onBeginOfSpeech

void onBeginOfSpeech()

开始说话
在录音模式(音频源参数设为 > -1时 )下， 调用开始录音函数后，会自动开启系统的录音 机，并在录音机开启后，会回调此函数（这中间的过程应该在几毫秒内，可以忽略，除非系 统响应很慢）。

应用层可通过此函数回调，告知用户，当前可开始说话。若应用层使用的是声音提示， 则应该在调用开始录音函数前，提放提示音， 并在提示音非静音数据播放结束时，调用 开始录音函数，开始录音。若太早调用，则 可能会把提示音录进要识别的音频中，若太晚，则可能会漏掉部分用户说话的音频。

另请参阅:
VoiceWakeuper.startListening(com.iflytek.cloud.WakeuperListener)

# onResult

void onResult(WakeuperResult result)

返回结果
返回的结果可能为null，请增加判断处理。当出现onError(com.iflytek.cloud.SpeechError)错误，或取消会话时， 可能不会再回调此函数返回结果。

单次唤醒：在SpeechConstant.KEEP_ALIVE参数设为非持续唤醒时，若录入的音频 与唤醒资源匹配，返回一次结果，并自动停止录音，并结束当次会话。

持续唤醒：在SpeechConstant.KEEP_ALIVE参数设为持续唤醒时，若录入的音频 与唤醒资源匹配，返回结果，录音继续，会话也在继续，直到应用主动调用VoiceWakeuper.stopListening()停止录音，或VoiceWakeuper.cancel()取消 会话，或出现onError(com.iflytek.cloud.SpeechError)错误，而导致会话结束为止。即，会多次返回结果——若 录音数据与唤醒资源匹配。

唤醒识别：通过此函数返回一次唤醒结果，然后再通过onEvent(int, int, int, android.os.Bundle)返回一次识别结果， 并自动停止录音，结束会话。参考onEvent(int, int, int, android.os.Bundle)。

特定人唤醒注册：根据设置的注册次数，返回 与之相同次数的结果。

识别采用边录边上传的分次上传音频数据方式，可能在结束录音前，就有结果返回。

参数:
result - 结果数据

另请参阅:
onError(com.iflytek.cloud.SpeechError), VoiceWakeuper.cancel(), WakeuperResult, VoiceWakeuper.writeAudio(byte[], int, int), onEvent(int, int, int, android.os.Bundle)

# onError

void onError(SpeechError error)

错误回调
当此函数回调时，说明当次会话出现错误，会话自动结束，录音也会停止。应在再次调用VoiceWakeuper.startListening(com.iflytek.cloud.WakeuperListener)开启新的会话前， 停止调用VoiceWakeuper.writeAudio(byte[], int, int)写入音频(当音频源设置为音频流时 （SpeechConstant.AUDIO_SOURCE为-1时)。

参数:
error - 错误类型

另请参阅:
SpeechError, onResult(com.iflytek.cloud.WakeuperResult), VoiceWakeuper.startListening(com.iflytek.cloud.WakeuperListener)

# onEvent

void onEvent(int eventType,
             int arg1,
             int arg2,
             android.os.Bundle obj)

事件
扩展用接口，唤醒的主要事件是音频事件，以及在唤醒识别时，返回识别结果（在唤醒结果之后返回）。

识别结果事件ID（消息类型）为SpeechEvent.EVENT_IVW_RESULT，通过第二 个参数，返回是否最后一个识别结果（0为否，1为是）。结果内容则从第四个参数 中获取，通过BaseBundle.get(String)，指定参数为 SpeechEvent.KEY_EVENT_IVW_RESULT,获取RecognizerResult对象。

音频事件ID（消息类型）为 SpeechEvent.EVENT_RECORD_DATA， 若 SpeechConstant.IVW_CHANNEL_NUM 不为0，则在唤醒后返回 从多声道的原始音频中，分解出来用于识别业务的音频（另参考SpeechConstant.IVW_RESET_AIMIC）； 否则返回当前设备录音的音频（SpeechConstant.NOTIFY_RECORD_DATA 参数为真时）。

应用可以使用音频事件返回的音频，调用 SpeechRecognizer 进行识别等。

参数:
eventType - 消息类型
arg1 - 参数1
arg2 - 参数2
obj - 消息内容

另请参阅:
SpeechEvent.EVENT_IVW_RESULT, SpeechEvent.KEY_EVENT_IVW_RESULT, SpeechEvent.EVENT_RECORD_DATA, SpeechConstant.IVW_RESET_AIMIC, RecognizerResult, onResult(com.iflytek.cloud.WakeuperResult)

# onVolumeChanged

void onVolumeChanged(int volume)

音量变化
当开始录音，到停止录音（停止写入音频流）为止， SDK检测到音频数据（正在录音或写入音频流）的音量变化时，会多次通过此函数回调，告 知应用层当前的音量值。

参数:
volume - 当前音量值，范围[0-30]

另请参阅:
VoiceWakeuper.startListening(com.iflytek.cloud.WakeuperListener), onBeginOfSpeech(), VoiceWakeuper.stopListening()