# Android 语音评测(Evaluator)

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

# 类SpeechEvaluator

com.iflytek.cloud

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

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

# 语音评测类

语音评测是通过智能语音技术自动对发音水平进行评价、发音错误、缺陷定位和问题分析的软件系统。评音评测提供汉语、英语两种语言的评测，支持单字（汉语专有）、词语、句子和篇章（需开权限）朗读四种题型，请参考SpeechConstant.ISE_CATEGORY。
本类使用单例，调用者使用本类的对象，只需要通过createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)创建 一次对象后，便可一直使用该对象，直到通过调用destroy()进行单例对象销毁。调用者可通过createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)获取当前已经创建的单例。在销毁本类的单例对象后， 需要先通过createEvaluator(android.content.Context, com.iflytek.cloud.InitListener)再次创建单例对象，方可再使用。

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

# 嵌套类概要

从类继承的嵌套类/接口 com.iflytek.cloud.msc.module.SpeechInterface
com.iflytek.cloud.msc.module.SpeechInterface.ENGINE_MODE

# 方法概要

从类继承的方法 com.iflytek.cloud.msc.module.SpeechInterface
setParameter

从类继承的方法 java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

# 方法详细资料

# createEvaluator

public static SpeechEvaluator createEvaluator(android.content.Context context,
                                              InitListener listener)

创建单例对象

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

返回：
评测对象

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

# getEvaluator

public static SpeechEvaluator getEvaluator()

获取单例对象

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

返回:
评测对象

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

# startEvaluating(传入String)

public int startEvaluating(java.lang.String text,
                           java.lang.String textParams,
                           EvaluatorListener listener)

开始评测 调用此函数，开始评测。

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

在调用本函数开始评测前，通过setParameter(java.lang.String, java.lang.String)设置相 应的参数。

调用本函数开始评测后，通过SDK的录音机录取用户通过麦克风读入的音频（当 SpeechConstant.AUDIO_SOURCE 值>=0时），或由应用层调用 writeAudio(byte[], int, int)写入音频流，获取用于评测的音频。在完成音频 录入（包括麦克风或写音频流方式）后，通过调用stopEvaluating()告知SDK已完 成音频录入，或由SDK自带的VAD（Voice Activity Detection,静音抑制）自动结束音频录 入，见EvaluatorListener.onEndOfSpeech()。（关于写入音流方式的SDK自动结束 录入应注意的地方，请参考writeAudio(byte[], int, int)；VAD端点长度设置，请 参考setParameter(java.lang.String, java.lang.String)）。

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

参数:
text - 评测文本
textParams - 当前会话参数，见setParameter(java.lang.String, java.lang.String)支持的参数， 仅在当次会话生效，如无特殊要求，传入null即可。
listener - 监听器，获取状态和结果。

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

另请参阅:
writeAudio(byte[], int, int), createEvaluator(android.content.Context, com.iflytek.cloud.InitListener), getEvaluator(), stopEvaluating(), setParameter(java.lang.String, java.lang.String), cancel(),startEvaluating(byte[], String, EvaluatorListener)

# startEvaluating(传入byte)

public int startEvaluating(byte[] text,
                           java.lang.String textParams,
                           EvaluatorListener listener)

开始评测
传入byte[]类型的评测文本，开始评测会话。其他介绍请参考startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener)。

另请参阅:
startEvaluating(String, String, EvaluatorListener)

# writeAudio

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

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

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

当SDK回调EvaluatorListener.onEndOfSpeech()时，说明SDK已经通过VAD检测 到了静音末端点，应该立即停止写入音频数据。当SDK回调EvaluatorListener.onResult(com.iflytek.cloud.EvaluatorResult, boolean)返回完结果，或回调 EvaluatorListener.onError(com.iflytek.cloud.SpeechError)返回错误时，也应该停止当次会话的音频写 入。

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

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

返回:
是否成功写入数据，true 表示成功，false 表示有错误。发生错误时，通过EvaluatorListener.onError(com.iflytek.cloud.SpeechError)获取错误信息。
另请参阅:
startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), stopEvaluating(), EvaluatorListener

# isEvaluating

public boolean isEvaluating()

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

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

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

另请参阅:
startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), stopEvaluating(),cancel()

# stopEvaluating

public void stopEvaluating()

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

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

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

当应用调用本函数结束停止录音时，SDK不会再回调EvaluatorListener.onEndOfSpeech()。相反的，当SDK回调EvaluatorListener.onEndOfSpeech()时，应用层可不必再调用本函数通知SDK停止 录音。

另请参阅:
startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), writeAudio(byte[], int, int),EvaluatorListener.onEndOfSpeech(), cancel()

# cancel

public void cancel()

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

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

另请参阅:
startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), stopEvaluating()

# setParameter

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

设置参数<>br> 设置评测会话参数。

可设置参数有：
SpeechConstant.ISE_AUDIO_PATH 音频保存路径
SpeechConstant.ISE_CATEGORY 题型
SpeechConstant.LANGUAGE 语言
SpeechConstant.ISE_INTERRUPT_ERROR 中断报错
SpeechConstant.ISE_PARSED 是否已标注
SpeechConstant.ISE_SOURCE_PATH 音频源文件路径
SpeechConstant.ISE_USER_MODEL_ID 用户模型ID
SpeechConstant.KEY_REQUEST_FOCUS 音频焦点
SpeechConstant.NET_TIMEOUT 网络超时
SpeechConstant.RESULT_LEVEL 结果等级
SpeechConstant.SAMPLE_RATE 音频采样率
SpeechConstant.TEXT_BOM 文本字节顺序
SpeechConstant.TEXT_ENCODING 文本编码格式
SpeechConstant.VAD_ENABLE 启用VAD
SpeechConstant.VAD_BOS VAD 前端点
SpeechConstant.VAD_EOS VAD 后端点
SpeechConstant.AUDIO_SOURCE: 音频源
SpeechConstant.BLUETOOTH: 蓝牙录音
SpeechConstant.ENGINE_TYPE:引擎类型（目前评测仅支持在线模式）

当前评测支持未压缩的16位，单声道，采样率为16000或8000，字节 顺序为Little-Endian的Windows PCM音频。

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

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

返回:
true 设置成功，false 设置失败

# 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()

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

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

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

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

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

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

# 类EvaluatorResult

java.lang.Object
com.iflytek.cloud.EvaluatorResult

所有已实现的接口:

android.os.Parcelable

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

# 评测结果类

关于评测结果的各键值说明，请参考《Speech Evaluation API Documents》。

另请参阅:
EvaluatorListener.onResult(EvaluatorResult, boolean), SpeechEvaluator

# 嵌套类概要

从接口继承的嵌套类/接口 android.os.Parcelable

android.os.Parcelable.ClassLoaderCreator<T>, android.os.Parcelable.Creator<T>

###字段概要
字段

从接口继承的字段 android.os.Parcelable

CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE

# 构造器概要

构造器
构造器和说明
EvaluatorResult(java.lang.String result)
构造函数 应用层一般只用到EvaluatorListener.onResult(com.iflytek.cloud.EvaluatorResult, boolean)返回的评测结果对象， 可忽略此构造函数。

# 方法概要

所有方法

从类继承的方法java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

字段详细资料
CREATOR

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

构造器详细资料

# EvaluatorResult

public EvaluatorResult(java.lang.String result)

构造函数
应用层一般只用到EvaluatorListener.onResult(com.iflytek.cloud.EvaluatorResult, boolean)返回的评测结果对象， 可忽略此构造函数。

方法详细资料

# getResultString

public java.lang.String getResultString()

获取评测结果
获取xml格式的String字符串，请参考《Speech Evaluation API Documents》。

返回:
评测结果

# describeContents

public int describeContents()

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

# writeToParcel

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

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

# 接口EvaluatorListener

public interface EvaluatorListener

# 评测回调接口

通过实现此接口，获取当前评测的状态和结果

识别监听器，请参考RecognizerListener

合成监听器，请参考SynthesizerListener

# 方法概要

方法详细资料

# onVolumeChanged

void onVolumeChanged(int volume,
                     byte[] data)

音量变化
当开始识别，到停止录音（停止写入音频流）或SDK返回最后一个结果自动结束识别为止， SDK检测到音频数据（正在录音或写入音频流）的音量变化时，会多次通过此函数回调，告 知应用层当前的音量值。应用层可通过此函数传入的值变化，改变自定义UI的画面等。

参数:
volume - 当前音量值，范围[0-30]
data - 录音数据，格式请参考SpeechConstant.SAMPLE_RATE , SpeechConstant.AUDIO_FORMAT。此参数返回的数据，即使 SpeechConstant.NOTIFY_RECORD_DATA为false，也会返回。

另请参阅: SpeechEvaluator.startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), onBeginOfSpeech(), onEndOfSpeech(), SpeechEvaluator.stopEvaluating(), SpeechConstant.NOTIFY_RECORD_DATA

# onBeginOfSpeech

void onBeginOfSpeech()

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

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

另请参阅:
SpeechEvaluator.startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener), onEndOfSpeech()

# onEndOfSpeech

void onEndOfSpeech()

结束说话
在SDK检测到音频的静音端点时，回调此函数（在录音模式或写音频模式下都会回调， 应用层主动调用SpeechEvaluator.stopEvaluating()则不会回调此函数， 在识别出错时，可能不会回调此函数）。在此函数回调后，当前识别会话可能并没有结束， 识别结果可能还要等待一定的时间才会返回。

此函数回调后，应用层应立即停止调用SpeechEvaluator.writeAudio(byte[], int, int)写入音 频数据，(当音频源设置为音频流时（SpeechConstant.AUDIO_SOURCE为-1时) 否则，再通过SpeechEvaluator.writeAudio(byte[], int, int)写入的音频也会被忽略。

应用层可以通过此函数回调，告知用户，当次说话已结束，正在等待识别结果（若结果 未返回）等。

另请参阅:
onBeginOfSpeech(), onResult(com.iflytek.cloud.EvaluatorResult, boolean), onError(com.iflytek.cloud.SpeechError), SpeechEvaluator.writeAudio(byte[], int, int), SpeechEvaluator.stopEvaluating()

# onResult

void onResult(EvaluatorResult result,
              boolean islast)

返回结果
返回的结果可能为null，请增加判断处理。

一次会话的结果可能会多次返回（即多次回调此函数），通过参数2，判断是否是最后 一个结果，true时为最后一个结果，否则不是。当最后一个结果返回时，本次会话结束，录 音也会停止，在重新调用SpeechEvaluator.startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener)开启新的会话前， 停止调用SpeechEvaluator.writeAudio(byte[], int, int)写入音频(当音频源设置为音频流时 （SpeechConstant.AUDIO_SOURCE为-1时)。 当出现错误，或应用层调用SpeechEvaluator.cancel()取消当次会话时，在当次 会话过程可能不会回调此函数。

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

参数:
result - 结果数据
islast - 是否最后一次结果标记

另请参阅:
onError(com.iflytek.cloud.SpeechError), SpeechEvaluator.cancel(), EvaluatorResult

# onError

void onError(SpeechError error)

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

参数:
error - 错误类型

另请参阅: SpeechError, onResult(com.iflytek.cloud.EvaluatorResult, boolean), SpeechEvaluator.startEvaluating(java.lang.String, java.lang.String, com.iflytek.cloud.EvaluatorListener)

# onEvent

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

事件
扩展用接口，由具体业务进行约定。例如eventType为0显示网络状态，agr1为网络连接值。

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

另请参阅: SpeechEvent